Usage Guide

DocsForge is a drop-in replacement for MkDocs + Material. This guide covers daily usage, from creating a new site to deploying it.

Quick Start

Create a New Site

# Install DocsForge
pip install docsforge

# Create a new project interactively
docsforge
cd my-docs

# Build and serve
docsforge serve

Build an Existing Site

cd your-project
# Edit docsforge.yml, then:
docsforge build
# Output goes to site/

Commands

Command	Description	Example
`docsforge`	Create a new project interactively	`docsforge`
`docsforge build`	Build the site	`docsforge build`
`docsforge serve`	Build + serve locally with live reload	`docsforge serve`
`docsforge --version`	Show version	`docsforge --version`
`docsforge --help`	Show help	`docsforge --help`

Configuration (`docsforge.yml`)

Basic Config

site_name: My Documentation
site_url: https://example.com/docs
site_description: A great docs site
site_author: Your Name

copyright: Copyright © 2025

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Reference: reference.md

docs_dir: docs
site_dir: site

Theme Customization

theme:
  name: material
  logo: assets/logo.png
  favicon: assets/favicon.png

  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

  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.action.edit

Language & Search

theme:
  language: en

  # Multi-language search pipeline
  search:
    language: en
    pipeline:
      - stemmer
      - stopWordFilter
      - trimmer

Markdown Extensions

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.emoji:
      emoji_index: !!python/name:docsforge.emoji.twemoji
      emoji_generator: !!python/name:docsforge.emoji.to_svg
  - tables
  - toc:
      permalink: true

Plugins

Built-in plugins are loaded automatically. You only need to declare plugins when you want to customize them:

plugins:
  - search:
      lang: en
  - tags:
      tags_file: tags.md
  - blog:
      blog_dir: blog
      blog_toc: true

Content Features

Admonitions (Callouts)

!!! note
    This is a note.

!!! warning "Be careful"
    This is a warning with a custom title.

!!! tip
    This is a tip.

    It can have multiple paragraphs.

!!! danger
    Don't do this!

Code Blocks

```python
print("hello")

key: value

With annotations:
```markdown
```python
print("hello")  # (1)!

This is an annotation!

### Content Tabs
```markdown
=== "Python"

    ```python
    print("hello")
    ```

=== "JavaScript"

    ```javascript
    console.log("hello");
    ```

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Mermaid Diagrams

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

### Math (KaTeX)
```markdown
Inline: $E = mc^2$

Block:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

Git Integration

Revision Dates

DocsForge automatically shows when each page was last updated, powered by git history. No plugin configuration is needed.

Edit Links

edit_uri: edit/main/docs/

Adds an "Edit this page" button linking to your repo.

PWA / Offline Support

DocsForge generates a Progressive Web App automatically. Features:
- Offline access: Service worker caches pages
- Installable: Add to home screen on mobile
- Auto-update: Checks for new content on each visit

No configuration needed — it's automatic!

Search

Full-text search is built-in. Features:
- Instant results: Search as you type
- Highlighting: Matches highlighted in results
- Suggestions: Auto-complete suggestions
- Multi-language: Supports Chinese, English, and more

Asset Handling

Images

![Alt text](assets/image.png)

Place images in docs/assets/ (or your docs_dir).

CSS & JS

extra_css:
  - stylesheets/custom.css
extra_javascript:
  - javascripts/custom.js

Place files in docs/stylesheets/ and docs/javascripts/.

Performance Tips

Incremental Builds

Both docsforge build and docsforge serve use incremental builds by default. Only changed pages are rebuilt, which is fast for large sites.

Build Optimization

DocsForge automatically optimizes after each build:
- Removes unused icons and assets
- Strips source maps
- Removes old font formats (keeps only WOFF2)
- Gzips sitemap

No manual steps needed.

Troubleshooting

Issue	Solution
`ModuleNotFoundError`	`pip install docsforge`
Theme not found	DocsForge bundles Material — no extra install needed
Search not working	Ensure `search` plugin is in `plugins:` list
CSS not loading	Check path is relative to `docs_dir`
Build is slow	Incremental builds are on by default; restart `docsforge serve` if needed
Icons missing	Use `material/` prefix (e.g., `material/home`)

Next Steps

Publishing → — Deploy to GitHub Pages, Netlify, Vercel, and more
Migration Guide — Moving from MkDocs/Material
Changelog — What's new