docs: add MkDocs Material documentation website
Renders the root markdown (manual, tools, changelog) into a static, searchable HTML site with client-side (lunr.js) search and a dark/light theme. Built in Docker via website/build-docs.sh (no host installs). Public URL is set at build time with SITE_URL=... (default is a neutral placeholder; the site works at any URL since site_url only affects the sitemap/canonical links). Generated output (website/_build/) is gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marcus Kida
parent
5ae4fa70bd
commit
35ba6e9975
5 changed files with 154 additions and 0 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -5,3 +5,6 @@ codec_bin_section_1.bin
|
|||
# Generated language plugin files + host-side builder binary
|
||||
*.gla
|
||||
languages_builder
|
||||
|
||||
# Generated docs site
|
||||
website/_build/
|
||||
|
|
|
|||
|
|
@ -11,6 +11,10 @@ single running list until the first versioned release.
|
|||
OpenGD77 features and FreeTRX additions, each tagged 🟢 [FreeTRX] or ⚪
|
||||
[OpenGD77]. Includes the spectrum scope (VFO sweep, hold `#`), channel add/delete,
|
||||
mute, dimming, and a button reference.
|
||||
- **Documentation website** (`website/`) — MkDocs Material config that renders the
|
||||
markdown into a static, searchable HTML site (client-side search, dark/light
|
||||
theme). Built in Docker via `./website/build-docs.sh`; the public URL is set with
|
||||
`SITE_URL=…`. For self-hosting on Forgejo.
|
||||
|
||||
## 0.4.0
|
||||
|
||||
|
|
|
|||
49
website/build-docs.sh
Normal file
49
website/build-docs.sh
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
#!/usr/bin/env bash
|
||||
#
|
||||
# Build the FreeTRX documentation website (MkDocs Material) entirely in Docker.
|
||||
# Source markdown lives in the repo root; this assembles it into _build/docs and
|
||||
# renders a static, self-contained HTML site with client-side search into
|
||||
# website/_build/site.
|
||||
#
|
||||
# Usage: ./website/build-docs.sh # build
|
||||
# ./website/build-docs.sh serve # live-reload preview on http://localhost:8000
|
||||
set -euo pipefail
|
||||
|
||||
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT="$(cd "$HERE/.." && pwd)"
|
||||
SRC="$HERE/_build/docs"
|
||||
IMAGE="squidfunk/mkdocs-material:9"
|
||||
|
||||
# ---- assemble the docs source tree from the root markdown -----------------
|
||||
rm -rf "$HERE/_build"
|
||||
mkdir -p "$SRC/images"
|
||||
|
||||
cp "$HERE/home.md" "$SRC/index.md"
|
||||
cp "$ROOT/MANUAL.md" "$SRC/MANUAL.md"
|
||||
cp "$ROOT/TOOLS.md" "$SRC/TOOLS.md"
|
||||
cp "$ROOT/CHANGELOG.md" "$SRC/CHANGELOG.md"
|
||||
cp "$ROOT"/docs/images/*.png "$SRC/images/" 2>/dev/null || true
|
||||
|
||||
# MANUAL.md links back to README.md (a repo file, not a site page) -> point it at
|
||||
# the site home instead.
|
||||
sed -i.bak 's#(README.md)#(index.md)#g' "$SRC/MANUAL.md" && rm -f "$SRC/MANUAL.md.bak"
|
||||
|
||||
# Optional public URL (sitemap / canonical only). Set SITE_URL to override the
|
||||
# placeholder in mkdocs.yml — the site works at any URL regardless.
|
||||
ENVARGS=()
|
||||
if [[ -n "${SITE_URL:-}" ]]; then
|
||||
echo "==> Site URL: $SITE_URL"
|
||||
ENVARGS=(-e "SITE_URL=$SITE_URL")
|
||||
fi
|
||||
|
||||
# ---- build (or serve) -----------------------------------------------------
|
||||
if [[ "${1:-}" == "serve" ]]; then
|
||||
echo "==> Serving docs on http://localhost:8000 (Ctrl-C to stop)"
|
||||
docker run --rm -it -p 8000:8000 "${ENVARGS[@]+"${ENVARGS[@]}"}" -v "$HERE":/docs "$IMAGE" serve -a 0.0.0.0:8000
|
||||
else
|
||||
echo "==> Building docs site"
|
||||
docker run --rm "${ENVARGS[@]+"${ENVARGS[@]}"}" -v "$HERE":/docs "$IMAGE" build
|
||||
echo
|
||||
echo "==> Done. Static site (upload the *contents* of this folder):"
|
||||
echo " $HERE/_build/site"
|
||||
fi
|
||||
35
website/home.md
Normal file
35
website/home.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# FreeTRX
|
||||
|
||||
**FreeTRX** is a fork of the [OpenGD77](https://opengd77.org) firmware for the
|
||||
**TYT MD-UV380 / Retevis RT-3S** and **Baofeng DM-1701 / Retevis RT-84**.
|
||||
|
||||
[Latest release :material-download:](https://git.dk1da.de/DK1DA/FreeTRX/releases){ .md-button .md-button--primary }
|
||||
[Source :material-git:](https://git.dk1da.de/DK1DA/FreeTRX){ .md-button }
|
||||
|
||||
## Screenshots
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[User Manual](MANUAL.md)** — every feature, tagged 🟢 **FreeTRX** (new/changed)
|
||||
or ⚪ **OpenGD77** (inherited), with a button reference.
|
||||
- **[Building & Flashing](TOOLS.md)** — Docker build, the flash helper, screenshots.
|
||||
- **[Changelog](CHANGELOG.md)** — version history.
|
||||
|
||||
## Supported radios
|
||||
|
||||
Developed and tested on the **TYT MD-UV380 / Retevis RT-3S**. A DM-1701 / RT-84
|
||||
build is also produced but not yet officially tested. Want to help test another
|
||||
OpenGD77-supported radio? Email **Marcus, DK1DA** at
|
||||
[qsl@dk1da.de](mailto:qsl@dk1da.de).
|
||||
|
||||
!!! note "License"
|
||||
FreeTRX inherits the OpenGD77 license (modified BSD 3-Clause with a
|
||||
non-commercial clause). It is not GPL-compatible and cannot be relicensed.
|
||||
63
website/mkdocs.yml
Normal file
63
website/mkdocs.yml
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
site_name: FreeTRX Documentation
|
||||
site_description: User manual for the FreeTRX firmware (an OpenGD77 fork for MD-UV380 / DM-1701)
|
||||
site_author: Marcus, DK1DA
|
||||
# Public URL where the docs are hosted. Only affects the sitemap / canonical links /
|
||||
# search-share URLs — the site itself works at ANY domain or path (relative links).
|
||||
# Override at build time without editing this file: SITE_URL=https://your.url/ ./build-docs.sh
|
||||
site_url: !ENV [SITE_URL, "https://docs.example.com/"]
|
||||
repo_name: DK1DA/FreeTRX
|
||||
repo_url: https://git.dk1da.de/DK1DA/FreeTRX
|
||||
|
||||
# Source markdown is assembled into _build/docs by build-docs.sh; output goes to _build/site.
|
||||
docs_dir: _build/docs
|
||||
site_dir: _build/site
|
||||
use_directory_urls: true
|
||||
|
||||
theme:
|
||||
name: material
|
||||
language: en
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: green
|
||||
accent: green
|
||||
toggle:
|
||||
icon: material/weather-night
|
||||
name: Switch to dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: green
|
||||
accent: green
|
||||
toggle:
|
||||
icon: material/weather-sunny
|
||||
name: Switch to light mode
|
||||
features:
|
||||
- navigation.top
|
||||
- navigation.sections
|
||||
- navigation.instant
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- search.share
|
||||
- content.code.copy
|
||||
- toc.follow
|
||||
|
||||
plugins:
|
||||
- search # built-in client-side (lunr.js) full-text search — no external service
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- User Manual: MANUAL.md
|
||||
- Building & Flashing: TOOLS.md
|
||||
- Changelog: CHANGELOG.md
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- attr_list
|
||||
- tables
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.superfences
|
||||
- pymdownx.highlight
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
Loading…
Reference in a new issue