Metadata-Version: 2.4
Name: docsforge
Version: 10.9.2
Summary: Drop-in replacement for MkDocs and Material for MkDocs. Self-contained documentation engine with vendored theme, plugins, KaTeX math, offline search, and zero external dependencies.
Project-URL: Documentation, https://qqshi13.github.io/docsforge
Project-URL: Source, https://github.com/QQSHI13/docsforge
Project-URL: Issues, https://github.com/QQSHI13/docsforge/issues
Author: DocsForge Contributors
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Requires-Dist: babel>=2.9.0
Requires-Dist: backrefs>=5.0
Requires-Dist: click>=7.0
Requires-Dist: colorama>=0.4
Requires-Dist: csscompressor>=0.9.5
Requires-Dist: ghp-import>=1.0
Requires-Dist: jinja2>=2.11.1
Requires-Dist: jsmin>=3.0
Requires-Dist: lunr>=0.7
Requires-Dist: markdown>=3.3.6
Requires-Dist: markupsafe>=2.0.1
Requires-Dist: mergedeep>=1.3.4
Requires-Dist: minify-html>=0.18
Requires-Dist: packaging>=20.5
Requires-Dist: paginate>=0.5
Requires-Dist: pathspec>=0.11.1
Requires-Dist: platformdirs>=2.2.0
Requires-Dist: pygments>=2.16
Requires-Dist: pymdown-extensions>=10.0
Requires-Dist: pyyaml-env-tag>=0.1
Requires-Dist: pyyaml>=5.1
Requires-Dist: requests>=2.27
Requires-Dist: watchdog>=2.0
Provides-Extra: all
Requires-Dist: cairosvg>=2.6; extra == 'all'
Requires-Dist: jieba>=0.42; extra == 'all'
Requires-Dist: pillow>=10.2; extra == 'all'
Provides-Extra: chinese
Requires-Dist: jieba>=0.42; extra == 'chinese'
Provides-Extra: imaging
Requires-Dist: cairosvg>=2.6; extra == 'imaging'
Requires-Dist: pillow>=10.2; extra == 'imaging'
Description-Content-Type: text/markdown

# 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 breaking changes and large updates until v11.0.0.

[![PyPI](https://img.shields.io/pypi/v/docsforge)](https://pypi.org/project/docsforge/)
[![Docs](https://img.shields.io/badge/docs-online-blue)](https://qqshi13.github.io/docsforge-docs/)
[![License](https://img.shields.io/badge/license-LGPL%20v3-blue.svg)](LICENSE)

**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](https://qqshi13.github.io/docsforge-docs/)** | 📦 **[PyPI](https://pypi.org/project/docsforge/)** | 🐙 **[GitHub](https://github.com/QQSHI13/docsforge)** | 🔄 **[Migrate from MkDocs](#migrating-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 on every build | 🔒 **Zero external network calls** — everything vendored |
| **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

**One command converts your project:**

```bash
# In your existing MkDocs project directory
pip install docsforge
docsforge migrate        # converts mkdocs.yml → docsforge.yml
docsforge build          # builds your site
docsforge serve          # live preview
```

`docsforge migrate` reads your `mkdocs.yml`, converts it to `docsforge.yml`, and reports which plugins are supported and which need attention.

```bash
docsforge migrate --dry-run    # preview changes without writing
docsforge migrate --force      # overwrite existing docsforge.yml
```

**What gets migrated automatically:**
- Site configuration (name, URL, repo, nav)
- Material theme settings
- Supported plugins (search, tags, blog, info, meta, minify, privacy, social, offline, etc.)
- Markdown extensions
- Custom CSS/JS

**DocsForge auto-detects legacy configs:** If you run `docsforge build` in a directory with `mkdocs.yml` but no `docsforge.yml`, it will suggest running `docsforge migrate`.

---

## What Makes DocsForge Different

### 🔒 Zero External Network Calls
Every asset is vendored: KaTeX for math, Mermaid for diagrams, all fonts and icons, the Material theme itself. Your docs build in an air-gapped environment.

### 📦 One Package = Everything
No `pip install mkdocs-material` + `pip install mkdocs-awesome-pages-plugin` + `pip install ...`. Just:

```bash
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, social, offline, optimize, typeset
- 📝 **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

```bash
pip install docsforge
```

Requires **Python 3.10+**.

---

## Quick Start

```bash
# Create a new project
docsforge new my-docs
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:

1. `docsforge.yml` / `docsforge.yaml` ← **preferred**
2. `mkdocs.yml` / `mkdocs.yaml` ← legacy fallback (shows migration hint)

### Minimal `docsforge.yml`

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

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

### Full example

```yaml
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 new <name>` | Scaffold a new project |
| `docsforge serve` | Live-reload dev server |
| `docsforge build` | Static site build |
| `docsforge migrate` | **Convert mkdocs.yml → docsforge.yml** |
| `docsforge gh-deploy` | Deploy to GitHub Pages |

---

## 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, self-hosted fonts, vendored dependencies, zero-config documentation.

---

## Changelog

See [full changelog](https://qqshi13.github.io/docsforge-docs/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 (Cyrus) and Nova ☄️ — because documentation tools should just work.*

## Star History

<a href="https://www.star-history.com/?repos=QQSHI13%2Fdocsforge&type=date&legend=top-left">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=QQSHI13/docsforge&type=date&theme=dark&legend=top-left" />
 <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=QQSHI13/docsforge&type=date&legend=top-left" />
 <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=QQSHI13/docsforge&type=date&legend=top-left" />
 </picture>
</a>
