Docs Site Generator: Markdown to a Docs Website

About the Docs Site Generator: Markdown to a Docs Website

Drop in your Markdown pages, or a whole docs folder, and get a complete documentation website: a sidebar built from your folders, search across every page, light and dark themes, “On this page” links, previous and next links, “Edit this page” links to your repository, code with syntax colours, tables, task lists, footnotes, GitHub-style alerts (> [!NOTE], [!TIP], [!WARNING]…), :::tip blocks and math written with $ signs. The site is plain HTML, CSS and two small scripts: upload it to any static host, from GitHub Pages to your own server.

It also writes what search engines and AI assistants read: sitemap.xml and robots.txt for your site’s address, canonical links, and llms.txt as llmstxt.org proposes it, with a Markdown copy of every page and llms-full.txt with all of them in one file. Every link between pages, every anchor and every picture is checked before you publish, with the line to fix.

Everything happens in your browser; your pages are not uploaded. Without a pass the result is a free preview: the list of the site’s files, its first pages (up to 3) in the preview under a watermark, and the checks’ counts with the first findings; the ZIP of the site and llms.txt unlock with a Premium pass.

Common uses

• Publishing the documentation of a library, an API or a command-line tool from the Markdown already in its repository.
• Turning a team’s how-to notes into a searchable internal knowledge base on any web host.
• Giving AI assistants a clean llms.txt and Markdown copies of your docs, so they answer questions about your product correctly.
• Checking a docs folder for broken links and missing pictures before a release.

What goes into the site

• One HTML page per Markdown file, at guide/install/ (a folder with index.html, for web hosts) or guide/install.html (which also opens straight from your disk). index.md or README.md is the page of its folder; without one at the top a home page lists the sections.
• The navigation follows your folders. Front matter orders and names pages (title, description, nav_order, nav_title, hidden: true, draft: true to leave a page out, slug for its address); a number in front of a name (02-install.md) orders it and is left out of the address.
• Markdown as GitHub writes it: tables, task lists, footnotes, strikethrough, heading anchors made the way GitHub makes them, and the five GitHub alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION). :::note, :::tip, :::warning and :::danger blocks take a title of your own.
• Code gets its colours when the site is built, so the pages need no script for them. Math between $ signs becomes MathML, which current versions of every major browser show without a script (MDN); $5 and $10 stays text.
• Search works on every page from a small index file, also when the site is opened from disk; press / to start typing.

For search engines and AI assistants

• sitemap.xml and robots.txt are written when you give the site’s address: sitemaps take “fully-qualified, absolute URLs” and up to 50,000 of them per file (Google Search Central). Every page also gets a canonical link and a description from its front matter or first paragraph.
• llms.txt follows the llms.txt proposal: the site’s name as the only required heading, your one-line description as a quote, then a section per folder with a link list, and an “Optional” section that, in the proposal’s words, holds “links an agent can skip when a shorter context is needed”. Each link goes to a clean Markdown copy of the page at the same address with .md, as the proposal recommends, and each page points to its copy with rel="alternate" type="text/markdown".
• llms-full.txt puts every page’s Markdown in one file, a common companion to llms.txt.

The checks

• Broken links: a link to a page or file that is not in your project (errors), and a link to a #heading that does not exist on the page it points to (warnings).
• Missing pictures, and files no page links to.
• Titles and headings: pages without a title, more than one # heading, headings that skip a level, empty pages, front matter that cannot be read, and formulas that cannot be read.
• Each finding names the file and the line: select it to jump there in the editor.

Limitations

• Diagrams written as mermaid code blocks show as their code; draw them as SVG pictures to show them as diagrams.
• HTML written in a page goes into the site as written (switch it off to show it as text); its img and a tags are not rewritten or checked the way Markdown links are.
• One project holds up to 2,000 pages, 2 MB per page and 25 MB per picture or file, and up to 5,000 files or 300 MB are read at once.
• The site has one language and one version; translated or versioned docs need one site each.
• ::: blocks cannot be put inside one another.

Privacy

On this device: nothing is sent

Your pages and pictures are read and built into the site in your browser. Nothing is uploaded. The site’s settings are remembered on this device; your pages stay until you leave the page, unless you save the project.