Migration Guide

Moving from MkDocs/Material to DocsForge is straightforward for most sites. This guide covers what migrates easily and what requires effort.

One-line migration

If you have an existing mkdocs.yml, properdocs.yml, or zensical.toml, migrate it automatically:

curl -fsSL https://qqshi13.github.io/docsforge/migrate.sh | bash

irm https://qqshi13.github.io/docsforge/migrate.ps1 | iex

The script converts navigation, theme, plugins, and extensions into
docsforge.yml, warns about anything it can't migrate (third-party plugins,
INHERIT, hooks), and prints a report with next steps. For anything it
misses, see Support — we'll help you port it.

Easy to Migrate (Zero/Low Effort)

Requires Some Effort

Requires Significant Effort

MkDocs Plugin Migration Guide

MkDocs plugins are not compatible with DocsForge. Below is a mapping of common MkDocs plugins to their DocsForge equivalents or workarounds.

Built-in (Zero Effort)

These MkDocs plugins have direct built-in equivalents in DocsForge — remove from plugins: and they load automatically:

Config-Compatible (Copy Plugin Config)

These MkDocs plugins are not supported, but their features can be replicated with DocsForge's built-in capabilities:

No Direct Equivalent (Requires Custom Work)

Custom MkDocs Plugins

Plugins that extend MkDocs' BasePlugin class or hook into MkDocs events (on_page_markdown, on_page_content, etc.) need to be rewritten for DocsForge's plugin system:

1. DocsForge uses the same event names (on_page_markdown, on_post_build, etc.) — many MkDocs plugins can be adapted by changing the import from mkdocs.plugins to docsforge.core.plugin_base.
2. The config schema uses DocsForge's Config class instead of MkDocs' BaseConfig.
3. See the plugin development guide for details.

Markdown Extensions

All MkDocs-compatible Markdown extensions work directly. DocsForge uses the same python-markdown package with pymdown-extensions. Copy your markdown_extensions: block as-is:

markdown_extensions:
  - admonition
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  # ... all your existing extensions work unchanged

The 31 most common extensions are already pre-enabled — you only need to list them if you want custom configuration.

Config Key Migration

Deprecated / Removed Keys

OI Wiki uses several advanced features. Here's how each maps:

Estimated Migration Effort

• Basic content + styling: < 1 hour
• Custom hooks + extensions: 2–4 hours
• Post-build pipeline: 4–8 hours
• Full OI Wiki migration: ~1–2 days for a developer familiar with both systems

Feature Parity: Material vs DocsForge

Step-by-Step Migration

1. Backup Your Site

cp mkdocs.yml mkdocs.yml.bak
git add -A && git commit -m "backup before docsforge migration"

2. Create docsforge.yml

Copy your mkdocs.yml to docsforge.yml. Most settings work directly:

site_name: Your Site
site_url: https://yourdomain.com
copyright: Copyright © 2025

nav:
  - Home: index.md
  # ... copy your nav structure

# Theme settings work as-is
theme:
  name: material
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

# Extra CSS/JS copy directly
extra_css:
  - stylesheets/extra.css
extra_javascript:
  - javascripts/extra.js

# Markdown extensions copy directly
markdown_extensions:
  - admonition
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  # ... etc

plugins:
  - tags
  - search
  # - blog        # built-in, customize only if needed

3. Convert Config Keys

DocsForge uses docsforge.yml with the same schema as mkdocs.yml. Replace these keys:

4. Install DocsForge

pip install docsforge

5. Build and Test

cd your-project
docsforge build
# Check site/ directory
docsforge serve

6. Deploy

DocsForge outputs static HTML to site/ — deploy to any static host. See Deployment Guide for platform-specific instructions.

Troubleshooting

Getting Help

• GitHub Issues: github.com/QQSHI13/docsforge/issues
• Docs: qqshi13.github.io/docsforge