# md2html: a portable AI skill that turns long Markdown into a single HTML page
> md2html is a three-file skill for Claude Code, Codex and other agents that analyzes a long Markdown document and writes one self-contained HTML page next to it. It is not a converter, and that distinction decides who should adopt it.
**haidang1810/md2html** — Your AI writes docs — md2html turns them into pages people actually read. A portable skill for Claude Code / Codex / Antigravity that converts long-form Markdown (plans, specs, system designs, RFCs, runbooks, postmortems, brainstorms) into self-contained HTML with Mermaid, timelines, callouts, TOC. Multi-language.
- Repository: https://github.com/haidang1810/md2html
- Stars: 421 · Forks: 27
- Language: HTML
- License: MIT
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/haidang1810-md2html
## The problem md2html targets: nobody reads the second half of a long Markdown file
The README opens with a scene most teams recognize. An agent produces two thousand words of system design with three architecture options compared, and the reader stops at section two because the whole thing is a monospace wall in a terminal scrollback. The same applies to the migration plan, the postmortem draft and the brainstorm doc. Sharing a plan.md link does not fix it either, since the recipient has to render it themselves.
md2html is aimed at people who already generate long-form Markdown with an AI agent and want the output to look like a page rather than a file. The README lists the document types explicitly: plans, specs, system designs, RFC-style proposals, runbooks, postmortems, brainstorms and notes. The audience is narrow on purpose. If you write short README files or commit messages, the skill has nothing to work with.
## How the skill works: the agent analyzes, the template renders
There is no parser and no build step. The README is direct about this: md2html is not a Markdown-to-HTML converter, it is an analyzer. When you type the command, the agent reads your Markdown file, then opens two files from the repository, template.html and components.md, and writes a single HTML file next to the source.
The interesting part is the mapping table in the README. A numbered list of actions becomes step cards with a timeline rail. Prose like "A calls B, B writes to DB" becomes a Mermaid flowchart. A "Pros / Cons" section becomes a two-column box, and "Option A vs B vs C" becomes comparison cards with a starred recommendation. Warnings become danger callouts, and long appendices become collapsible panels. The agent makes those calls per document, so two Markdown files with the same headings can produce different layouts.
That design has a consequence worth naming. Because the analysis is done by a language model rather than by rules, the output is not byte-reproducible. The same input run twice can yield different component choices. The repository ships examples/example-plan.md and examples/example-plan.html so you can see one intended pairing, but the README does not describe a way to pin the mapping.
## Installing md2html for Claude Code and running a first document
The README calls the install zero-dependency: no npm, no Docker, no Python. For Claude Code, it is a git clone into the skills directory.
```bash
git clone https://github.com/haidang1810/md2html ~/.claude/skills/md2html
```
After cloning, reload your session so the skill is picked up. The command is then a slash command followed by the file you want processed.
```
/md2html plan.md
```
The README states this writes plan.html next to the source file. There are two other forms: an explicit output path, and a bare invocation that prompts you for a file.
```
/md2html plan.md --out docs/x.html
/md2html
```
For Codex CLI the repository takes a different route, cloning to a config directory and symlinking SKILL.md into the prompts directory. The README warns that Codex's prompts directory has shifted across versions and that you may need to adjust the symlink target. For Antigravity, you clone the repo, open Settings, then Custom Agents, then New, and paste the contents of SKILL.md into the agent, granting it file-read access to the clone. Any other agent that accepts custom instructions and can read and write local files follows the same pattern.
## What you get in the generated page, and what it costs
The output is one HTML file with embedded CSS and theme JavaScript. The README lists a sidebar table of contents with scroll-spy, anchor links on headings, copy-to-clipboard buttons on code blocks and a scroll progress bar. Accessibility work is described as well: WCAG AA contrast, touch targets of at least 40 px, prefers-reduced-motion support, focus-visible rings, a mobile TOC drawer that closes on the backdrop or the ESC key, a skip-to-content link and a print stylesheet.
The self-contained claim has one exception the README admits: the only network request is the Mermaid CDN. It adds that you can inline Mermaid too if that matters to you. For a document opened on a plane or pasted into a chat tool, that exception is the thing to check first, because diagrams will not render without it.
Theme customization happens through CSS variables at the top of template.html. The README points at the :root and [data-theme="dark"] blocks for accent color, surface, fonts and radii. The description mentions a light and dark Claude-orange theme, so the default palette is opinionated rather than neutral.
## Multi-language output and the RTL gap
UI labels follow the source document's language. The README says the built-in label table covers English, Vietnamese, Chinese, Japanese, Korean, Spanish, French and German. For anything outside that list, the agent translates the labels and sets both the lang attribute on the html element and the --rec-label CSS variable.
The limitation is stated plainly in the README: RTL languages are LTR-only for now. If your team writes in Arabic, Hebrew or Farsi, the labels may translate but the layout direction will not follow, and the README does not offer a workaround.
The repository itself is multi-language in a second sense. The demo file, examples/example-plan.md, has a Vietnamese source, and the screenshots in the README come from a longer game economy design document. That is a useful pair to inspect, because it shows what a non-English source produces without you having to install anything.
## Where md2html is the wrong tool
The skill depends on an agent that can read and write files. If your pipeline is a CI job with no model in the loop, md2html does not fit, because there is no standalone binary to call. The README frames the skill as agent-hosted throughout, and the install steps are all about placing files where an agent will find them.
Determinism is the second boundary. Documentation pipelines that diff generated output between commits will not get stable results, since the component selection is a judgement call made per run. If you need a converter with predictable output, this is the wrong category of tool.
There is also the question of what the skill does not do. It produces a page, not a site. There is no routing, no search index, no versioning and no server. The README's own framing is that you email the file or drop it in Slack. Teams expecting a docs platform will be disappointed, and the README does not claim otherwise.
## How it differs from a plain Markdown converter
A conventional converter such as Pandoc or a marked-based build takes a Markdown file and applies a fixed set of rules: headings become heading tags, tables become table tags, and the same input always yields the same output. Styling is your problem afterward.
md2html inverts that. The transformation is decided by the agent reading the document, so a trade-off discussion can become comparison cards instead of a paragraph. The README's table of mappings is the clearest statement of the difference, and the phrase it uses is that the result feels designed rather than converted.
The trade-off is real in both directions. A converter is scriptable, testable and cheap to run over a thousand files. md2html is none of those things, but it can decide that your appendix belongs in a collapsed panel. If your documents are few and long, the second behavior is worth more. If they are many and short, it is not.
## Licence, maintenance and what upgrading involves
The repository is MIT licensed, which permits commercial and private use with the licence and copyright notice retained. That is a statement about the licence text, not legal advice; check how your organization handles attribution for vendored files.
The skill is not a package, so there is no lockfile and no version resolution. Upgrading means pulling the clone in the directory where you placed it, which replaces SKILL.md, components.md and template.html in one move. Any edits you made to the template's CSS variables will be overwritten by that pull, so local theme work belongs in a fork or a separate copy rather than in the clone itself.
The last push to the repository was on 2026-05-14, and the only release listed is v0.1.0 from the same day. The repository is not archived, but the README does not describe a deprecation policy or a compatibility guarantee for the template. Treat the file layout as the interface and check it after any pull.
## Conclusion
Adopt md2html if your documents are long, structured and produced by an agent that can read and write local files, and if you want a single HTML artifact you can email or drop in Slack. Skip it if you need a deterministic batch converter, a CLI you can run in CI without an agent, or RTL output, since the README states RTL is LTR-only for now. Before relying on it, open template.html and confirm the :root variables match your brand, then run /md2html on examples/example-plan.md and compare the result against examples/example-plan.html.
## FAQ
### How can I convert a Markdown file to a website with md2html?
Install the skill into your agent's skills directory, then run the slash command with your file. The README states the result is one self-contained HTML file written next to the source, which you can open in a browser or send to someone else.
### Is md2html the same as a Markdown-to-HTML converter?
No. The README states it is an analyzer rather than a converter: the agent reads the document and decides which sections become Mermaid diagrams, step cards, comparison cards or collapsible panels, instead of applying one fixed set of rules to every file.
### Does md2html work outside Claude Code?
Yes, if the agent accepts custom instructions and can read and write local files. The README gives setup steps for Codex CLI and Antigravity, and says any other agent follows the same pattern of cloning the repo and pasting SKILL.md into its instructions.
### Does the generated md2html page need a server or a network connection?
The HTML is self-contained with embedded CSS and theme JavaScript, so it opens from the filesystem. The README notes one network request for the Mermaid CDN, and says you can inline Mermaid if you need the page to work fully offline.
### Which languages does the md2html interface support?
The built-in label table covers English, Vietnamese, Chinese, Japanese, Korean, Spanish, French and German. For other languages the README says the agent translates the labels and sets the lang attribute plus the --rec-label CSS variable, though RTL languages are LTR-only for now.
## Sources
- [haidang1810/md2html on GitHub](https://github.com/haidang1810/md2html)
- [Issues](https://github.com/haidang1810/md2html/issues)
- [License: MIT](https://github.com/haidang1810/md2html/blob/main/LICENSE)
- [README](https://github.com/haidang1810/md2html/blob/main/README.md)
- [Releases](https://github.com/haidang1810/md2html/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/haidang1810-md2html