Metadata-Version: 2.4
Name: docsforge
Version: 10.4.0
Summary: Self-contained unified documentation engine with Material theme.
Project-URL: Documentation, https://qqshi13.github.io/docsforge-docs
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
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: 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: ghp-import>=1.0
Requires-Dist: jinja2>=2.11.1
Requires-Dist: markdown>=3.3.6
Requires-Dist: markupsafe>=2.0.1
Requires-Dist: mergedeep>=1.3.4
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: imaging
Requires-Dist: cairosvg>=2.6; extra == 'imaging'
Requires-Dist: pillow>=10.2; extra == 'imaging'
Description-Content-Type: text/markdown

# DocsForge

> **One package. One command. Beautiful docs.**

[![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)

Write your documentation in Markdown. Build a professional static site in seconds. Deploy anywhere.

📖 **[Documentation](https://qqshi13.github.io/docsforge-docs/)** | 📦 **[PyPI](https://pypi.org/project/docsforge/)** | 🐙 **[GitHub](https://github.com/QQSHI13/docsforge)**

---

## What is DocsForge?

DocsForge is a **self-contained documentation engine**. Everything you need is bundled into one package:

- ⚡ **Engine** — ProperDocs (MkDocs fork), vendored
- 🎨 **Theme** — Material for MkDocs, vendored  
- 🔌 **Plugins** — 7 plugins built-in (search, tags, blog, info, meta, minify, privacy)
- 📝 **Markdown** — 31 extensions pre-configured (all pymdownx + python-markdown)
- ➗ **Math** — KaTeX vendored (`$$...$$` works out of the box)
- 🖍️ **Highlighting** — Pygments for code blocks at build time
- 📐 **Diagrams** — TikZ support (auto-compiled to SVG)
- 🔍 **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)

`pip install docsforge` and you're done. No CDN, no extra config, no external dependencies.

---

## 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/
```

---

## What's Built In

### 📝 Documentation
| Feature | Status |
|---------|--------|
| Admonitions (`!!! note`) | ✅ Zero config |
| Math (`$$...$$`) | ✅ Zero config |
| Code highlighting | ✅ Zero config |
| Tables, task lists, footnotes | ✅ Zero config |
| Definition lists, abbreviations | ✅ Zero config |
| Content tabs, diagrams (Mermaid, TikZ) | ✅ Zero config |

### 🔍 Discovery
| Feature | Status |
|---------|--------|
| Full-text search (Lunr.js) | ✅ Zero config |
| Tags and tag pages | ✅ Zero config |
| Navigation with sections/tabs | ✅ Zero config |
| Table of contents | ✅ Zero config |

### 🎨 Theming
| Feature | Status |
|---------|--------|
| Material theme (light/dark) | ✅ Zero config |
| Customizable colors/fonts | ✅ Zero config |
| 14,000+ icons | ✅ Zero config |

### 📝 Blogging
| Feature | Status |
|---------|--------|
| Author profiles | ✅ Zero config |
| Categories, tags, archives | ✅ Zero config |
| Pagination | ✅ Zero config |
| RSS feeds | ✅ Zero config |

### 🌐 Publishing
| Feature | Status |
|---------|--------|
| Static HTML output | ✅ Zero config |
| GitHub Pages workflow | ✅ Zero config |
| PWA with offline support | ✅ Zero config |
| Minified HTML/CSS/JS | ✅ Zero config |

---

## Config File

DocsForge looks for config in this priority:

1. `docsforge.yml` / `docsforge.yaml` ← **preferred**
2. `properdocs.yml` / `properdocs.yaml`
3. `mkdocs.yml` / `mkdocs.yaml` ← legacy fallback

### 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 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.

---

## Changelog

See [full changelog](https://qqshi13.github.io/docsforge-docs/changelog/) in the documentation.

Recent highlights:

- **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 ☄️*

## 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>
