Design Philosophy

Commands that make sense in Markdown write Markdown. TODO keywords, priorities, SCHEDULED/DEADLINE lines and hashtags use the same syntax as org (see Tasks, Planning and Hashtags in Markdown). Features that only exist in org syntax (clocking, property drawers, tangling) stay org-only rather than writing org text that Markdown renderers show literally.

✅ Document Outline and Navigation

Markdown files have full support for the VS Code outline view and breadcrumb navigation.

What Counts as a Heading

A heading is a line that starts with one to six # characters followed by a space. Every heading command, speed key, fold, outline entry and refile target ignores # lines in these places, because they are not headings there:

• inside fenced code blocks (``` or ~~~), such as a # comment in Python

• in YAML front matter at the top of the file (between --- lines)

• inside HTML comments (<!-- ... -->)

So a speed key pressed at the start of # install deps inside a ```bash block types the letter instead of acting on a section, and moving or demoting a section moves its code blocks with it untouched.

Setext headings (a title underlined with ==== or ---) are not recognized; use # headings. A trailing ## sequence or a Pandoc {#id} attribute is not part of the heading title.

✅ Heading Navigation

All heading navigation commands work in Markdown:

Speed commands (when cursor is at column 0 of a heading line):

Heading Manipulation

Change heading levels and move subtrees:

Markdown has six heading levels, so demoting stops at ######.

Subtree Operations

All subtree operations work in Markdown:

Refile and archive (speed key a) adjust heading levels the same way yank does.

## Target Section

<!-- Yank a subtree that was cut from a different level -->
<!-- Headings are automatically adjusted to match ## level -->

Speed Commands

Speed commands work at the beginning of Markdown headings (column 0 of a heading line, see What Counts as a Heading).

The keys 1 2 3 0 (priority), : (tags), e (effort), P (property) and I O (clock in/out) are for org headings; see Features Not Available in Markdown.

✅ Folding

Markdown headings support folding via the standard VS Code folding mechanism:

• Press Tab on a heading to cycle fold state

• Press Shift+Tab anywhere for global fold cycling

• Use the fold icons in the gutter

Fenced code blocks and Pandoc fenced divs (::: {.callout-note} ... :::, nested to any depth, and MyST :::{note} fences) fold as well.

✅ Text Markup and Comments

The markup commands write Markdown syntax in Markdown files:

M-; (scimax.org.dwimComment) comments lines with HTML comments (<!-- ... -->), using VS Code's Toggle Line Comment. In org it adds =# =, which in Markdown would make the line a heading.

Lists and Return

Return (DWIM return) in a Markdown file:

• On a list item (-, +, * or 1.), starts the next item; on an empty item, removes it. * at column 0 is a list bullet in Markdown, not a heading.

• On a checkbox item (- [ ] ...), starts a new checkbox item.

• In a table, moves to the next row.

• Inside a fenced code block, front matter or an HTML comment, inserts a plain newline, so - key: value in a YAML block and | pipes in code are left alone.

C-c C-c on a checkbox (scimax.markdown.toggleCheckbox) toggles it in Markdown and Quarto files.

Links

C-c C-o follows:

• URLs: [docs](https://example.com)

• other files, relative to the current file: [notes](../notes.md)

• headings in this file: [Methods](#methods)

• headings in another file: [setup](install.md#setup); in an org file the anchor is a CUSTOM_ID

Heading anchors are GitHub-style: lower case, punctuation removed, spaces replaced by hyphens, so ## Results & Discussion is #results--discussion. A Pandoc attribute such as # Intro {#sec-intro} also works as #sec-intro.

To link to a heading, put the cursor on it and press C-c l, then press C-c C-l where the link should go. In the same file this inserts [Methods](#methods); in another Markdown file, [Methods](notes.md#methods). Org-style [[...]] links in Markdown files still work with C-c C-o.

Tables

Org table editing works on GitHub-flavored Markdown pipe tables:

| Name | Count | Price |
|:-----|:-----:|------:|
| a    |   1   |  2.50 |

• Tab / S-Tab move between cells and realign the table.

• Alignment colons in the delimiter row are kept: :--- left, :---: center, ---: right. Cells are padded to match, and the alignment moves with its column when you move, insert or delete columns.

• The header row and the delimiter row stay at the top. Inserting a row below the header puts it under the delimiter row, moving rows skips over the delimiter, and deleting the header or the delimiter is refused.

• C-c - (insert separator) creates the delimiter row when the table has none, and otherwise does nothing, since GFM tables have only one.

Rows must start with |. Tables written without the outer pipes (a | b / --|--) are not recognized. Table formulas (#+TBLFM:) are org-only.

Code Block Support

Markdown fenced code blocks support:

• Detection and navigation

• Execution via Babel/Jupyter

• Block manipulation (split, merge, clone, kill, move)

```python
print("Hello from Python")
```

~~~javascript
console.log("Hello from JS");
~~~

```{python}
print("Quarto/Pandoc chunk form")
```

```python
print(6 * 7)
```

<!-- results -->
```
42
```
<!-- /results -->

```python
data = [3, 1, 4, 1, 5]
```

```python
print(sorted(data))
```

```python
sorted(data)[-1]
```

```python :session none
print("a fresh Python, without data")
```

```python :results value
sum(data)
```

Tasks and Planning

Markdown files have two kinds of task: TODO headings and checkbox tasks. Checkbox tasks carry their dates as @due(...) / @scheduled(...) tags, and C-c C-s / C-c C-d above the first heading insert those tags.

- [ ] Email reviewers @due(2026-01-22) @project(paper) #urgent
- [x] Upload data @closed(2026-01-10)

Export

C-c C-e (scimax.markdown.exportMenu) exports the Markdown file with Pandoc to HTML, PDF, LaTeX or Word, writing the output next to the source with the new extension. This works for .md, .markdown and other Markdown extensions; the export never writes over the source file. Code blocks are not executed during export.

Markdown Preview

VS Code's Markdown preview (Cmd+Shift+V, Cmd+K V to the side) gets these additions from Scimax:

• MyST directives and roles (Jupyter Book) render as callouts, figures and highlighted code instead of raw :::{...} text. See MyST Preview.

• Reveal Cursor in Markdown Preview (scimax.marp.revealInPreview) scrolls the preview so the element on the cursor line is at its top, opening a preview to the side if none is showing. It relies on markdown.preview.scrollPreviewWithEditor (on by default).

• Export to PDF: the export button in the preview's title bar (scimax.markdown.preview.exportPdf, also in the Command Palette while the preview has focus) saves the previewed file as name.pdf next to it and opens it. It uses Pandoc and LaTeX, like Markdown → PDF (see Markdown File Export), so the PDF is typeset rather than a copy of the preview's look; unsaved changes are included. A Marp deck exports its slides with Marp instead, as p in the Marp export menu does. The other markdown export commands and the export menu also work from the preview.

Files with marp: true in their front matter are previewed as slides, with citations rendered; see Marp Slides.

Equation Hover

Hovering LaTeX math in a Markdown or Quarto file shows it typeset, as in org files: $...$, \(...\), $$...$$ and \[...\] (on one line or across lines), and math environments such as \begin{equation}. Math in code fences, inline code, front matter and HTML comments is skipped. The hover uses the org LaTeX renderer, so it needs latex and dvisvgm (or dvipng), and scimax.latexPreview.enabled turns it off. Equations are shown without numbers. See LaTeX Preview.

Code chunks

Scimax recognizes Quarto's chunk fences (```{python}, ```{r, echo=FALSE}) as code blocks, along with plain fences, ```{.python} display blocks and ```{=html} raw blocks. Blocks that scimax inserts in a .qmd file use the chunk form, so Quarto executes them; splitting, cloning and merging keep it.

C-c C-c in a chunk runs it with Quarto's Run Cell (quarto.runCurrentCell) rather than scimax's own execution, because chunk output belongs in the rendered page, not in the source. Quarto's own keys stay in charge in .qmd files: Cmd+Enter (run line or selection), Shift+Enter (run and advance) and Cmd+Shift+K (preview). In a .md file those keys keep their scimax meanings, and Cmd+Shift+K on a citation still deletes it there.

Cmd+Shift+V (Ctrl+Shift+V) in a .qmd file also runs Quarto's Preview (quarto.preview), so the preview key matches org and Markdown files.

Callouts and other divs

Fenced divs (callouts, ::: {.columns}, panels, ::: {#fig-x} figure divs) fold from the opening ::: to its matching close, including nested divs.

Highlighting

Task headings are coloured as in org: TODO keywords red, done keywords green, and the priority, :tags: and the SCHEDULED / DEADLINE / CLOSED line with its timestamps in the theme's org colours. They are semantic tokens (orgTodo, orgDone, orgPriority, orgTag, orgPlanning, orgTimestamp), so editor.semanticTokenColorCustomizations can change them.

Keywords

The default keywords are TODO NEXT WAIT WAITING HOLD SOMEDAY IN-PROGRESS (active) and DONE CANCELLED CANCELED (done). Declare others with a #+TODO: line, inside an HTML comment so it does not render:

<!-- #+TODO: TODO REVIEW | DONE REJECTED -->

Put the declaration somewhere other than the first line when the first line is a heading.

Commands

C-c C-s and C-c C-d work anywhere in a heading's section, as in org: they open the calendar date picker, write the SCHEDULED / DEADLINE line under the heading, and add TODO to a heading without a keyword, so the task shows in the agenda. Above the first heading they insert @scheduled(...) / @due(...) at the cursor, as before. Cycling a [TODO] heading writes the keyword bare (TODO).

C-c C-t, t and S-<right> / S-<left> work as in org. A done keyword adds a CLOSED: [...] timestamp to the planning line (or a new line under the heading), and leaving it removes it. On a task with a repeater (SCHEDULED: <2026-11-03 Tue +1w>) the date moves on and the heading goes back to TODO instead. The planning line must come right after the heading, with no blank line in between.

Checkbox Statistics

A [n/m] or [n%] cookie on a heading counts the checkboxes in its section; on a list item, its direct child checkboxes. Toggling a checkbox (C-c C-c or a click) updates the cookies above it, and C-c C-c on a line with a cookie recounts it. As in org, a heading's cookie also counts its direct subheadings with TODO keywords when you change one with C-c C-t.

## Checkboxes [2/3]
- [x] task 1
- [x] task 2
- [ ] task 3

Agenda

Indexed Markdown files take part in the database agenda and TODO lists (C-c a), with priority, tags and planning dates. The first database sync after updating re-indexes Markdown files. The agenda view for the current file (C-c a < a) works on a Markdown file; agendas limited to a project read only its org files.

Hashtags

#tags in Markdown are drawn in blue, hover and click like in org (see Hashtags in the Editor), and are indexed. A heading's own # marks are not hashtags, but #tags in its title are.

Time and Metadata

The speed keys I (clock in), e (effort) and P (set property) insert org drawers even in Markdown files, where nothing reads them back. Avoid them in Markdown.

Special Elements

Maximizing Compatibility

To get the most out of Scimax VS Code with Markdown:

1. Use speed commands - Position cursor at column 0 of headings for rapid single-key operations

2. Use fenced code blocks - The extension supports ```language blocks for execution and manipulation

3. Use the outline view - Provides visual navigation similar to org's sparse tree features

4. Use jump commands - C-c C-j for headings, C-c C-v g for code blocks

5. Use # TODO headings with SCHEDULED / DEADLINE lines - they show up in the org agenda next to your org tasks

When to Use Org-Mode Instead

Consider using org-mode files when you need:

• Time tracking with clocking

• Inherited properties and tags

• Per-block header arguments, tangling and noweb

• Table formulas

• Advanced export features

Org files can be exported to Markdown when sharing with others who don't use org-mode.