mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-08 22:21:12 +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

4.9 KiB

Raw Permalink Blame History

Information Density Patterns for Long-form Documents

Why this exists: The md-document converter renders long-form markdown (specs, RFCs, reports, explainers) — typically 100-2000 lines of prose, code, tables, and callouts. Past 100 lines the linear flow loses orientation. This document codifies the patterns that restore it.

The four density patterns

1. Hierarchy made visible

Linear markdown shows hierarchy through indented # characters. HTML shows hierarchy through typography scale, color, weight, spacing, and surface. The renderer uses a modular type scale (typography.scale_ratio, default 1.25 = major third) so each heading level is visibly proportional. H2 sections get a hairline border-bottom for visual chunking. Callouts get a 4px accent border that signals "stop and read."

Linear reading is one channel — top to bottom. The renderer adds:

Sticky-sidebar TOC (default) — always visible, jumps to any H2/H3 in one click.
Scrollspy — the current section's TOC entry gets aria-current="location" as the reader scrolls, so they always know where they are.
Anchored headings — every H2-H6 gets an id derived from the heading text, so deep links work without further effort.
Smooth scroll — TOC clicks animate, not jump, so the reader keeps spatial context.

3. Lateral structure

Side-by-side comparison is impossible in linear markdown. HTML provides:

Tables — rendered with <table>, semantic <thead>/<tbody>, per-column alignment from the GFM delimiter row.
Collapsible sections — <details> blocks for content the reader can skip on first pass. (TOC variant collapsible-top uses this for the TOC itself.)
Callouts — <aside class="callout"> for NOTE/TIP/IMPORTANT/WARNING/CAUTION. Distinct from paragraphs because they interrupt flow with intent.

4. Lateral interaction

Lightweight, no-framework:

Search filter — <input type="search"> filters H2 sections by heading + body text. Vanilla JS, no debouncing needed because typical documents have under 30 H2 sections.
Code-copy buttons — appear on hover over <pre>, copy the entire <code> text. navigator.clipboard with document.execCommand fallback.
Smooth scroll — already covered above.

What's deliberately excluded

Slider/knob controls — that's Anthropic's official Playground plugin's lane.
Real-time collaboration — documents are read artifacts, not edit surfaces.
Multi-page navigation — single-file is the discipline (see single_file_html_discipline.md).
Dark mode toggle — the user picked code_theme once; switching mid-document violates the shipped-as-onboarded contract. (code_theme: auto does follow prefers-color-scheme for syntax highlighting.)

Sources

1. Thariq Shihipar — "Claude Code HTML output" (Medium, 2026)

The spec. Five advantages mapped here: density, clarity, shareability, two-way interaction, context ingestion. The four-pattern taxonomy above is the implementation answer.

2. Edward Tufte — Envisioning Information (Graphics Press, 1990)

Ch. 2, "Micro/Macro Readings" — argues that effective information design lets the reader move between overview (TOC) and detail (paragraph) without losing context. The scrollspy + sticky TOC implements this micro/macro discipline for documents.

3. Amelia Wattenberger — Why React isn't great for actually building websites (wattenberger.com, 2022) + interactive essay archive

Argues that documents are not apps; framework runtimes are overhead. Validates the vanilla-JS + IntersectionObserver implementation choice.

4. Jakob Nielsen / NN/g — How Users Read on the Web (1997, updated 2024)

Establishes the F-shaped reading pattern: users scan headings + first sentences. The sticky-sidebar TOC + bold heading typography + H2 hairline border-bottom optimize for this pattern.

5. Maggie Appleton — Digital Gardens (maggieappleton.com, 2020)

The single-page-document-with-lightweight-interactivity pattern at scale. Her own gardens use exactly the techniques this converter emits.

6. Bartosz Ciechanowski — interactive essay archive (ciechanow.ski, 2017-present)

The upper bound of what vanilla-JS + inline SVG can produce in a single HTML file. Demonstrates that "lightweight" doesn't mean "low-quality."

7. Bret Victor — "Up and Down the Ladder of Abstraction" (worrydream.com, 2011)

Argues for letting the reader move fluidly between concrete and abstract. The TOC (abstract) + section detail (concrete) + scrollspy (the link between them) is the documents-shaped implementation.

Applied to `md-document`

The converter emits exactly these patterns. markdown_parser.py extracts the structure; html_renderer.py renders it with the design-system tokens; interactivity_injector.py adds the four interactive behaviors. None of these need a JS framework or a build step.

4.9 KiB Raw Permalink Blame History