Migrate from Material for MkDocsCopy Anchor Link

Material for MkDocs uses Markdown plus Python Markdown extensions, plugins, Jinja macros, and theme overrides. Standard prose moves directly, while mkdocs.yml navigation and extension syntax need structured conversion.

1. Inventory the sourceCopy Anchor Link

Collect:

• mkdocs.yml and any inherited config files
• docs_dir, commonly docs/
• explicit nav
• markdown_extensions
• plugins, hooks, macros, and generated pages
• theme.custom_dir overrides
• extra_css, extra_javascript, extra, and social metadata
• requirements.txt, pyproject.toml, lock files, and plugin versions
• redirects, versioning, localization, and deployment configuration

2. Map the filesCopy Anchor Link

3. Preserve routingCopy Anchor Link

Routes can depend on docs_dir, site_url, use_directory_urls, and plugins. Build a route list from the deployed site or MkDocs build before moving files.

Translate nav in its exact YAML order. Headings become directory groups and file entries become pages. Add numeric order frontmatter and create landing pages for groups that need content.

Preserve old paths through destination filenames or tested redirects.

4. Convert frontmatter and macrosCopy Anchor Link

Keep portable YAML fields such as title, description, tags, and dates. Review Material-specific fields and plugin metadata.

Search for Jinja and macros:

{{ variable }}
{% include "file.md" %}
{% if ... %}

Replace static values with resolved content. Replace reusable dynamic behavior with a registered component or explicit build step. Never leave Jinja syntax expecting MDX to evaluate it.

5. Convert Markdown extensionsCopy Anchor Link

Indentation is significant in Python Markdown extensions. Convert the entire block rather than editing only its opening line.

6. Replace plugins and theme overridesCopy Anchor Link

Classify each plugin:

• search → Farming Labs search
• redirects → host/runtime redirects
• versioning → explicit version routes or separate deployments
• macros → resolved content or components
• literate navigation → target file hierarchy
• blog or generated pages → separate content/application migration
• minification and sitemap → target build and sitemap

Jinja templates under theme.custom_dir are application UI, not Markdown. Rebuild only the behavior still required using the target runtime and theme configuration.

7. Move assets and linksCopy Anchor Link

Copy assets from the docs tree or configured directories. Verify:

• relative images
• root-relative assets
• downloadable files
• image captions and alignment extensions
• cross-page anchors
• generated link references

Do not copy the generated site/ directory as source content.

8. Validate and recoverCopy Anchor Link

1. Run the target production build.
2. Compare every nav entry and published route.
3. Search the target for unconverted !!!, ???, ===, --8<--, {{, and {%.
4. Test admonitions, tabs, includes, diagrams, code annotations, and assets.
5. Verify redirects, search, versions, and locales.
6. Fetch representative pages through .md.

If extension syntax appears as text, convert that extension family corpus-wide. If plugin-generated pages are missing, materialize their output or keep the plugin-backed site until an explicit target replacement exists.

Source referencesCopy Anchor Link

• Material for MkDocs navigation
• Material for MkDocs reference
• Material for MkDocs admonitions
• Material for MkDocs content tabs
• Farming Labs configuration