Skip to content

2026

  • 1 min read

Multi-Language Docs with Suffix-Mode i18n

DocsForge's i18n uses sibling files instead of per-locale directory
trees. A translated page is just the same file with a locale suffix:

docs/
├── index.md       # English (default)
├── index.zh.md    # 中文
└── getting-started.md
└── getting-started.zh.md

Why suffix mode?

  • No URL forks — every locale shares one canonical URL; the language
    switcher stores your preference and the service worker serves the right
    sibling.
  • No duplication — assets live once at the root; untranslated pages
    simply have no sibling.
  • Simple nav — per-locale titles are declared inline:
nav:
  - title: Getting started
    path: getting-started.md
    i18n:
      zh: 入门

Search follows the locale

Each locale gets its own search index (search_index.zh.json), so search
on the Chinese site searches Chinese pages. The preference persists across
visits via IndexedDB — and it works on 404 pages too.

This very site is a live example: switch to 中文 in the header and the whole
documentation — this post included — flips languages.

  • 1 min read

Most documentation tooling ships a language server to power editor features.
DocsForge takes a different route: the build itself validates your docs,
and the VS Code extension reads the results.

During docsforge build (and every serve rebuild), DocsForge:

  • resolves every relative link and image against the docs tree,
  • cross-checks page.md#anchor links against the target page's headings,
  • checks footnotes and nav entries,
  • and persists everything to .docsforge/cache/validation.json.

A broken cross-link surfaces even when only the target page changed —
validation is re-emitted for every page on every build.

The extension reads that file

DocsForge Studio turns the validation data into:

  • squiggles on every occurrence of a broken link or anchor,
  • Fix link / Fix all broken links code actions,
  • Rename Document and Rename Anchor refactors that rewrite every
    inbound link — translation-aware, so renaming a .zh file renames its
    base and all locale variants.

No language server, no background indexer, no paid tier — just the build
output you already have. Run docsforge serve and watch the squiggles
appear (and disappear) as you edit.

  • 1 min read

Publication-Quality Diagrams with TikZ

DocsForge compiles TikZ diagrams to SVG at build time — no client-side
JavaScript, no browser plugin, just crisp vector graphics in your docs.

The workflow

TikZ diagrams live as .tex files. Drop them anywhere under your docs
directory and reference them like any image:

![Binary Entropy](assets/tikz/binary-entropy.svg)

When a LaTeX toolchain is available, DocsForge compiles each diagram with
latex + dvisvgm (or pdflatex + pdf2svg) and caches the result — a
change to the .tex file triggers a rebuild, everything else is skipped.

Why TikZ?

MermaidTikZ
SyntaxText-based, simpleLaTeX-based, powerful
Math supportLimitedFull LaTeX math
PrecisionLayout by algorithmPixel-perfect
BuildNoneCompile to SVG

See the diagram demo for five live examples, including
the Shannon communication model and a neural network diagram.

Graceful degradation

If no LaTeX toolchain is installed, the build warns and skips compilation
instead of failing. Install texlive texlive-pictures dvisvgm to enable it.

  • 1 min read

Introducing DocsForge

Today I'm launching DocsForge — a self-contained documentation engine.

What is DocsForge?

DocsForge is a fork of MkDocs + Material for MkDocs with all dependencies vendored. Install once, document forever.

Features

  • ✅ Zero external dependencies
  • ✅ All plugins built-in
  • ✅ Material theme included
  • ✅ Blog, tags, search, privacy, minify, info, meta, i18n

Quick Start

pip install docsforge
docsforge serve

That's it. Start writing markdown.

Posted on 2026-05-10 by QQ

  • 1 min read

Math Rendering in DocsForge

DocsForge includes KaTeX for zero-config math rendering.

Inline Math

You can write \(E = mc^2\) inline with single dollar signs.

Display Math

\[ \sum_{i=1}^{n} x_i = \frac{1}{n} \sum_{i=1}^{n} x_i \cdot n \]

Complex Equations

\[ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \end{aligned} \]

Works out of the box — no configuration needed!

  • 1 min read

Code Highlighting with Pygments

DocsForge uses Pygments for build-time syntax highlighting.

Python

def hello_world():
    """Say hello to DocsForge."""
    print("Hello, World!")
    return True

Rust

fn main() {
    println!("Hello from Rust!");
}

Go

package main

import "fmt"

func main() {
    fmt.Println("Hello from Go!")
}

No client-side JavaScript required!