Documentation Site on GitHub Pages (#2376)

* Add initial documentations * Update documentation for Basic Client and add WebSocket section * feat: add a static site generator with multi-language support - Introduced a new Rust-based static site generator in the `docs-gen` directory. - Implemented core functionality for building sites from markdown files, including: - Configuration loading from `config.toml`. - Markdown rendering with frontmatter support. - Navigation generation based on page structure. - Static file copying and output directory management. - Added templates for base layout, pages, and portal. - Created a CSS file for styling and a JavaScript file for interactive features like language selection and theme toggling. - Updated documentation source with new configuration and example pages in English and Japanese. - Added a `justfile` target for building the documentation site. * Add language/theme toggle functionality - Created a new Japanese tour index page at docs/ja/tour/index.html - Implemented navigation links for various sections of the cpp-httplib tutorial - Added a language selector to switch between English and Japanese - Introduced theme toggle functionality to switch between light and dark modes - Added mobile sidebar toggle for better navigation on smaller screens
2026-04-12 03:38:30 +00:00 · 2026-02-28 14:45:40 -05:00
parent 85b18a9c64
commit 797758a742
66 changed files with 12361 additions and 0 deletions
--- a/docs-gen/README.md
+++ b/docs-gen/README.md
@@ -0,0 +1,148 @@
+# docs-gen
+
+A simple static site generator written in Rust. Designed for multi-language documentation sites with Markdown content, Tera templates, and syntax highlighting.
+
+## Build
+
+```
+cargo build --release --manifest-path docs-gen/Cargo.toml
+```
+
+## Usage
+
+```
+docs-gen [SRC] [--out OUT]
+```
+
+- `SRC` — Source directory containing `config.toml` (default: `.`)
+- `--out OUT` — Output directory (default: `docs`)
+
+Example:
+
+```
+./docs-gen/target/release/docs-gen docs-src --out docs
+```
+
+## Source Directory Structure
+
+```
+docs-src/
+├── config.toml          # Site configuration
+├── pages/               # Markdown content (one subdirectory per language)
+│   ├── en/
+│   │   ├── index.md     # Portal page (no sidebar)
+│   │   ├── tour/
+│   │   │   ├── index.md # Section index
+│   │   │   ├── 01-getting-started.md
+│   │   │   └── ...
+│   │   └── cookbook/
+│   │       └── index.md
+│   └── ja/
+│       └── ...          # Same structure as en/
+├── templates/           # Tera HTML templates
+│   ├── base.html        # Base layout (header, scripts)
+│   ├── page.html        # Content page with sidebar navigation
+│   └── portal.html      # Portal page without sidebar
+└── static/              # Static assets (copied as-is to output root)
+    ├── css/
+    └── js/
+```
+
+## config.toml
+
+```toml
+[site]
+title = "My Project"
+base_url = "https://example.github.io/my-project"
+
+[i18n]
+default_lang = "en"
+langs = ["en", "ja"]
+
+[highlight]
+theme = "base16-eighties.dark"        # Dark mode syntax theme (syntect built-in)
+theme_light = "base16-ocean.light"    # Light mode syntax theme (optional)
+```
+
+When `theme_light` is set, code blocks are rendered twice (dark and light) and toggled via CSS classes `.code-dark` / `.code-light`.
+
+Available themes: `base16-ocean.dark`, `base16-ocean.light`, `base16-eighties.dark`, `base16-mocha.dark`, `InspiredGitHub`, `Solarized (dark)`, `Solarized (light)`.
+
+## Markdown Frontmatter
+
+Every `.md` file requires YAML frontmatter:
+
+```yaml
+---
+title: "Page Title"
+order: 1
+---
+```
+
+| Field    | Required | Description |
+|----------|----------|-------------|
+| `title`  | yes      | Page title shown in heading and browser tab |
+| `order`  | no       | Sort order within the section (default: `0`) |
+| `status` | no       | Set to `"draft"` to show a DRAFT banner |
+
+## URL Routing
+
+Markdown files are mapped to URLs as follows:
+
+| File path             | URL             | Output file              |
+|-----------------------|-----------------|--------------------------|
+| `en/index.md`         | `/en/`          | `en/index.html`          |
+| `en/tour/index.md`    | `/en/tour/`     | `en/tour/index.html`     |
+| `en/tour/01-foo.md`   | `/en/tour/01-foo/` | `en/tour/01-foo/index.html` |
+
+A root `index.html` is generated automatically, redirecting `/` to `/<default_lang>/` (respecting `localStorage` preference).
+
+## Navigation
+
+Navigation is generated automatically from the directory structure:
+
+- Each subdirectory under a language becomes a **section**
+- The section's `index.md` title is used as the section heading
+- Pages within a section are sorted by `order`, then by filename
+- `portal.html` template is used for root `index.md` (no sidebar)
+- `page.html` template is used for all other pages (with sidebar)
+
+## Template Variables
+
+Templates use [Tera](https://keats.github.io/tera/) syntax. Available variables:
+
+### All templates
+
+| Variable      | Type   | Description |
+|---------------|--------|-------------|
+| `page.title`  | string | Page title from frontmatter |
+| `page.url`    | string | Page URL path |
+| `page.status` | string? | `"draft"` or null |
+| `content`     | string | Rendered HTML content (use `{{ content \| safe }}`) |
+| `lang`        | string | Current language code |
+| `site.title`  | string | Site title from config |
+| `site.base_url` | string | Base URL from config |
+| `site.langs`  | list   | Available language codes |
+
+### page.html only
+
+| Variable           | Type   | Description |
+|--------------------|--------|-------------|
+| `nav`              | list   | Navigation sections |
+| `nav[].title`      | string | Section title |
+| `nav[].url`        | string | Section URL |
+| `nav[].active`     | bool   | Whether this section contains the current page |
+| `nav[].children`   | list   | Child pages |
+| `nav[].children[].title` | string | Page title |
+| `nav[].children[].url`   | string | Page URL |
+| `nav[].children[].active` | bool  | Whether this is the current page |
+
+## Dependencies
+
+- [pulldown-cmark](https://crates.io/crates/pulldown-cmark) — Markdown parsing
+- [tera](https://crates.io/crates/tera) — Template engine
+- [syntect](https://crates.io/crates/syntect) — Syntax highlighting
+- [walkdir](https://crates.io/crates/walkdir) — Directory traversal
+- [serde](https://crates.io/crates/serde) / [serde_yml](https://crates.io/crates/serde_yml) / [toml](https://crates.io/crates/toml) — Serialization
+- [clap](https://crates.io/crates/clap) — CLI argument parsing
+- [anyhow](https://crates.io/crates/anyhow) — Error handling