Project: vscode-github-markdown

Goal

This project is a VS Code extension that makes local Markdown preview match GitHub as closely as possible, so developers can write documentation and preview the expected GitHub result while editing.

Stack

• TypeScript
• VS Code extension API
• Markdown preview contribution points
• Nub
• oxlint + oxfmt
• lefthook

Key Files

• package.json: extension manifest, contribution points, engine constraints
• src/extension.ts: extension entrypoint
• README.md: default English documentation
• README.zh-CN.md: Simplified Chinese documentation
• CHANGELOG.md: canonical user-facing release record
• docs/CHANGELOG_STYLE_GUIDE.md: required changelog content and writing standard
• tsconfig.json: strict TypeScript config
• lefthook.yml: pre-commit checks

Environment and Commands

• Install the project toolchain: mise install
• Install dependencies: pnpm install
• Build: nub run build
• Dev watch: nub run dev
• Verify GitHub Markdown: nub scripts/verify/index.ts
• Test: nub run test
• Test watch: nub run test:watch
• Test coverage: nub run test:coverage
• Package: nub run package
• Lint: nubx oxlint .
• Type-aware lint: nubx oxlint --type-aware .
• Format: nubx oxfmt .

Implementation Rules

• Keep runtime code compatible with web extensions. package.json uses both main and browser, so avoid Node-only APIs in extension runtime code unless the manifest is updated intentionally.
• Prefer the built-in Markdown extension hooks already declared in package.json:
  • markdown.markdownItPlugins
  • markdown.previewScripts
  • markdown.previewStyles
• Do not introduce a custom preview system if the built-in Markdown preview hooks can solve the problem.
• Keep changes minimal and directly tied to GitHub Markdown parity. Avoid speculative theme systems or configuration layers.

Documentation Rules

• README.md is the default English document.
• README.zh-CN.md is the Simplified Chinese counterpart.
• When updating shared project-facing documentation, keep both files aligned unless the change is intentionally language-specific.
• Do not claim a feature is implemented unless it exists in the current codebase.
• Follow docs/CHANGELOG_STYLE_GUIDE.md for every new CHANGELOG.md entry.
• For every change, evaluate the guide's admission rules. Add eligible changes under [Unreleased] and intentionally omit ineligible internal work.
• Record only user-observable or user-actionable outcomes in the changelog. Omit implementation, testing, tooling, CI, and dependency details unless they materially affect extension users.

Versioning Rules

• Treat engines.vscode as the minimum supported version, not the development version.
• Do not raise the minimum VS Code version unless the implementation requires APIs or behavior from a newer release.

Before Finishing

• Run the relevant lint/format commands for touched files when practical.
• Keep scope tight. If a task only needs docs or manifest changes, do not expand into runtime refactors.

Agent 技能

Issue Tracker

Issue 和 PRD 使用 GitHub Issues 跟踪，详见 docs/agents/issue-tracker.md。

Triage 标签

使用 Matt 技能的标准 Triage 标签，详见 docs/agents/triage-labels.md。

领域文档

使用单上下文领域文档布局，详见 docs/agents/domain.md。