Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
64 lines (43 loc) · 5.31 KB

ARCHITECTURE.md

File metadata and controls

64 lines (43 loc) · 5.31 KB
Raw

Architecture

This extension narrows the gap between VS Code's built-in Markdown preview and GitHub. It augments the host preview through supported contribution points rather than owning a renderer or webview.

Runtime Flow

package.json contributions
  ├─ markdown.markdownItPlugins ──> src/extension.ts ──> focused markdown-it plugins
  └─ markdown.previewStyles ──────> dist/extension.preview.css

VS Code configuration changes ───> src/events.ts ──> preview refresh + Mermaid sync
VS Code commands ────────────────> src/commands.ts ──> theme configuration

activate registers every command and configuration listener in the extension context, then returns extendMarkdownIt. VS Code calls that hook with its own markdown-it instance. The plugin order is intentional:

  1. GitHub-compatible strikethrough
  2. GFM tagfilter
  3. task lists
  4. alerts
  5. emoji
  6. footnotes
  7. automatic text direction
  8. theme metadata
  9. HTML image URL rewriting

Each behavior lives under src/plugins/. Plugins transform tokens or renderer rules while the built-in preview remains responsible for document lifecycle, webview security, syntax highlighting, and navigation.

Presentation and Themes

src/extension.preview.css is the authored entrypoint. The build combines it with a committed snapshot of GitHub Markdown styles and nine theme variable sets, then writes dist/extension.preview.css.

Normal builds are deliberately offline. scripts/build/github-css.ts extracts build assets from tests/fixtures/parity-reference.css; within the CSS and parity workflows, only explicit refresh and remote-verification commands contact GitHub. Other maintenance commands, such as emoji metadata updates, may contact GitHub independently. This keeps local builds and pull-request CI independent of GitHub availability and unauthenticated API quotas.

Theme metadata written by src/plugins/markdown-it-github-theme.ts selects either one fixed theme or separate light and dark themes through CSS media queries. Runtime code does not infer light or dark mode from the clock.

Mermaid Integration

Mermaid rendering belongs to the separate markdown-mermaid extension. If its configuration keys exist and githubMarkdown.mermaid.syncTheme is enabled, this extension maps the selected GitHub themes to both markdown-mermaid.lightModeTheme and markdown-mermaid.darkModeTheme.

Each Mermaid slot uses the Workspace target when that setting has an explicit workspace override; otherwise it uses Global. Original values and the last applied values are stored per target in extension global state, with Workspace records keyed by the current workspace identity. Stopping synchronization or deactivating the extension restores every still-owned Global record and the current workspace's still-owned Workspace records. A user change releases the affected record, so restoration does not overwrite the newer choice.

Apply and restore intent is persisted before configuration writes. Pending records are reconciled after an interrupted transition, and released records preserve user takeovers across later workspace changes. Concurrent extension hosts cannot update shared Global settings atomically, so the latest observed host write wins until another host observes a user takeover. If markdown-mermaid is absent, synchronization is a no-op. No Mermaid runtime is bundled.

Verification Boundaries

  • Unit tests cover plugins, commands, configuration events, Mermaid state restoration, and reusable build/parity helpers. Coverage thresholds gate src/**/*.ts and unit-testable scripts/**/*.ts independently so strong runtime coverage cannot hide weak development tooling coverage.
  • Generated sources and explicitly listed thin command entrypoints are outside the unit-coverage denominator. Host launch/browser-driving entrypoints and the scripts/verify harness are also excluded because they require their real VS Code/browser host or repository-level verification environment; small host configuration and assertion helpers remain covered by unit tests.
  • scripts/verify checks the complete Markdown transformation and manifest boundaries.
  • Pixel parity renders committed GitHub reference input and local output in the same Chromium process. Exact cases use zero tolerance; host-rendered features use explicit recorded budgets.
  • Desktop host smoke tests run against VS Code 1.74.0 and stable. A browser-host smoke test protects the browser entrypoint and the no-Node-runtime constraint. These tests activate the extension, render through VS Code's built-in Markdown engine so the markdown.markdownItPlugins contribution is exercised, and verify the contributed preview stylesheet exists.
  • Packaging verifies the Marketplace artifact after the code and visual checks pass.

Compatibility and Non-goals

Both main and browser point to the same extension bundle. Runtime modules under src/ therefore avoid Node-only APIs. Node APIs are allowed in development scripts under scripts/ and test tooling.

The project does not:

  • replace VS Code's Markdown preview or create a custom webview;
  • bundle Mermaid or other client-side diagram renderers;
  • promise pixel identity for visuals owned by a host application without an explicit measured budget;
  • raise the minimum VS Code version unless a required runtime API demands it.