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-06-13
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

haresh-sai06
haresh-sai06/SapSynk-AI

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
haresh-sai06
haresh-sai06/SapSynk-AI

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
haresh-sai06
haresh-sai06/SapSynk-AI

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.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

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.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

webinar-marketing

When the user wants to plan, promote, run, or improve a webinar or virtual event to generate and convert demand. Use when the user mentions 'webinar,' 'virtual event,' 'online event,' 'live demo,' 'virtual summit,' 'workshop,' 'masterclass,' 'fireside chat,' 'roundtable,' 'registration funnel,' 'show-up rate,' 'attendance rate,' 'webinar promotion,' 'webinar follow-up,' or 'on-demand webinar.' Also use when they have a webinar that isn't converting — low registrations, low show-up, or attendees who don't buy — and want to diagnose and fix it. Covers the full funnel: registration, promotion, show-up, live engagement, live-to-close, and post-event nurture. Distinct from launch-strategy (full product launches) and email-sequence (lifecycle nurture) — this is the end-to-end webinar/event motion. NOT for in-person field events logistics, and NOT for generic lifecycle email (use email-sequence).

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

vpe-advisor

VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing → screen → onsite → offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) — VPE owns delivery operations and how the team ships.

★ 0