mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-07 08:26:02 +00:00

feat(markdown-html): add md-document v2.10.1 — long-form markdown→HTML converter

Adds the third skill to the markdown-html/ domain. The 90%-case converter
that Shihipar's essay calls for: any markdown spec / plan / RFC / report /
explainer becomes a single-file, lightly-interactive HTML document with
the user's onboarded brand applied.

Three stdlib tools pipeline together:

1. markdown_parser.py — CommonMark subset → section AST. Stdlib regex +
   state machine, no `markdown` dependency. Handles headings 1-6 (with
   slug anchors), paragraphs with inline bold/italic/code/links/images,
   fenced code with language tag, GFM tables with per-column alignment,
   GFM callouts (NOTE/TIP/IMPORTANT/WARNING/CAUTION), blockquotes,
   ordered + unordered lists (single-level), horizontal rules.

2. html_renderer.py — section AST + design-system config →
   single-file HTML. Inlines the 12 derived CSS custom properties from
   ~/.config/markdown-html/design-system.json. Applies the user's
   design_style (editorial/technical/minimal/playful) via body-class
   CSS overrides — editorial uses 720px max-width and 1.75 line-height,
   playful rounds callouts with shadows, technical is dense with
   0.875rem code. Emits sticky-sidebar/collapsible-top/inline/none TOC
   per toc.behavior. Google Fonts CDN link + Prism.js theme link per
   code_theme (light/dark/auto = prefers-color-scheme).

3. interactivity_injector.py — vanilla-JS payload injected before
   </body>. Search filter on H2 sections (Esc clears, sticky bar),
   code-copy buttons (navigator.clipboard + execCommand fallback),
   smooth-scroll on TOC links, scrollspy via IntersectionObserver
   (sets aria-current="location" on the matching TOC entry; rootMargin
   tuned to NN/g F-shape reading pattern). Idempotent (marker check).
   Feature subset selectable via
   --features search,copycode,smoothscroll,scrollspy.

Plus 3 reference docs (each citing 5-7 sources): information_density
_patterns.md (Shihipar + Tufte + Wattenberger + Appleton + Ciechanowski
+ Bret Victor + Nielsen), toc_and_nav_ux.md (NN/g + WCAG 2.2 + ARIA APG
+ Vitepress/Docusaurus/mdBook convergence + GOV.UK + MDN), single_file
_html_discipline.md (Shihipar + Tom MacWright's Big + Google Fonts API
+ Prism.js + Anil Dash). 1 template asset documenting the canonical
output shape. /cs:md-document slash command with the pre-flight gates
+ pipeline + output digest.

Repo-level updates:
- markdown-html/.claude-plugin/plugin.json: skills array adds
  ./skills/md-document; version 2.10.0 → 2.10.1; description updated.
- .claude-plugin/marketplace.json: markdown-html-skills entry version
  2.10.0 → 2.10.1, description updated; ALSO cleans up stale top-level
  counters left over from foundation PR #780 — 338 → 341 skills, 16 → 17
  domains, 63 → 64 plugins, 2.9.0 → 2.10.1 metadata.version.
- Root CLAUDE.md: v2.10.1 release-notes block above v2.10.0.

Validation:
- check_plugin_json.py → OK
- sync-codex-skills.py --dry-run → 1 new symlink, documentation: 3 skills
- skill_description_validator.py → PASS (action verb, third person,
  trigger phrase, length within limit)
- skill_review_checklist_runner.py → 5/6 PASS (under-100-lines warns at
  105 — same as research-ops orchestrator; advisory not blocking)
- All 3 tools pass --help and --sample
- Full pipeline on markdown-html/CLAUDE.md (470 lines) produces 22.8 KB
  single-file HTML with all 7 expected components present (doctype,
  injected JS, scrollspy, IntersectionObserver, clipboard API, palette
  tokens, TOC)
