DLSlime Documentation

May 10, 2026 · View on GitHub

This directory contains the DLSlime documentation site. The site uses MkDocs Material with bilingual English/Chinese pages, explicit navigation, and GitHub Pages publishing.

Prerequisites

  • Python 3.10+
  • uv for local development, or pip for CI-style installs

Quick Start

Run these commands from the docs/ directory:

cd docs

make install
make serve

Useful commands:

make serve        # local preview with live reload
make serve-dirty  # faster dirty reload if normal reload is slow
make serve-versioned
make build        # build static site into docs/site/
make check-links  # check links under docs/src/
make deploy-dev   # build versioned docs into gh-pages as dev/latest
make deploy-version VERSION=0.1.0
make clean        # remove generated artifacts

Structure

docs/
├── mkdocs.yml
├── Makefile
├── pyproject.toml
├── requirements.txt
├── src/
│   ├── index.md
│   ├── index.zh.md
│   ├── installation.md
│   ├── quickstart.md
│   ├── guide/
│   ├── design/
│   ├── platform/
│   ├── api_reference.md
│   └── assets/
└── imgs/                 # legacy image location used by root README

Translation

The documentation uses suffix-based i18n:

  • page.md is the English source.
  • page.zh.md is the Chinese source.
  • If a Chinese page is missing, MkDocs falls back to the English page.

Publishing

.github/workflows/docs.yml builds and publishes the site to GitHub Pages when documentation changes land on main or master. Branch builds are published as dev with the latest alias. Git tags matching v* are published as release versions, for example v0.1.0 becomes version 0.1.0. The workflow can also be run manually from GitHub Actions.

Version switching is powered by mike. The local docs/src/versions.json file is useful for static builds, but a faithful local preview of the dropdown uses mike's versioned server:

cd docs
make deploy-dev
make serve-versioned

make deploy-dev uses mkdocs.local.yml so local language links point at the local mike serve root. The GitHub Actions workflow uses mkdocs.yml, where site_url keeps the /DLSlime/ project-pages prefix. Deployed versions.json metadata is generated by mike on the gh-pages branch.

Older Markdown files directly under docs/ are kept for repository links and README compatibility. New content should be added under docs/src/ and wired into docs/mkdocs.yml.