mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +00:00

History

Claude 8818bee8be 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
..
.claude-plugin	feat(markdown-html): add md-document v2.10.1 — long-form markdown→HTML converter	2026-06-02 05:58:00 +00:00
agents	feat(markdown-html): add v2.10.0 foundation — orchestrator + design-system	2026-05-29 14:19:06 +00:00
commands	feat(markdown-html): add md-document v2.10.1 — long-form markdown→HTML converter	2026-06-02 05:58:00 +00:00
skills	feat(markdown-html): add md-document v2.10.1 — long-form markdown→HTML converter	2026-06-02 05:58:00 +00:00
CLAUDE.md	feat(markdown-html): add v2.10.0 foundation — orchestrator + design-system	2026-05-29 14:19:06 +00:00
README.md	feat(markdown-html): add v2.10.0 foundation — orchestrator + design-system	2026-05-29 14:19:06 +00:00

README.md

markdown-html — Markdown to interactive HTML converter

"I generated a 200-line implementation plan in Claude Code last month. Markdown. … I skimmed the first 20 lines, scrolled past the diagram I could not actually parse, and closed the file. I never read the rest." — Thariq Shihipar, Claude Code HTML output (Medium, 2026)

Convert long markdown files in a Claude project into single-file, lightly-interactive HTML that respects your brand. One-time design-system onboarding captures brand primary + accent + typography + layout style + default save location. Every conversion reads that config and renders consistently.

Status — v2.10.0 (foundation)

Skill	Purpose	Status
`markdown-html-orchestrator`	Routes long markdown → converter sub-skill (`context: fork`)	✓ live
`design-system`	Onboarding wizard + WCAG-AA-validated brand palette + shared config	✓ live
`md-document`	Long-form: sticky TOC + collapsibles + search + code-copy + scrollspy	v2.10.1 (next PR)
`md-review`	Code review: 2-col diff + severity-tagged margin annotations + jump-nav	v2.10.1 (next PR)
`md-slides`	Slide deck: arrow-key nav + presenter mode + print-to-PDF	v2.10.1 (next PR)

Quick start

# 1. One-time onboarding (10 questions, ~60 seconds)
python3 markdown-html/skills/design-system/scripts/onboard.py

# 2. (or zero-touch defaults for first-test)
python3 markdown-html/skills/design-system/scripts/onboard.py --defaults

# 3. Inspect the saved config
python3 markdown-html/skills/design-system/scripts/config_loader.py --status

# 4. Classify a markdown file and see the routing decision
python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input ./my-report.md --output json \
  | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py

# 5. Resolve where it would save (foundation; converters in v2.10.1)
python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input ./my-report.md --doctype document

Slash commands

/cs:markdown-html <path>.md — top-level router (classify + route + recommend)
/cs:grill-markdown-html <path>.md — Matt-style 5-question grill before conversion
/cs:design-system — surface the onboarding wizard

Hard rules

Refuses input < 100 lines — markdown still wins below the threshold (Shihipar). Keep short docs as markdown.
Refuses without onboarding — without a captured brand, output renders with placeholder defaults. Run onboarding once.
Refuses unwritable save location — onboarding asks where to save; the orchestrator honors it; collisions get suffixed (-2, -3, …).
Single-file HTML only — all CSS + JS inline. The only external CDN entries are Google Fonts + Prism.js. No build step, no bundler, no JS framework.
Never silently chain — "convert this AND make slides AND a code review" is three operations, asked explicitly.
WCAG AA enforced — body-text contrast must reach 4.5:1. Onboarding refuses any combination that fails.

Distinct from

Anthropic Playground plugin (/playground) — builds interactive prompt-tuning controls (sliders, knobs, prompt-copy-back). Different tool entirely.
marketing/landing/ — generates landing pages from scratch. Doesn't take markdown input.
engineering/handoff/ + productivity/handoff/ — session continuity briefs. Different artifact type.

File layout

markdown-html/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── cs-markdown-html-orchestrator.md
├── commands/
│   ├── cs-markdown-html.md          # router
│   ├── cs-design-system.md          # onboarding surface
│   └── cs-grill-markdown-html.md    # 5-question grill
└── skills/
    ├── markdown-html-orchestrator/  # context: fork
    │   ├── SKILL.md
    │   ├── scripts/
    │   │   ├── doctype_classifier.py
    │   │   ├── route_explainer.py
    │   │   └── output_path_resolver.py
    │   └── references/
    │       ├── information_density_canon.md
    │       ├── orchestrator_routing_patterns.md
    │       └── single_file_html_discipline.md
    └── design-system/
        ├── SKILL.md
        ├── scripts/
        │   ├── onboard.py
        │   ├── config_loader.py
        │   └── brand_palette_validator.py
        ├── references/
        │   ├── design_token_canon.md
        │   ├── wcag_accessibility.md
        │   └── typography_pairing.md
        └── assets/
            └── design_system_schema.json

License

MIT. See repo LICENSE.

Spec

Thariq Shihipar — Claude Code HTML output: Why Markdown Lost and How to Switch (Medium, 2026). The plugin operationalizes the article's central claim — markdown collapses past ~100 lines for agent-generated artifacts; HTML restores density, clarity, shareability, and lightweight interaction.