Agent skill

Md Document

by alirezarezvani in alirezarezvani/claude-skills

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…

MITAuto-check passedFrontend & Design

Install Md Document

skills CLI
$ npx skills add alirezarezvani/claude-skills --skill md-document -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install alirezarezvani/claude-skills md-document --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/alirezarezvani/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/markdown-html/skills/md-document .claude/skills/md-document && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
md-document
GitHub stars
28k
Token cost
~1.6k tokens
SKILL.md length
525 words
Files
8 (incl. scripts, references, assets)
Skills in repo
342
Repo updated
First seen
Licence
MIT

At a glance

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…

  • Works in 6 steps: Refuses input < 100 lines. Markdown wins… → Refuses without onboarding.… → Single-file output. All CSS + JS inline.… → …
  • The markdown-html-orchestrator classifies an input as DOCUMENT
  • SKILL.md covers When to invoke, Pipeline, What gets rendered and Hard rules, plus 4 more sections
  • Runs Python scripts from its folder; calls python3

What it does

Md Document is an agent skill from alirezarezvani/claude-skills. 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 configloader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file…

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including scripts, reference files and assets (for example `references/information_density_patterns.md`, `references/single_file_html_discipline.md` and `references/toc_and_nav_ux.md`).

It sits in Frontend & Design, covering Design systems, Markdown and HTML artifacts. The repository describes itself as: 380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8… The licence is MIT.

When your agent uses it

  • The markdown-html-orchestrator classifies an input as DOCUMENT
  • Invoked directly via /cs:md-document

Example prompts

  • “Use the md-document skill to convert long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML…”
  • “/md-document”

Requirements

  • Python 3

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  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…
  4. Customization must change behavior. design_style=editorial produces 720px-wide layout with 1.75 line-height; playful rounds the callouts…
  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.

What it can do on your machine

Read from SKILL.md and the folder at commit 19392f7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Md Document loads about 1.6k tokens when it runs, and up to ~5.2k if it reads all its reference files. Until then it costs about 176 tokens; SKILL.md has 525 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~176
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~5.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from alirezarezvani/claude-skills at commit 19392f7, republished under its MIT licence (© alirezarezvani). 525 words, ~1,552 tokens.

Download SKILL.mdSave it as .claude/skills/md-document/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
name
md-document
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.
version
2.10.1
author
Alireza Rezvani
license
MIT
tags
markdown, html, documentation, single-file, toc, scrollspy, search, code-copy, design-system
compatible_tools
claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli

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

SymptomAction
markdown-html-orchestrator routes input as DOCUMENTInvoke this skill
User runs /cs:md-document <path>.md directlyInvoke 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 linesRefuse (Shihipar threshold — markdown still wins)
Design-system not onboardedRefuse, surface /cs:design-system

Pipeline

bash
# 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):

bash
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 / Image: 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.
Show full SKILL.md (219 more words)Show less

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

© alirezarezvani, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (scripts, references, assets) in markdown-html/skills/md-document of alirezarezvani/claude-skills.

  • SKILL.md
  • assets/md_document_template.html
  • references/information_density_patterns.md
  • references/single_file_html_discipline.md
  • references/toc_and_nav_ux.md
  • scripts/html_renderer.py
  • scripts/interactivity_injector.py
  • scripts/markdown_parser.py

Open the folder on GitHubat commit 19392f7

Compare with similar skills

Md Document next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Md Document compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Md Document this skillalirezarezvani/claude-skills28k—~1.6kAutomated safety check: PassMIT
Data Viz Deckthatrebeccarae/claude-marketing162—~1.8kAutomated safety check: PassMIT
Building With Lobe UIlobehub/lobe-ui2.2k—~2kAutomated safety check: PassMIT
Using Docs Kitlobehub/lobe-ui2.2k—~2.8kAutomated safety check: PassMIT
Web Designdrewnekota/cetus146—~2.1kAutomated safety check: PassMIT
Visualizedisplay-dev/visualize131—~7.4kAutomated safety check: PassMIT

