DocsForge
The drop-in replacement for MkDocs + Material for MkDocs. One package. One command. Beautiful docs. Zero CDN calls. โ ๏ธ Development Mode: DocsForge is under active development. Expect frequent updates and possible instability until v12.0.0; use with caution in production.
DocsForge is a self-contained, actively-maintained documentation engine. 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 + Material | DocsForge | |
|---|---|---|
| Maintenance | โ ๏ธ MkDocs is unmaintained; Material is maintenance-only | โ Actively developed |
| Installation | pip install mkdocs-material + 15+ plugins separately |
pip install docsforge โ everything included |
| CDN calls | Google Fonts, KaTeX, Mermaid loaded from CDN in the browser | ๐ Zero CDN calls โ external assets are fetched during the build and served locally, so readers never call a CDN |
| Math rendering | Requires internet or manual KaTeX setup | โ KaTeX vendored, works offline instantly |
| Diagrams | Mermaid loaded from CDN | โ Mermaid vendored |
| Icons | Downloaded at build time | โ 14,000+ icons included |
| Privacy | External font/icon requests | โ All assets self-hosted |
| Search | Plugin + external JS | โ Lunr.js built-in, works offline |
| PWA / Offline | Not included | โ Service worker + offline cache built-in |
DocsForge is everything MkDocs + Material does, in one package, with zero external dependencies.
Migrating from MkDocs
To migrate an existing MkDocs project, manually convert mkdocs.yml to docsforge.yml:
- Rename
mkdocs.ymltodocsforge.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
See the migration guide for a detailed walkthrough.
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 fork, vendored and maintained
- ๐จ Theme โ Material for MkDocs, fully included
- ๐ Plugins โ 7 built-in: search, tags, blog, info, meta, minify, privacy
- ๐ Markdown โ 31 extensions pre-configured (pymdownx + python-markdown)
- โ Math โ KaTeX vendored (
$$...$$works out of the box) - ๐๏ธ Highlighting โ Pygments at build time
- ๐ Diagrams โ TikZ auto-compiled to SVG, Mermaid built-in
- ๐ Search โ Lunr.js client-side full-text search
- ๐ 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)
๐ Production-Ready Defaults
Sensible defaults for everything. No config file needed for basic sites. Add a docsforge.yml when you need customization.
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โ preferredmkdocs.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:
- Home: index.md
- Getting started: getting-started.md
- Blog:
- 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 |
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 (network-first, updates 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, static site generation with Markdown.
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, zero-config documentation.
Changelog
See full changelog in the documentation.
Recent highlights:
- v10.4.1 โ Mermaid auto-config, search plugin cleanup
- v10.3.3 โ Versioned service worker with auto cache cleanup
- v10.3.0 โ TikZ diagrams, blog plugin, theme playground
- v10.1.0 โ Zero-config Markdown, KaTeX math, dark mode toggle
License
LGPL v3-or-later
DocsForge is built by QQ and Nova โ๏ธ โ because documentation tools should just work.
Install VSCode Extension
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/QQSHI13/docsforge/main/scripts/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/QQSHI13/docsforge/main/scripts/install.ps1 | iex
Star History
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file docsforge-11.6.1.tar.gz.
File metadata
- Download URL: docsforge-11.6.1.tar.gz
- Upload date:
- Size: 4.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8eb8f937a562c88e7f769ad5cfc8d50a4d387c943b3d22547ed386cbbf58749a
|
|
| MD5 |
22d5d868b56f3080896d0a64be8b63e1
|
|
| BLAKE2b-256 |
b40ad1af9a68738d5cf7e26e308b8f421fca9fe5510d3cc7050e6a2f5191c1ee
|
Provenance
The following attestation bundles were made for docsforge-11.6.1.tar.gz:
Publisher:
release.yml on QQSHI13/docsforge
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
docsforge-11.6.1.tar.gz -
Subject digest:
8eb8f937a562c88e7f769ad5cfc8d50a4d387c943b3d22547ed386cbbf58749a - Sigstore transparency entry: 2311953933
- Sigstore integration time:
-
Permalink:
QQSHI13/docsforge@fdac671a24a21287b1191a5dcfcfd9e7f148c550 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/QQSHI13
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fdac671a24a21287b1191a5dcfcfd9e7f148c550 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file docsforge-11.6.1-py3-none-any.whl.
File metadata
- Download URL: docsforge-11.6.1-py3-none-any.whl
- Upload date:
- Size: 10.3 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a0db0fbbc6f14d4380d7e92b71f5acc631d9078493f6430c77917510f641dada
|
|
| MD5 |
9499401f55435d710e0cd7fa6fb90367
|
|
| BLAKE2b-256 |
e5663a38ba17e63204f32b198c494acf8a549221d6ddc3d607fffe45a34e2465
|
Provenance
The following attestation bundles were made for docsforge-11.6.1-py3-none-any.whl:
Publisher:
release.yml on QQSHI13/docsforge
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
docsforge-11.6.1-py3-none-any.whl -
Subject digest:
a0db0fbbc6f14d4380d7e92b71f5acc631d9078493f6430c77917510f641dada - Sigstore transparency entry: 2311953935
- Sigstore integration time:
-
Permalink:
QQSHI13/docsforge@fdac671a24a21287b1191a5dcfcfd9e7f148c550 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/QQSHI13
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fdac671a24a21287b1191a5dcfcfd9e7f148c550 -
Trigger Event:
workflow_dispatch
-
Statement type:
