VS Code Version

Scimax VS Code requires Visual Studio Code version 1.85 or later.

Optional Dependencies

While Scimax VS Code works out of the box, some features require additional software:

From VS Code Marketplace

1. Open VS Code

2. Press `C-S-X' to open the Extensions view

3. Search for "Scimax"

4. Click Install

From VSIX File

1. Download the .vsix file from the GitHub Releases page

2. Open VS Code

3. Press `C-S-X' to open the Extensions view

4. Click the `...' menu (top right)

5. Select "Install from VSIX..."

6. Choose the downloaded file

From Source (GitHub)

The source code is available at [[https://github.com/jkitchin/scimax_vscode]].

To build and install from source:

1. Clone the repository:

2. Install dependencies and build:

3. Install the generated VSIX:

⚠️ Updating the Extension

To update to the latest version from within VS Code:

1. Open the Command Palette (`C-S-P')

2. Run "Scimax: Update from GitHub"

3. Confirm the update when prompted

4. Reload VS Code when prompted

This downloads and installs the latest release from GitHub automatically.

Verify Installation

After installation:

1. Open the Command Palette (`C-S-P')

2. Type "Scimax"

3. You should see Scimax commands listed

Opening an Org File

Org files use the .org extension. To create your first file:

1. Press `C-n' to create a new file (note s-n on Mac)

2. Save it with `C-s' and give it a `.org' extension (e.g., `notes.org')

3. The file will automatically use org-mode syntax highlighting

Creating Your First Document

Type the following to create a basic document structure:

,#+TITLE: My First Document
,#+AUTHOR: Your Name
,#+DATE: 2026-01-13

,* Introduction

This is my first Scimax VS Code document.

,** A Subsection

Content under the subsection.

,* Tasks

,** TODO Learn Scimax VS Code
DEADLINE: <2026-01-20 Mon>

,** DONE Install the extension
CLOSED: [2026-01-13 Mon]

,* Code Example

,#+BEGIN_SRC python :results output
print("Hello from Scimax VS Code!")
,#+END_SRC

Basic Navigation

Outline View

The Outline view in VS Code's sidebar shows your document structure:

1. Click the Outline icon in the sidebar (or press `C-S-O')

2. See all headings hierarchically

3. Click a heading to jump to it

Tree Views

Scimax VS Code adds several tree views to the Explorer sidebar:

Status Bar

The status bar shows:

• Current journal date (when in journal files)

• Kernel status (when using Jupyter)

Hydra Menus

Hydra menus provide discoverable access to commands:

• `C-c m' - Open main menu

• `C-c C-m' - Open context-sensitive menu

• C-M-V - Open database/search menu

Menus show available commands with their keybindings. Press a key to execute a command or `Escape' to close the menu.

Document Commands

Source Block Commands

Export Commands

Navigation Commands

Help Commands

Essential Settings

{
  // Enable speed commands (single-key at heading start)
  "scimax.speedCommands.enabled": true,

  // Set your journal directory
  "scimax.journal.directory": "~/Documents/journal",

  // Configure bibliography files for citations
  "scimax.ref.bibliographyFiles": ["~/references.bib"],

  // Enable image overlays
  "scimax.imageOverlays.enabled": true,

  // Auto-index files for search
  "scimax.db.autoIndex": true
}

Python Configuration

If Python isn't automatically detected:

{
  "scimax.literate.pythonPath": "/usr/bin/python3"
}

LaTeX Configuration

For PDF export:

{
  "scimax.latexLivePreview.compiler": "pdflatex",
  "scimax.latexLivePreview.useLatexmk": true
}

Similar Features

Different Behaviors

• Completion: Uses VS Code's completion system, triggered automatically

• Folding: Uses VS Code's native folding with org-specific ranges

• Buffer management: VS Code tabs instead of Emacs buffers

• Customization: JSON settings instead of Emacs Lisp

Missing Features

Some advanced Emacs features may not be available:

• Org-mode's full capture/refile system (simplified version available)

• Column view

• Some specialized agenda views

• Custom link types (limited set supported)

Code Blocks Not Executing

1. Check that the language is installed (e.g., Python, Node.js)

2. Verify the language is in your PATH

3. Check the Output panel (`C-S-U') for errors

4. Run `scimax.org.checkExecutors' to verify available executors

LaTeX Preview Not Working

1. Ensure LaTeX is installed (`latex --version' in terminal)

2. Check that dvipng or dvisvgm is available

3. Run `scimax.checkLatexTools' to verify installation

Search Not Finding Results

1. Run `scimax.db.reindex' to rebuild the search index

2. Check that files aren't in excluded patterns

3. Verify the search scope (`scimax.db.setScope')

Journal Not Opening

1. Check that `scimax.journal.directory' is set correctly

2. Ensure the directory exists and is writable

3. Try creating the directory manually if needed

Disable Option-Key Accents on macOS

M- combinations may produce accented characters instead of the intended commands on a Mac. To fix this, you can change your keyboard input settings:

• Add Unicode Hex Input

System Settings → Keyboard → Input Sources → click "+" → select Other → add "Unicode Hex Input"

• Remove U.S. Input (optional)

System Settings → Keyboard → Input Sources → select "U.S." → click "−"

• Navigation

• Previous: Documentation Index

• Index: Documentation Index

• Next: Basic Syntax