AGENT SKILL

md-document

Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output — Google Fonts + Prism.js CDN are the only externals; no framework runtime, no build step. Use after orchestrator routing or after design-system onboarding is confirmed.

License 许可
MIT
最近更新
2026-11-08
Stars
★ 0
Forks
0

01 前言 Front Matter

name
md-document
tags
[ "markdown", "html", "documentation", "single-file", "toc", "scrollspy", "search", "code-copy", "design-system" ]
author
Alireza Rezvani
license
MIT
version
2.10.1
description
Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output — Google Fonts + Prism.js CDN are the only externals; no framework runtime, no build step. Use after orchestrator routing or after design-system onboarding is confirmed.
compatible_tools
[ "claude-code", "codex-cli", "cursor", "antigravity", "opencode", "gemini-cli" ]

03 SKILL.md 正文

md-document — Long-form Markdown to HTML

The general-purpose converter — handles the 90% case Shihipar describes (specs, plans, RFCs, reports, explainers). Three stdlib tools pipeline together:

markdown_parser.py  →  html_renderer.py  →  interactivity_injector.py
   (md → JSON AST)    (AST + tokens → HTML)    (HTML + JS behavior)

Output is one .html file with sticky TOC, search filter, scrollspy, code-copy buttons, and the user's 12 derived brand tokens. Externals limited to Google Fonts CSS + Prism.js CDN.

When to invoke

Symptom Action
markdown-html-orchestrator routes input as DOCUMENT Invoke this skill
User runs /cs:md-document <path>.md directly Invoke this skill
User says "convert this spec/report/RFC/plan to HTML" Invoke this skill
Input is a code review (has ```diff blocks) Route to md-review instead
Input is a slide deck (clear --- boundaries) Route to md-slides instead
Input is < 100 lines Refuse (Shihipar threshold — markdown still wins)
Design-system not onboarded Refuse, surface /cs:design-system

Pipeline

# 1. Parse markdown → JSON AST
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
    --input <path>.md --output sections.json

# 2. Render AST + design-system config → single-file HTML
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
    --sections sections.json --output document.html

# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
    --file document.html \
    --features search,copycode,smoothscroll,scrollspy

Or all-in-one (sample render):

python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \
  | python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
      --file /dev/stdin --output document.html

What gets rendered

CommonMark subset sufficient for agent-generated artifacts:

  • Headings H1-H6 (every H2+ gets an anchor id and TOC entry)
  • Paragraphs with inline bold / italic / code / links / images
  • Fenced code blocks (```python) with Prism.js highlighting on demand
  • GFM tables with per-column alignment
  • GFM callouts (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION])
  • Blockquotes, ordered + unordered lists (single-level), horizontal rules

Out of scope: nested lists, HTML inlines, footnotes, definition lists, task list checkboxes (rendered as plain text), reference-style links.

Hard rules

  1. Refuses input < 100 lines. Markdown wins below the threshold (Shihipar).
  2. Refuses without onboarding. config_loader.setup_completed() must return True. Otherwise surface /cs:design-system.
  3. Single-file output. All CSS + JS inline. Only externals are fonts.googleapis.com and cdn.jsdelivr.net (Prism). Anything else is a regression.
  4. Customization must change behavior. design_style=editorial produces 720px-wide layout with 1.75 line-height; playful rounds the callouts and adds shadow; technical is dense with 0.875rem code. Smoke-tested.
  5. WCAG-compliant tokens. Inherits the design-system's WCAG AA palette — body text ≥ 4.5:1 contrast, links iteratively walked to 4.5:1.
  6. Idempotent injection. Re-injecting interactivity is a no-op (marker check). Re-rendering with a different design_style works cleanly.

Forcing-question library (Matt Pocock grill discipline)

  1. What's the document for — skim, decide, or deep-read? Recommended: name it; density follows. Canon: Shihipar; Tufte Envisioning Information.
  2. Sticky-sidebar TOC or collapsible-top? Recommended: sticky-sidebar for > 800 words / 4+ H2s; collapsible-top for shorter mobile-first docs. Canon: NN/g TOC Best Practices (2023).
  3. All four interactive features, or a subset? Recommended: all four — none of them cost more than ~1 KB. Canon: Wattenberger Why React isn't great for actually building websites.
  4. Code theme — light, dark, or auto? Recommended: auto (follows OS prefers-color-scheme). Canon: WCAG 2.2 §1.4.3.
  5. Does the document have a clear H1 title? Recommended: yes — H1 becomes the page <title> and is excluded from the TOC.

Distinct from

  • md-review — that converter renders diff blocks + severity-tagged margin annotations. This one renders prose + tables + code + callouts.
  • md-slides — that converter splits on --- boundaries into slides. This one renders one continuous document.
  • marketing/landing/ — that generates landing pages from scratch (no markdown input). This converts existing markdown.

Output artifact

{default_output_dir}/doc-{slug}.html (path resolved by orchestrator's output_path_resolver.py; collision suffix -2, -3, … by default).

References

  • Shihipar — Claude Code HTML output (Medium, 2026)
  • Tufte — Envisioning Information (1990), ch. 2 "Micro/Macro Readings"
  • NN/g — Table of Contents Best Practices (2023)
  • WCAG 2.2 — §1.4.3 contrast, §2.4.5 multiple ways
  • Wattenberger — Why React isn't great for actually building websites
  • See references/ for full citations

04 同仓库更多 Skills

Tashima-Tarsh
Tashima-Tarsh/Disha6.6

youtube-full

Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private/age-restricted videos.

图像与多媒体
★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

x-twitter-growth

X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.

★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.

Skill与智能体开发
★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

wrap-up

Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says "wrap up", "close this out", "what do I own now", "give me the summary", "recap the agent", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained ./my-agent/agent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done.

★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

workflow-builder

Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.

Skill与智能体开发
★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

weekly-review

Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.

★ 0