DocsForge

The drop-in replacement for MkDocs + Material for MkDocs. One package. One command. Beautiful docs. Zero CDN calls.

DocsForge

DocsForge is a self-contained, actively-maintained documentation engine — a vendored ProperDocs/MkDocs engine plus the Material theme, plugins, search, math, diagrams, and offline support in a single Python package. If you use MkDocs, Material for MkDocs, or are looking for a modern alternative, you're in the right place.

Documentation | PyPI | GitHub | Migrate from MkDocs

Why DocsForge?

MkDocs core has seen no real development for 18+ months and Material for MkDocs is in maintenance mode through its 2027 end-of-life, with its team focused on Zensical. DocsForge continues that stack as an independent, Apache-2.0 engine — no migration of your content required.

	DocsForge	Alternatives
MkDocs + Material	Vendored engine + theme, maintained, one install	Plugin sprawl across dozens of packages; upstream frozen
Docusaurus	No Node.js toolchain needed	Requires Node + React; heavy client JS
Sphinx / Read the Docs	Markdown-first	reStructuredText-first; Markdown is second-class
VitePress / VuePress	No Node.js toolchain needed	Requires Node + Vue
Hugo	Docs-specific: versioning, search, i18n, offline built in	General static generator; docs features come via themes
Zensical	Free, open engine + free Studio extension	Rust core, but editor refactoring and governance are paid tiers
GitBook	Self-hosted static output you own	Hosted SaaS platform

DocsForge is everything MkDocs + Material does, in one package, with zero external dependencies.

Migrating from MkDocs

To migrate an existing MkDocs project automatically, run the one-liner — it converts mkdocs.yml / properdocs.yml / zensical.toml to docsforge.yml:

macOS / Linux:

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

Windows (PowerShell):

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

The script converts navigation, theme, plugins, and extensions, warns about anything it can't migrate, and prints a report. See the migration guide for the manual, key-by-key walkthrough (also fine for a small site):

Rename mkdocs.yml to docsforge.yml.
Keep the theme: block as-is (DocsForge uses the built-in Material theme).
Remove built-in plugins and extensions from explicit lists — they are loaded by default.
Remove KaTeX, Mermaid, font, and icon CDN references — these are vendored.

Then build and preview:

pip install docsforge
docsforge build          # builds your site
docsforge serve          # live preview

What Makes DocsForge Different

Zero CDN Calls

DocsForge fetches external assets (such as fonts, icons, and emojis) during the build process and serves them from your site. Readers never contact a CDN, so your docs load fast, work offline, and respect privacy.

One Package = Everything

No pip install mkdocs-material + pip install mkdocs-awesome-pages-plugin + pip install .... Just:

pip install docsforge

You get:

Engine — ProperDocs/MkDocs fork, vendored and maintained (no longer tracks upstream, so it can evolve independently)
Theme — Material for MkDocs, fully included
Plugins — 8 built-in: search, tags, blog, info, meta, minify, privacy, i18n
Markdown — 39 extensions pre-configured (36 default + 3 built-in, pymdownx + python-markdown)
Math — KaTeX vendored ($$...$$ works out of the box, offline)
Highlighting — Pygments at build time
Diagrams — TikZ auto-compiled to SVG (requires a LaTeX toolchain), Mermaid built-in
Search — Marz engine (Rust core, CJK-aware) with offline WASM retrieval
Dark mode — Light/dark toggle with auto system detection
Offline — Service worker caches all assets for PWA support
Fonts — Self-hosted (privacy plugin downloads Google Fonts locally)
Bilingual docs — English/Chinese twin pages with per-locale navigation, search indexes, and translation diagnostics

Sensible Defaults

Most behavior works out of the box; a two-line docsforge.yml is a complete site (see below). Add configuration only when you need customization.

Requirements

Python 3.10+ and pip — the only hard requirements.
LaTeX toolchain — only for TikZ diagrams (texlive + dvisvgm).
Playwright + Chromium — only for PDF export (pip install "docsforge[pdf]").
pillow + cairosvg — only for social cards (pip install "docsforge[social]").
Node.js / pnpm — only for contributors rebuilding the frontend theme.

Known Limitations

Honest accounting of where DocsForge is weaker:

Smaller plugin universe. MkDocs has hundreds of community plugins; DocsForge vendors 8 core ones. Anything outside that needs a custom plugin or stays behind.
Diverged theme. The Material fork no longer tracks upstream, so upstream features and fixes don't flow in automatically — everything is maintained in-tree.
Build speed is Python speed. Parallel incremental builds keep iteration fast, but cold full-site builds can't match Rust-based engines on very large sites.
Editor support is VS Code (+ forks like Cursor) only. Studio is built directly on the VS Code extension API with no language server, so Zed, JetBrains IDEs, and Neovim are out of reach by design.
Search index ships the corpus. The full-text index downloads to every reader; very large sites should watch its size (per-locale indexes and position stripping help).
TikZ and PDF are heavyweight. Both shell out to large external toolchains rather than working out of the box like the rest.

Installation

pip install docsforge

Requires Python 3.10+.

