From 35ba6e99750123e6102ac5ae5649885e2f8bd3da Mon Sep 17 00:00:00 2001 From: Marcus Kida Date: Fri, 10 Jul 2026 13:29:29 +0200 Subject: [PATCH] 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) --- .gitignore | 3 +++ CHANGELOG.md | 4 +++ website/build-docs.sh | 49 +++++++++++++++++++++++++++++++++ website/home.md | 35 ++++++++++++++++++++++++ website/mkdocs.yml | 63 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 154 insertions(+) create mode 100644 website/build-docs.sh create mode 100644 website/home.md create mode 100644 website/mkdocs.yml diff --git a/.gitignore b/.gitignore index ef7714d..c84fa27 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 4972e8d..a7a087f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/website/build-docs.sh b/website/build-docs.sh new file mode 100644 index 0000000..aa2a716 --- /dev/null +++ b/website/build-docs.sh @@ -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 diff --git a/website/home.md b/website/home.md new file mode 100644 index 0000000..7812cc3 --- /dev/null +++ b/website/home.md @@ -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 + +
+ +![DMR call with the segmented S-meter](images/screenshot-dmr.png) + +![VFO with the 7-segment frequency font](images/screenshot-vfo.png) + +
+ +## 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. diff --git a/website/mkdocs.yml b/website/mkdocs.yml new file mode 100644 index 0000000..de173fd --- /dev/null +++ b/website/mkdocs.yml @@ -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