Migrating from mkdocs

Migrating from mkdocs

bxSites migrate --from=mkdocs converts an mkdocs project - mkdocs.yml plus its docs/ folder - into a complete bx-sites project, in one command:

bxSites migrate --source=/path/to/mkdocs-project --from=mkdocs

• --source (required) - the mkdocs project's root directory (must contain mkdocs.yml)

Unlike migrating from GitBook, this is mostly a config translation, not a content one. mkdocs' own docs/ folder already uses bx-sites' exact conventions - folder nesting is nav structure, index.md is a folder's own home page, and relative .md links between pages just work. More to the point: mkdocs-material's own extended Markdown syntax is the same textual syntax bx-sites already speaks, because bx-sites modeled itself on mkdocs-material to begin with (see Markdown Extensions). So page bodies are copied across byte-for-byte unchanged - nothing here needs to rewrite !!! note admonitions, === "Tab" content tabs, or $x^2$ math, because they're already valid bx-sites syntax.

What gets converted automatically

mkdocs.yml → bxsites.yaml:

Every other markdown_extensions entry mkdocs-material's own syntax already covers natively - admonition, pymdownx.tabbed, pymdownx.details, pymdownx.superfences, pymdownx.highlight, toc, attr_list, and more - needs no bxsites.yaml change at all; bx-sites already behaves that way out of the box.

nav: → docs/nav.json:

# mkdocs.yml
nav:
  - Home: index.md
  - Guide:
      - Setup: guide/setup.md
      - Advanced: guide/advanced.md
  - About: about.md

becomes:

[
  { "title": "Home", "path": "index.md", "children": [] },
  { "title": "Guide", "path": "", "children": [
    { "title": "Setup", "path": "guide/setup.md", "children": [] },
    { "title": "Advanced", "path": "guide/advanced.md", "children": [] }
  ] },
  { "title": "About", "path": "about.md", "children": [] }
]

• a bare path entry (- about.md, no explicit title) converts too - its title comes from the migrated page's own frontmatter/first-heading, the same as any bx-sites docs/nav.json entry with no title set
• see Configuration: nav for the full format

Pages and assets:

• every .md file is copied to the same path under docs/, unchanged
• every other file (images, PDFs, ...) is relocated to docs/assets/mkdocs/<same-relative-path> - bx-sites' own asset pipeline only ever publishes docs/assets/**, and mkdocs has no single asset-folder convention of its own the way GitBook's .gitbook/assets/ is, so images are commonly scattered next to the pages that use them
• every reference to a relocated asset - ![diagram](img/diagram.png), say - is rewritten to the correct relative path reaching its new location, accounting for how deep the linking page itself sits (the same "author writes the right number of ../" convention any bx-sites project already uses - computed for you here instead of left to a find-and-replace)

What needs a manual look

Reported as warnings in the command's own output, nothing is silently dropped:

• an mkdocs markdown_extensions/plugins entry with no bx-sites equivalent (mkdocs-material's own emoji shortcodes, a third-party plugin like awesome-pages or git-revision-date) - if you need the same behavior, see Plugins
• mkdocs.yml's own color/font customization (theme.palette/theme.font) has no direct equivalent - see Customizing colors once the migration is done
• a theme.name other than material (defaulted to bootstrap)

Worked example

bxSites new --projectRoot=my-docs
bxSites migrate --projectRoot=my-docs --source=../my-mkdocs-project --from=mkdocs
cd my-docs
bxSites serve

migrate writes bxsites.yaml and docs/ itself - the new step above is only there to get a project root with docs/ ready to receive them; migrate creates docs/ on its own too, so it's not strictly required. Review the command's own warnings, then serve to see the result before committing it.