[markbac]

The VS Code extension (2.3.0) now helps while writing py-doc Markdown, not only with the live preview.

Highlighting

• Every fence py-doc draws is highlighted in its own language. A Python test checks the list against py-doc's renderers and poster blocks, so a new fence can't be missed.

  Fences	Grammar
  mermaid	The extension's own: diagram types, keywords, arrows, edge labels, %% comments
  dot, graphviz and the blockdiag family	The extension's own: graph keywords, attributes, edges, strings, comments
  plantuml, puml	The extension's own: @startuml, element keywords, arrows, stereotypes, colours, ' comments
  vega, vega-lite, wavedrom, wireviz, bytefield-svg	VS Code's own JSON, JavaScript, YAML and Clojure
  Poster blocks, plot, circuit, chess, music/abc, pikchr, railroad and the science fences	One grammar for py-doc's written forms: key: lines, key=value options, a | b cells, icons, numbers with units, colours, comments

  Attributes on the fence line, such as width="100%", are highlighted too. The extension's grammars use their own scope names, so they don't clash with dedicated Mermaid, Graphviz or PlantUML extensions.

• py-doc constructs in Markdown, beside the directives and {{variables}} added in Rich table cells: [[LISTTABLE]] with lists, header rows, merged cells and diagrams #219:

  • [[LISTTABLE]] rows cell by cell: <br>, - and 1. items, < and ^ merges, {bg=… valign=…} and [[BLOCK:]] slots, with ordinary Markdown inside the cells.
  • Callouts (> [!NOTE], > **Warning:**).
  • Fenced divs (::: {.pagebreak}, :::: columns).
  • pandoc attribute blocks after spans, links, pictures, code and headings.

  Code blocks and inline code are left as code.

Folding and snippets

• Folding: [[IF:]]/[[NOT:]] to [[ENDIF]] (nested too), [[BLOCK:]] to [[ENDBLOCK]], [[LANDSCAPE]] to [[PORTRAIT]], a [[LISTTABLE]] with its rows, and ::: fenced divs. It comes from src/folding.js through a folding range provider, beside VS Code's own folding of headings.
• 25 snippets: listtable, block, cellstyle, the five callouts, captions, include, if/not, pagebreak, landscape, style, var, mermaid/dot/plantuml, chart/cards, notes/columns.

Instructions

The extension README is now a full guide:

• installing from a .vsix, by command or from the Extensions view, and updating and removing it
• a quick start
• the live preview
• what is highlighted, in tables
• folding keys
• every snippet, and how to have snippets offered as you type in Markdown
• settings and troubleshooting (output channel, reloading, inspecting token scopes)

The user guide's VS Code section and the root README mention the new features. CHANGELOG 2.3.0.

Testing

• test/highlight.test.js tokenizes py-doc Markdown with vscode-textmate and vscode-oniguruma, the engine VS Code uses (new dev-only dependencies). That caught two real problems: a capture-pattern loop, and arrow patterns matching single hyphens.
  • VS Code's Markdown grammar isn't on npm, so the tests use a stand-in host. With PYDOC_MARKDOWN_GRAMMAR set to the real grammar, they also check that py-doc syntax in code blocks stays plain.
  • The CI vscode job fetches VS Code 1.105.0's Markdown grammar, checks its SHA-256, and runs the highlighting tests against it.
• test/folding.test.js, test/snippets.test.js, and tests/test_editor_grammar.py in Python.
• Results:
  • npm run lint && npm test: 31 passed, plus the real-grammar test run locally against 1.105.0.
  • python -m pytest: 1996 passed.
  • ruff check . and ruff format --check . are clean.
  • py-doc lint docs --strict is clean with Vale.
  • npx @vscode/vsce package builds a 69-file .vsix with the grammars, snippets and folding, without the dev dependencies.

I haven't tried it in a running VS Code window. The token tests use VS Code's own engine and Markdown grammar, but how the colours look depends on your theme.

---

Generated by Claude Code