Migration

Use marque migrate when you already have a markdown docs project and want the content in Marque without rebuilding the whole thing by hand.

Migration is designed to import the content and navigation quickly.
It is not a promise to carry over every plugin, theme, hook, or runtime behaviour from the old tool.

Supported today

mdBook

book.toml, src/SUMMARY.md, and src/**/*.md map naturally onto marque.toml, navigation.mq, and pages/**/*.mq.

MkDocs

mkdocs.yml plus docs/**/*.md also translates well, especially when the site uses a normal nav: tree and markdown pages.

What not to expect

Themes, preprocessors, plugins, extra CSS or JS hooks, and framework-specific markup still need a manual pass after the import.

Fast flow

Run marque migrate against the old project.

Open the generated site and serve it locally.

Read pages/migration-notes.mq inside the migrated site.

Clean up navigation, theme, layout, and any tool-specific extras that Marque intentionally does not port automatically.

Commands

Auto-detect the source

sh
marque migrate ./old-docs

If you do not pass a target directory, Marque creates one next to the source folder with -marque appended.

Explicit source

sh
marque migrate ./old-book ./new-marque --from mdbook
marque migrate ./old-site ./new-marque --from mkdocs

Pick the starter shell

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

If you omit these flags, the migration starts with sidebar and comte.

What Marque brings over

Content

Markdown pages are copied into pages/ and renamed from .md to .mq.

Navigation

src/SUMMARY.md from mdBook or nav: from MkDocs becomes navigation.mq.

Assets

Non-markdown files from the source docs tree are copied into static/ with matching relative paths.

Internal links

Local markdown links are rewritten from .md targets to the matching .mq pages so Marque can resolve them to HTML.

Site config

The migrated site gets a fresh marque.toml using the imported site title and description when they are available.

Review page

Marque also creates pages/migration-notes.mq so skipped metadata and unsupported features are impossible to miss.

What still needs you

Review the generated navigation.mq and confirm labels, nesting, and ordering.

Rebuild the original visual design as a Marque theme or layout instead of expecting source themes to carry across automatically.

Check plugins, preprocessors, extra JavaScript, MDX, or framework-specific markup by hand.

Open the generated migration-notes.mq page and clear every warning before treating the migration as finished.

Structure mapping

mdBook

txt
book.toml        -> marque.toml
src/SUMMARY.md   -> navigation.mq
src/**/*.md      -> pages/**/*.mq
src/** assets    -> static/**

MkDocs

txt
mkdocs.yml       -> marque.toml + navigation.mq
docs/**/*.md     -> pages/**/*.mq
docs/** assets   -> static/**

Pick the source-specific guide

From mdBook

SUMMARY.md, book.toml, and the default mdBook structure map very cleanly into Marque.

From MkDocs

This path works best when the project uses a normal docs/ folder plus a standard nav: tree in mkdocs.yml.

The goal is "you are 70 to 90 per cent done and reviewing a real site", not "your old project survived the trip without needing taste or judgement".