MkDocs -> Marque

MkDocs is a good fit for migration when the project is still basically "markdown files plus a nav: tree".

The cleaner the mkdocs.yml, the cleaner the migration. Standard docs/ content and a normal nested nav: block translate best.

Run it

Auto-detect

sh
marque migrate ./my-docs

This creates ./my-docs-marque.

Explicit source

sh
marque migrate ./my-docs ./my-docs-marque --from mkdocs

Pick layout and theme

sh
marque migrate ./my-docs ./my-docs-marque --from mkdocs --layout sidebar --theme comte

What gets imported

Config values

Marque reads the parts of mkdocs.yml that map cleanly:

  • site_name
  • site_description
  • docs_dir
  • nav

Pages and assets

txt
docs/**/*.md     -> pages/**/*.mq
docs/** assets   -> static/**

If docs_dir points somewhere else, Marque uses that directory instead of docs/.

Navigation

A standard MkDocs nav: tree becomes navigation.mq.

If there is no usable nav tree, Marque falls back to generating the navigation file from the file tree and records that in migration notes.

What still needs manual review

Theme

MkDocs theme settings are noted, but they are not converted automatically into a Marque theme.

Extensions and plugins

These are called out for manual review when present:

  • plugins
  • markdown_extensions
  • extra_css
  • extra_javascript
  • hooks

Runtime assumptions

If the old site depended on Material features, custom JS hooks, or plugin-generated pages, expect a real clean-up pass after the import.

Mental model for the result

You keep

  • most markdown content
  • the rough navigation structure
  • copied assets
  • rewritten local page links

You redo

  • the final visual design
  • plugin behaviour
  • special markdown extension behaviour
  • extra CSS and JavaScript wiring

Suggested clean-up pass

Run the migration and serve the generated Marque site locally.

Open navigation.mq and confirm the imported labels and nesting still make sense outside MkDocs.

Read pages/migration-notes.mq for any theme, plugin, extension, or navigation warnings.

Rebuild the final polish in Marque themes, layouts, and directives instead of trying to preserve the old MkDocs runtime.

MkDocs migration goes best when the source site is content-first. The more the old site leaned on plugins and theme magic, the more the last 20 per cent becomes your job.