Quick Start

# Create a new project interactively
docsforge
# Follow the prompts, then:
cd my-docs

# Start the dev server
docsforge serve
# → http://localhost:8000

# Build for production
docsforge build
# → site/

Config File

DocsForge looks for config in this priority:

docsforge.yml / docsforge.yaml ← preferred
mkdocs.yml / mkdocs.yaml ← legacy fallback (shows migration hint)

Minimal `docsforge.yml`

site_name: My Documentation
site_url: https://example.com/

That's it. All plugins, extensions, and theme settings use sensible defaults.

Full example

site_name: My Docs
site_url: https://example.com/
site_author: Your Name

repo_url: https://github.com/username/repo

nav:
  - title: Home
    path: index.md
  - title: Getting started
    path: getting-started.md
  - title: Blog
    children:
      - path: blog/index.md

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

CLI Reference

Command	Description
`docsforge`	Interactive project setup (when no config exists)
`docsforge serve`	Live-reload dev server (`-n` skips auto-open, `--lan` serves on all interfaces)
`docsforge build`	Static site build
`docsforge --version`	Show version
`docsforge --help`	Show help

PWA / Offline Support

Every built site includes a service worker that:

Caches HTML pages (cache-first, refreshed in background)
Caches assets (CSS, JS, fonts, images — cache-first for speed)
Versioned updates — Each build generates a unique SW hash, forcing browser refresh
Auto cleanup — Old caches purged when new version activates

No configuration needed. Works offline after the first visit.

Keywords

DocsForge is the best alternative to: MkDocs, Material for MkDocs, Docusaurus, GitBook, ReadTheDocs, VuePress, Hugo documentation.

Use DocsForge for: Python project documentation, API docs, technical documentation, knowledge bases, blogs, product docs, internal wikis, open-source project sites, bilingual English/Chinese documentation, offline documentation.

Features: static site generator, markdown documentation, material design theme, dark mode, offline support, PWA, KaTeX math, Mermaid diagrams, TikZ diagrams, built-in search, tags, blogging, privacy-focused, no CDN for readers, self-hosted fonts, vendored dependencies, bilingual documentation.

Changelog

See the full changelog in the documentation.

License

Apache-2.0

DocsForge is built by QQ and Nova ☄️ — because documentation tools should just work.

Install VSCode Extension

Install DocsForge Studio from the .vsix attached to the latest release:

code --install-extension docsforge-vscode-<version>.vsix

or install it via the VS Code UI: Extensions view → ... → Install from VSIX.

Star History

Metadata

Release files for docsforge 13.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for docsforge 13.0.2
File	Size	Uploaded
docsforge-13.0.2.tar.gz	8.7 MB	Sep 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for docsforge 13.0.2
File	Interpreter	ABI	Platform	Reset
docsforge-13.0.2-py3-none-any.whl 18.2 MB Sep 23, 2026	Python 3	none	any	Details

Total release size: 26.9 MB

Release files / docsforge-13.0.2.tar.gz

Download URL	docsforge-13.0.2.tar.gz
Size	8.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`5dfccfadc95ae9be08cb7a04f59814b595fad3f143e2b48ec2f33cf5914fc6a7`
BLAKE2b-256 checksum How to use checksums	`559c95039f274902e26f396fae80abc1b19c19fba395f28bd39a378681ff2668`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/QQSHI13/docsforge
Publishing commit: github.com/QQSHI13/docsforge/tree/9dbc4d7253a01f9922c13801b9a235a66a965d5c

Workflow

Publishing configuration: github.com/QQSHI13/docsforge/blob/9dbc4d7253a01f9922c13801b9a235a66a965d5c/.github/workflows/release.yml
Publishing logs: github.com/QQSHI13/docsforge/actions/runs/35862734651/attempts/1

Artifact

Subject: docsforge-13.0.2.tar.gz
SHA-256 checksum: 5dfccfadc95ae9be08cb7a04f59814b595fad3f143e2b48ec2f33cf5914fc6a7 Verifying attestations

Release files / docsforge-13.0.2-py3-none-any.whl

Download URL	docsforge-13.0.2-py3-none-any.whl
Size	18.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`03812dcce8f0cc3b97f6a52f08bcd189a088ae52ece1f023195579ff4e342fec`
BLAKE2b-256 checksum How to use checksums	`c47fd5710b8f9dacf0bc68a132b312528f966aa12a0d74fa29024f54867c0fc9`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/QQSHI13/docsforge
Publishing commit: github.com/QQSHI13/docsforge/tree/9dbc4d7253a01f9922c13801b9a235a66a965d5c

Workflow

Publishing configuration: github.com/QQSHI13/docsforge/blob/9dbc4d7253a01f9922c13801b9a235a66a965d5c/.github/workflows/release.yml
Publishing logs: github.com/QQSHI13/docsforge/actions/runs/35862734651/attempts/1

Artifact

Subject: docsforge-13.0.2-py3-none-any.whl
SHA-256 checksum: 03812dcce8f0cc3b97f6a52f08bcd189a088ae52ece1f023195579ff4e342fec Verifying attestations