Similar skills

  • Data Viz Deck

    thatrebeccarae/claude-marketing

    Transform audit data, performance reports, and structured analyses into polished visual deliverables.

    162 GitHub stars~1.8k tokensUpdated 4 mo ago
    Documents & OfficeAuto-check passed
  • Building With Lobe UI

    lobehub/lobe-ui

    Build UI with the LobeHub design ecosystem — @lobehub/ui (plus its base-ui, chat, mobile, awesome, brand, mdx, i18n namespaces), @lobehub/icons, @lobehub/charts, @lobehub/fluent-emoji and…

    2.2k GitHub stars~2k tokensUpdated today
    Frontend & DesignAuto-check passed
  • Using Docs Kit

    lobehub/lobe-ui

    Set up and author a documentation site with @lobehub/docs-kit (the lobedocs CLI, React Router + Vite static docs used by ui.lobehub.com).

    2.2k GitHub stars~2.8k tokensUpdated today
    Frontend & DesignAuto-check passed
  • Web Design

    drewnekota/cetus

    A skill your agent uses when building any web page, HTML artifact, landing page, dashboard, slide deck, report, email, or UI component the user will look at.

    146 GitHub stars~2.1k tokensUpdated 2 days ago
    Frontend & DesignAuto-check passed
  • Visualize

    display-dev/visualize

    Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards.

    131 GitHub stars~7.4k tokensUpdated 21 days ago
    Frontend & DesignAuto-check passed
  • Web Design Engineer

    ConardLi/garden-skills

    Builds polished browser-rendered HTML, CSS, JavaScript and React pages, dashboards, prototypes and slide decks, aiming for a stunning rather than merely functional result.

    13k GitHub stars~8.8k tokensUpdated 2 mo ago
    Frontend & DesignAuto-check passed

More from alirezarezvani/claude-skills

All 342 skills in this repo
  • Agile Product Owner

    alirezarezvani/claude-skills

    Writes INVEST-checked user stories with acceptance criteria, splits epics, plans sprints from velocity and ranks the backlog with a weighted score.

    28k GitHub starsUsed in 3 repos~3.2k tokens
    Auto-check passed
  • Product Strategist

    alirezarezvani/claude-skills

    OKR cascade toolkit for product leaders: generates aligned company-to-team OKRs from five strategy types and scores how well they line up.

    28k GitHub starsUsed in 2 repos~1.8k tokens
    Auto-check passed
  • App Store Optimization

    alirezarezvani/claude-skills

    App Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store.

    28k GitHub starsUsed in 1 repo~4.2k tokens
    Auto-check passed
  • AWS Solution Architect

    alirezarezvani/claude-skills

    Design AWS architectures for startups using serverless patterns and IaC templates.

    28k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Campaign Analytics

    alirezarezvani/claude-skills

    Calculates attribution, funnel and ROI figures for marketing campaigns with three Python scripts that need only the standard library.

    28k GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed
  • Code to PRD

    alirezarezvani/claude-skills

    Reverse-engineers a frontend, backend or fullstack codebase into a product requirements document with per-page docs, an enum dictionary and an API inventory.

    28k GitHub starsUsed in 1 repo~4.9k tokens
    Auto-check passed

Questions about Md Document

What does Md Document do?

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…. Md Document is an agent skill from alirezarezvani/claude-skills. 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.

When should I use Md Document?

Md Document fits situations like: the markdown-html-orchestrator classifies an input as DOCUMENT; invoked directly via /cs:md-document.

How do I install Md Document in Claude Code?

Run `npx skills add alirezarezvani/claude-skills --skill md-document -a claude-code`. Or copy the skill folder (markdown-html/skills/md-document in alirezarezvani/claude-skills) into .claude/skills/md-document in your project. Claude Code loads it when a task matches its description.

How do I install Md Document in Codex?

Run `npx skills add alirezarezvani/claude-skills --skill md-document -a codex`. Or copy the skill folder (markdown-html/skills/md-document in alirezarezvani/claude-skills) into .agents/skills/md-document in your project. Codex loads it when a task matches its description.

Can I use Md Document in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add alirezarezvani/claude-skills --skill md-document -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/md-document, .gemini/skills/md-document, .github/skills/md-document and .opencode/skills/md-document in your project.

What does Md Document need to run?

Going by SKILL.md and its folder, Md Document needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Md Document access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Md Document safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Md Document use?

Md Document is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Md Document use?

About 1.6k tokens (SKILL.md is roughly 6.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.6k tokens, read only when the agent opens those files.

What are the alternatives to Md Document?

Skills that share tags, products or a category with Md Document: Data Viz Deck (thatrebeccarae/claude-marketing, 162 stars), Building With Lobe UI (lobehub/lobe-ui, 2.2k stars), Using Docs Kit (lobehub/lobe-ui, 2.2k stars) and Web Design (drewnekota/cetus, 146 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Md Document?

alirezarezvani (a GitHub user) maintains it in alirezarezvani/claude-skills, which has 27,788 GitHub stars. The repository holds 342 skills in this directory. The repository was last updated on August 30, 2026.

Source: alirezarezvani/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.