- Design-style switch round-trip: --set design_style=editorial → output
  has 720px max-width and 1.75 line-height; --set design_style=playful
  → output has rounded callouts with shadow. Customization changes
  behavior, not decoration (design-system rule §3 honored).
- Empirical footprint: ~150-line markdown → 11 KB HTML / 15 KB with JS;
  ~470-line markdown → 17 KB / 23 KB with JS.

Coming in v2.10.2: md-review (2-col diff + severity-tagged margin
annotations + jump-nav) and md-slides (arrow-key nav + presenter mode +
print-to-PDF). Both will reuse md-document's renderer scaffolding and
design-system/scripts/config_loader.py.

https://claude.ai/code/session_01BK2KoQot1U7J5oSosrCQdc

2026-06-02 05:58:00 +00:00

3.3 KiB

Raw Permalink Blame History

description	argument-hint
Convert long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file interactive HTML document. Runs the md-document pipeline (parser → renderer → injector) with the user's design-system tokens. Sticky TOC, search filter, code-copy buttons, scrollspy, WCAG-AA palette. Refuses input < 100 lines (Shihipar) or unfinished onboarding. Output is a single .html file (Google Fonts + Prism.js CDN as the only externals).	<path to markdown file> [--out <dir>] [--features search,copycode,smoothscroll,scrollspy]

description

argument-hint

Convert long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file interactive HTML document. Runs the md-document pipeline (parser → renderer → injector) with the user's design-system tokens. Sticky TOC, search filter, code-copy buttons, scrollspy, WCAG-AA palette. Refuses input < 100 lines (Shihipar) or unfinished onboarding. Output is a single .html file (Google Fonts + Prism.js CDN as the only externals).

<path to markdown file> [--out <dir>] [--features search,copycode,smoothscroll,scrollspy]

/cs:md-document — Long-form markdown → HTML

Convert the markdown at $ARGUMENTS into a single-file interactive HTML document.

Pre-flight gates (refuse, never override)

Input < 100 lines → refuse (markdown wins below the threshold per Shihipar). wc -l <path> to confirm.
Design-system not onboarded → refuse, surface /cs:design-system.
Output directory unwritable → refuse, ask user for an alternate via --out.

Pipeline

# 1. Classify (if not already routed by orchestrator)
python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input "<path>.md" --output json \
  | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py

# 2. Resolve the output path
python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input "<path>.md" --doctype document

# 3. Parse → render → inject
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
    --input "<path>.md" --output /tmp/sections.json
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
    --sections /tmp/sections.json --output <resolved-out>.html
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
    --file <resolved-out>.html \
    --features search,copycode,smoothscroll,scrollspy

What ships in the HTML

Sticky-sidebar TOC (default; configurable via toc.behavior in design-system)
Scrollspy: aria-current="location" on the TOC entry for the section in view
Search bar (Esc clears): filters which H2 sections are visible
Code-copy buttons on every <pre> (vanilla navigator.clipboard with execCommand fallback)
Smooth-scroll on TOC link clicks
Prism.js syntax highlighting (autoloader fetches only the languages this doc uses)
12 brand CSS custom properties from the design-system's derived_palette
@media (prefers-reduced-motion: reduce) honored
Print-friendly via the browser's native print stylesheet (no @page overrides needed for documents)

Hard rules

Output is one .html file. No multi-file output, no extracted CSS/JS, no asset folders.
External CDN: fonts.googleapis.com + cdn.jsdelivr.net (Prism). Nothing else.
No JS framework runtime. Vanilla JS + IntersectionObserver only.
Re-running on the same input writes doc-{slug}-2.html etc. (collision suffix).

Output

Returns: input lines, output path, design style applied, top 3 features used, one forcing question.

References

See markdown-html/skills/md-document/references/:

information_density_patterns.md — Shihipar + Tufte + Wattenberger
toc_and_nav_ux.md — NN/g + WCAG + ARIA
single_file_html_discipline.md — Single-file artifact rationale

3.3 KiB Raw Permalink Blame History