Moving from another tool3 of 5

MkDocs

Bring a documentation site across from MkDocs with one command, keeping every address, every link and the way its pages are written.

2 min read

On this page

Only move what's yours. HotDog's importers are migration tools, for moving a site you own, or have the rights to, onto HotDog CMS. They're not for copying anyone else's site, posts or pictures. Every import says so when it starts, and again at the top of its report.

HotDog reads MkDocs' own way of writing: notes (!!! tip), notes that open (??? info), tabs (=== "Linux"), keys (++ctrl+k++), and the rest (see Notes, tabs and keys). So your pages come across as they are, and the import is about putting things where HotDog expects them.

Bring it in

A documentation site usually lives at an address of its own, like docs.example.org. Start a HotDog site for it, and take out the starter's front page, because your docs' front page goes there:

hotdog-cms new docs
cd docs
rm content/index.md

Then point the importer at the folder that holds your mkdocs.yml:

hotdog-cms import mkdocs -from ../old-docs
hotdog-cms check

It adds the docs pack if the site hasn't got it, and tells you what it did:

430 page(s), 44 other file(s), 0 skipped, 52 nav entries; 0 page(s) to look at. Details: IMPORT-REPORT.md

Run hotdog-cms serve and look around.

Docs inside a bigger site

To put the docs under /docs/ on a site that has its own front page, import with -path /docs/ and keep content/index.md.

What happens

  • Pages go under content/docs/ as written. A page's first heading becomes its title, and index.md (or README.md) becomes its folder's own page.
  • Addresses stay. run/sizing.md is still at /run/sizing/, because the docs are set to live at the root of the site (path: / in site.yaml).
  • Links keep landing. Links between pages' files are followed when the site is built. Headings get the same anchors MkDocs gives them, so a link to sizing.md#memory still finds its section. Links to pictures and downloads are fixed for the page's address.
  • Pictures and other files in your docs folder go into static/, at the same addresses.
  • The nav in mkdocs.yml becomes data/docs-nav.yaml: the sidebar, the breadcrumb, the previous and next links. Sections can hold sections. Without a nav, the files' order is used, as MkDocs does.
  • Settings: the site's name, address and description come from mkdocs.yml if your site.yaml still has the new site's. Key names from pymdownx.keys come too.

What doesn't come across

The report, IMPORT-REPORT.md, lists each page that uses something HotDog shows as plain text, and each setting in mkdocs.yml it doesn't use:

  • snippets (--8<--) and template tags from the macros plugin;
  • abbreviations, and icons and emoji like :material-check:;
  • Mermaid diagrams, which show as their code;
  • colors in code blocks;
  • your theme's overrides and extra CSS and JavaScript: the site's own look replaces the theme. That's usually the point of moving.

HTML in your pages

MkDocs lets any HTML in a page through. HotDog cleans it, so a <script>, an inline <svg> drawing or a style="" is taken out, and the report names each one.

If everyone who writes your docs can be trusted with scripts, import with -trust-html to turn the cleaning off for the site:

hotdog-cms import mkdocs -from ../old-docs -trust-html
Why clean HTML at all?

A documentation site is often written by many people, through pull requests and the editor. Cleaning means a page can't carry a script that runs for every reader. Turn it off only when you'd trust each writer with the site's code itself.

↑↓ moveEnter openEsc close