How to convert technical docs from markdown to html
- Step 1Remove front matter, then paste the doc — Strip any YAML front matter first (marked doesn't and it leaks into the page). Paste the Markdown or drop the
.mdfile — one document per run. For a multi-file doc set, merge first with md-merger. - Step 2Choose full document or fragment — Keep Full document ON for a standalone reference page with the built-in readable stylesheet. Turn it OFF to get the body fragment for an existing docs theme that supplies its own
<head>and CSS. - Step 3Run the conversion — marked renders the HTML locally and instantly — nothing uploads, which matters for NDA'd or unreleased API docs.
- Step 4Verify reference tables and code samples — Check that parameter/status tables became
<table>and that code samples kept theirlanguage-*class. Remember syntax colour isn't baked in — add a highlighter on the page if you want coloured samples. - Step 5Add heading ids for cross-references — marked emits no heading
ids, so 'see the Authentication section' cross-links and 'on this page' navs won't resolve. Addidattributes to the headings in the output, or let your docs platform generate them on render. - Step 6Publish or hand off — Drop the fragment into your docs theme, or share the self-contained full-document
.html. For a GitHub-styled reference look, use md-to-github-html instead.
Documentation elements and conversion
Verified against marked 14.1.4. These are the constructs technical docs rely on.
| Doc construct | Markdown | HTML output | Supported? |
|---|---|---|---|
| Parameter table | GFM pipe table | <table> with <thead>/<tbody> | Yes |
| Code example | ` http ` | <pre><code class="language-http"> | Yes — class only |
| Deprecation marker | ~~oldField~~ | <del>oldField</del> | Yes |
| Setup checklist | - [ ] step | <input disabled type="checkbox"> | Yes |
| Cross-reference | [Auth](#auth) | <a href="#auth">Auth</a> (target has no id) | Link emitted, anchor won't resolve |
| Note / admonition | > **Note:** … | <blockquote> (no callout styling) | Partial — renders as a quote |
| Footnote | spec[^1] | broken <a href="1">^1</a> | No |
| Math | $O(n)$ | literal $O(n)$ | No |
Full document vs fragment for docs
The single fullDocument option (default true) controls the wrapper and stylesheet.
| Goal | Mode | What you get |
|---|---|---|
| Standalone reference page | Full document ON | Complete page + built-in readable stylesheet (styled pre/code/table/blockquote) |
| Slot into a docs theme | Full document OFF (fragment) | Body HTML only; theme provides head + CSS |
| Stakeholder handoff file | Full document ON | One openable .html they don't need to build |
| GitHub-styled look | use md-to-github-html instead | Primer CSS render (separate sibling tool) |
Tier limits (markdown family)
Per-file limits. Character cap is independent of byte size — large API references can be multibyte-heavy.
| Plan | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 |
| Pro + Media | 50 MB | 20,000,000 | 50 |
| Developer | 500 MB | unlimited | unlimited |
Cookbook
Real technical-doc snippets, the HTML this tool produces, and where docs-specific syntax needs a workaround.
API parameter reference table
The bread and butter of API docs — a parameter table — converts to a full HTML table. Full-document mode adds borders via the built-in stylesheet.
Input: | Field | Type | Required | |---------|--------|----------| | api_key | string | yes | | limit | int | no | Output: <table> <thead><tr><th>Field</th><th>Type</th><th>Required</th></tr></thead> <tbody> <tr><td>api_key</td><td>string</td><td>yes</td></tr> <tr><td>limit</td><td>int</td><td>no</td></tr> </tbody> </table>
Request/response code example
A fenced http or json block keeps its language class so your highlighter can colour request and response samples.
Input: ```http GET /v1/users HTTP/1.1 Authorization: Bearer TOKEN ``` Output: <pre><code class="language-http">GET /v1/users HTTP/1.1 Authorization: Bearer TOKEN </code></pre>
Marking a deprecated field
Strikethrough is a tidy way to flag deprecation in a reference — it converts to a semantic <del> element.
Input: - ~~`legacy_id`~~ (deprecated, use `id`) Output: <ul> <li><del><code>legacy_id</code></del> (deprecated, use <code>id</code>)</li> </ul>
Cross-reference link won't resolve without ids
Docs lean on 'see the X section' links. Because headings have no id, these anchors dead-end in the output. Add ids before publishing.
Input: See the [Authentication](#authentication) section. ## Authentication ... Output: <p>See the <a href="#authentication">Authentication</a> section.</p> <h2>Authentication</h2> <!-- no id="authentication" --> Fix: add id="authentication" to the <h2>.
Admonition becomes a plain blockquote
A '> Note:' callout renders as a blockquote, not a styled admonition box — marked has no callout/admonition syntax. Style the blockquote with theme CSS or add a wrapper.
Input: > **Warning:** This endpoint is rate-limited. Output: <blockquote> <p><strong>Warning:</strong> This endpoint is rate-limited.</p> </blockquote> (No callout box — your CSS styles the blockquote.)
Edge cases and what actually happens
Heading ids absent — cross-refs and on-this-page nav break
By designmarked emits headings with no id attributes, so [Auth](#auth) cross-references and any 'on this page' sidebar built on anchors won't scroll. This is the most consequential gap for reference docs. Add ids to the headings in the output, or rely on your docs platform to slugify headings on render.
Admonitions/callouts render as plain blockquotes
Partial supportmarked has no :::note or callout syntax. A > **Note:** line becomes a <blockquote> with bold text inside — semantically a quote, not a styled callout box. Style the blockquote with CSS, or post-process the HTML to wrap admonitions in your callout component.
Footnotes render as broken links
Not supportedTechnical docs often cite specs via footnotes ([^rfc]). Core marked has no footnote support, so these become broken reference links. Convert footnotes to inline links or an end-of-page references list before converting.
Math / complexity notation stays literal
Not supportedAlgorithm docs with $O(n \log n)$ get no rendering — marked passes the dollar-delimited text through verbatim. Normalise delimiters with md-math-normalizer and load KaTeX/MathJax on the page to actually render math.
No syntax highlighting in code samples
By designCode fences carry class="language-*" but no colour spans. Request/response samples appear as plain monospace until you add highlight.js or Prism. Full-document mode gives a code background but not colouring.
Raw HTML passes through unsanitized
Not sanitizedInline HTML in your docs (custom anchors, <details> accordions, diagrams) passes through verbatim, including <script>. Convenient for first-party docs; sanitize if converting untrusted contributor content for a public site.
Front matter leaks into the page
Remove firstDoc front matter (title, sidebar position, etc.) is not stripped by marked and shows up in the HTML. Remove the --- block before converting so metadata doesn't appear in the rendered reference.
Relative links/images kept verbatim
PreservedInter-doc links like [guide](../guide.md) and image paths are preserved exactly — note .md links won't auto-rewrite to .html. Adjust link targets for the published form, or rewrite image bases with md-image-path-rewriter.
Not the same as your docs theme render
ExpectedFull-document mode uses a generic readable stylesheet, not your portal's theme. It's for standalone pages and handoffs. The fragment, placed in your theme, picks up the theme's CSS and renders correctly there.
Large API reference exceeds the free cap
400 rejectedA big single-page API reference over 500,000 characters / 1 MB is rejected on Free before conversion. Multibyte-heavy references can hit the character cap before the MB cap. Pro raises both to 5,000,000 / 10 MB.
Frequently asked questions
Will cross-reference links between sections work in the output?
Not from this output alone. marked emits headings without id attributes, so [Auth](#auth) anchors have no target. Add id attributes to the headings in the HTML, or rely on your docs platform to slugify headings on render. This is the main thing to plan for in reference docs.
Do GFM tables work for parameter and status-code references?
Yes — pipe tables convert to full <table> elements with <thead> and <tbody>, which is exactly what parameter, return-value, and HTTP-status reference tables need. Full-document mode adds borders via the built-in stylesheet; in fragment mode your theme styles them.
How do admonitions / note boxes convert?
As plain blockquotes. marked has no :::note or callout syntax, so a > **Note:** line becomes a <blockquote>. Style it with CSS, or post-process the HTML to wrap it in your callout component for a proper admonition box.
Are my code samples syntax-highlighted?
Not in this output — code fences get a class="language-http" (or similar) hook but no colour markup. Add highlight.js or Prism to the page to colour request/response and code samples. The class hook is already there for them to use.
Why are my footnotes broken?
Core marked doesn't support footnote syntax, so [^1] becomes a broken reference link. Convert spec citations and footnotes to inline links or a references section before converting.
Does it render math / Big-O notation?
No — marked passes $…$ and $$…$$ through as literal text. Normalise the delimiters with md-math-normalizer and load KaTeX or MathJax on the rendered page to display the math.
Should I use full-document or fragment mode for docs?
Full document ON for a standalone reference page with the built-in readable stylesheet, or a handoff file someone can open without building. Fragment (OFF) when slotting the body into an existing docs theme that already supplies <head> and CSS.
Do inter-doc .md links get rewritten to .html?
No — links are preserved verbatim, so [guide](../guide.md) stays pointing at the .md. Adjust link targets for the published HTML form yourself, or handle it in your docs build. Image bases can be batch-rewritten with md-image-path-rewriter.
Is it safe for internal or pre-release API docs?
Yes. Conversion runs entirely in your browser via marked — NDA'd or unreleased docs never leave your machine. Only an anonymous processed-file counter is stored for dashboard stats, never the content. Note that raw HTML is passed through unsanitized, so sanitize before publishing untrusted content.
How do I get a GitHub-styled reference page?
Use md-to-github-html, which wraps the body in GitHub's Primer CSS for a github.com-style render. This tool's full-document mode uses a simpler generic stylesheet instead.
How large a doc can I convert?
Free: 1 MB / 500,000 characters per file. Pro: 10 MB / 5,000,000. Pro + Media: 50 MB / 20,000,000. Developer: 500 MB / unlimited. Large API references can be multibyte-heavy, so the character cap may bite before the byte limit.
What file name does the download get?
The output is named after your input with the extension swapped to .html — api-reference.md becomes api-reference.html. .mdx, .markdown, and .txt inputs are handled the same way.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.