mk-markdown-reader
Serve a markdown file/directory as a calm, book-like reader via a local HTTP server (127.0.0.1 only); good for long-form docs like RFCs and plans. Supports Mermaid, dark/light mode, and a nav sidebar.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 16
- Forks
- 3
01 前言 Front Matter
- name
- mk-markdown-reader
- description
- Serve a markdown file/directory as a calm, book-like reader via a local HTTP server (127.0.0.1 only); good for long-form docs like RFCs and plans. Supports Mermaid, dark/light mode, and a nav sidebar.
02 资源文件 24
- 资产文件assets/directory-browser.css2.9 KB
- 资产文件assets/favicon.ico15.0 KB
- 资产文件assets/novel-theme.css612 B
- 脚本assets/reader.js23.9 KB
- 资产文件assets/styles/novel-theme-base.css1013 B
- 资产文件assets/styles/novel-theme-components.css3.8 KB
- 资产文件assets/styles/novel-theme-content.css2.9 KB
- 资产文件assets/styles/novel-theme-header.css3.9 KB
- 资产文件assets/styles/novel-theme-mermaid.css3.1 KB
- 资产文件assets/styles/novel-theme-overlays.css3.6 KB
- 资产文件assets/styles/novel-theme-responsive.css4.5 KB
- 资产文件assets/styles/novel-theme-sidebar.css6.2 KB
- 资产文件assets/styles/novel-theme-variables.css1.4 KB
- 资产文件assets/template.html6.0 KB
- 参考文档package.json352 B
- 参考文档references/reader-experience.md625 B
- 参考文档references/reader-operations.md1.1 KB
- 脚本scripts/lib/http-server.cjs11.4 KB
- 脚本scripts/lib/markdown-renderer.cjs9.7 KB
- 脚本scripts/lib/plan-navigator.cjs10.1 KB
- 脚本scripts/lib/plan-table-parser.cjs9.9 KB
- 脚本scripts/lib/port-finder.cjs1.2 KB
- 脚本scripts/lib/process-mgr.cjs3.7 KB
- 脚本scripts/server.cjs9.6 KB
03 SKILL.md 正文
mk:markdown-reader
Local HTTP server rendering markdown files with a calm, book-like reading experience.
Note: mk:brainstorming --html and mk:plan-creator --html produce self-contained
HTML files that open directly in the browser — they do not use or need this server.
Installation (Required Before First Use)
This skill requires npm dependencies. Install once from the project root:
cd .agents/skills/markdown-reader
npm install
Dependencies: marked, highlight.js, gray-matter
Without installation you will get Error 500: Error rendering markdown.
Usage
# View a markdown file (opens browser automatically)
node .agents/skills/markdown-reader/scripts/server.cjs \
--file ./tasks/plans/my-plan/plan.md
# Browse a directory
node .agents/skills/markdown-reader/scripts/server.cjs \
--dir ./tasks/plans
# Background mode (foreground process for Codex task runners)
node .agents/skills/markdown-reader/scripts/server.cjs \
--file ./README.md \
--foreground
# Stop all running instances
node .agents/skills/markdown-reader/scripts/server.cjs --stop
The server binds to 127.0.0.1 (localhost) only. Served files are not reachable from
other devices on the network — this is intentional.
Lifecycle
Start with --file or --dir; use --foreground when the host needs to keep the process
attached. The default port is 3456 and increments through 3500 if busy. End the lifecycle with
--stop; never leave a reader process running after the task.
| Need | Route |
|---|---|
| CLI flags, routes, persistent state | references/reader-operations.md |
| Reader features, plan navigation, shortcuts, Mermaid | references/reader-experience.md |
| Architecture and troubleshooting | references/reader-operations.md |
The server binds only to 127.0.0.1. It validates every file against its allowed directories;
traversal attempts return 403. Referenced images must be relative to the source markdown file.
Self-contained HTML from mk:brainstorming --html or mk:plan-creator --html opens directly
and does not need this server.
04 同仓库更多 Skills
mk-worktree
Manages git worktrees for parallel agent isolation: creates parallel/{name}-{timestamp} branches, merges with conflict detection. NOT for user feature branches (use git worktree directly).
mk-workflow-orchestrator
Auto-invoked 7-phase workflow for complex-feature intent; fasttrack mode for pre-approved specs. NOT for explicit single tasks (mk:cook), green-field builds (mk:autobuild), or simple fixes (mk:fix).
mk-web-to-markdown
Fetch a URL and return clean markdown, for arbitrary external pages (blog, RFC, GitHub issue, vendor doc) not covered by mk:docs-finder. Static-only by default; opt-in JS rendering available.
mk-vulnerability-scanner
Vulnerability analysis: OWASP Top 10, current threat landscape, supply chain security, attack surface mapping, risk prioritization. Use for security audits. NOT for STRIDE/CSO infra audits (mk:cso).
mk-vue
Vue 3 authoring/review: components, composables, reactivity, Pinia, Pinia Colada, file routing, forms. Composition API + script setup. Auto-activates on .vue files. Deep review: mk:vue-best-practices.
mk-vue-testing-best-practices
Vue 3 testing best-practices review: Vitest + Vue Test Utils for components, composables, Pinia, Router, async/Suspense, forms, a11y, plus Playwright E2E strategy. Advisory only.