chore: convert 2.5 docs from GitBook to MkDocs

.github/workflows/preview-docs.yml

@@ -0,0 +1,121 @@
+# Builds a preview of the docs for each pull request and uploads it to
+# Cloudflare as a Worker *version* with a preview alias. Production keeps
+# serving the deployed version; the preview is only reachable at
+#   https://pr-<number>-edgetx-lua-reference-guide.edgetx.workers.dev/
+#
+# The PR is built as the version its base branch publishes (main -> "dev",
+# edgetx_<x.y> -> "<x.y>", plus "latest" for the latest release branch) on
+# top of the current gh-pages tree, so the preview is the whole site with
+# that one version replaced. Nothing is pushed to gh-pages.
+#
+# Only runs for PRs from branches in this repo: fork PRs don't get the
+# Cloudflare secrets, and building untrusted code with them available
+# would be unsafe anyway.
+name: Preview Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "edgetx_*"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: preview-docs-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Resolve version metadata
+        id: version
+        shell: bash
+        env:
+          LATEST_BRANCH: ${{ vars.DOCS_LATEST_BRANCH || 'edgetx_2.12' }}
+        run: |
+          case "${GITHUB_BASE_REF}" in
+            main)
+              version_id="dev"
+              title="Dev"
+              ;;
+            edgetx_[0-9]*.[0-9]*)
+              version_id="${GITHUB_BASE_REF#edgetx_}"
+              title="${version_id}"
+              ;;
+            *)
+              echo "Unsupported base branch: ${GITHUB_BASE_REF}" >&2
+              exit 1
+              ;;
+          esac
+
+          if [[ "${GITHUB_BASE_REF}" == "${LATEST_BRANCH}" ]]; then
+            aliases="${version_id} latest"
+          else
+            aliases="${version_id}"
+          fi
+
+          {
+            echo "version_id=${version_id}"
+            echo "title=${title}"
+            echo "aliases=${aliases}"
+            echo "alias=pr-${{ github.event.pull_request.number }}"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Sync docs dependencies
+        run: uv sync
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Build preview into local gh-pages
+        env:
+          DOCS_EDIT_URI: edit/${{ github.head_ref }}/website/md-docs/
+        run: |
+          git branch -f gh-pages origin/gh-pages
+          uv run mike deploy --update-aliases --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
+
+      - name: Export gh-pages tree for Cloudflare
+        run: |
+          rm -rf .site-publish
+          mkdir .site-publish
+          git archive gh-pages | tar -x -C .site-publish
+
+      - name: Upload preview version to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: versions upload --preview-alias ${{ steps.version.outputs.alias }} --message "PR #${{ github.event.pull_request.number }} @ ${{ github.event.pull_request.head.sha }}"
+
+      - name: Comment preview link on the PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          url="https://${{ steps.version.outputs.alias }}-edgetx-lua-reference-guide.edgetx.workers.dev/${{ steps.version.outputs.version_id }}/"
+          body="📖 **Docs preview:** ${url}
+
+          Built from ${HEAD_SHA::7} as the \`${{ steps.version.outputs.version_id }}\` version, on top of the currently published site."
+          gh pr comment "${PR_NUMBER}" --edit-last --create-if-none --body "${body}"

.github/workflows/publish-versioned-docs.yml

@@ -0,0 +1,118 @@
+# Publishes each docs branch via `mike deploy` on every push:
+#   main         -> "dev"
+#   edgetx_<x.y> -> "<x.y>", plus "latest" for the latest release branch
+#
+# Every branch carries its own MkDocs site (mkdocs.yml + website/md-docs/)
+# and an identical copy of this workflow, so a push builds the branch it
+# came from. The latest release branch comes from the DOCS_LATEST_BRANCH
+# repository variable (falling back to edgetx_2.12), so moving "latest" to
+# a new release is a settings change rather than an edit on every branch.
+#
+# mike keeps the accumulated versioned site on the gh-pages branch; after
+# each deploy, the full gh-pages tree is published to Cloudflare Workers
+# (static assets, see wrangler.jsonc). Requires the CLOUDFLARE_API_TOKEN and
+# CLOUDFLARE_ACCOUNT_ID repository secrets.
+name: Publish Versioned Docs
+
+on:
+  push:
+    branches:
+      - main
+      - "edgetx_*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Every run rewrites gh-pages and then uploads the whole tree, so run them
+# one at a time to avoid racing mike or publishing a stale snapshot.
+concurrency:
+  group: publish-versioned-docs
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Resolve version metadata
+        id: version
+        shell: bash
+        env:
+          LATEST_BRANCH: ${{ vars.DOCS_LATEST_BRANCH || 'edgetx_2.12' }}
+        run: |
+          branch="${GITHUB_REF_NAME}"
+
+          case "${branch}" in
+            main)
+              version_id="dev"
+              title="Dev"
+              ;;
+            edgetx_[0-9]*.[0-9]*)
+              version_id="${branch#edgetx_}"
+              title="${version_id}"
+              ;;
+            *)
+              echo "Unsupported branch: ${branch}" >&2
+              exit 1
+              ;;
+          esac
+
+          if [[ "${branch}" == "${LATEST_BRANCH}" ]]; then
+            aliases="${version_id} latest"
+            is_latest="true"
+          else
+            aliases="${version_id}"
+            is_latest="false"
+          fi
+
+          {
+            echo "version_id=${version_id}"
+            echo "title=${title}"
+            echo "aliases=${aliases}"
+            echo "is_latest=${is_latest}"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Sync docs dependencies
+        run: uv sync
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish docs with mike
+        env:
+          # "Edit this page" should open the branch this version is built from.
+          DOCS_EDIT_URI: edit/${{ github.ref_name }}/website/md-docs/
+        run: uv run mike deploy --push --update-aliases --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
+
+      - name: Set default docs version
+        if: steps.version.outputs.is_latest == 'true'
+        run: uv run mike set-default --push latest
+
+      - name: Export gh-pages tree for Cloudflare
+        run: |
+          rm -rf .site-publish
+          mkdir .site-publish
+          git archive gh-pages | tar -x -C .site-publish
+
+      - name: Deploy to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy

.gitignore

@@ -1,3 +1,10 @@
 /_book/
 /node_modules/
 /book.pdf
+/site/
+/.site-legacy-generated/
+/site-legacy/
+.tmp/
+.venv/
+__pycache__/
+/.site-publish/

README.md

@@ -1,19 +1,18 @@
 # EdgeTX 2.5 Lua Reference Guide
 
-[Join the chat on Discord](https://discord.gg/CZCwVx2)
+Source for the EdgeTX 2.5 version of the Lua Reference Guide, published at
+<https://luadoc.edgetx.org/2.5/>.
 
-The latest version of this guide will always be available [here](https://luadoc.edgetx.org). At the top of the left sidebar there is a version option if you are running an older version of EdgeTX or OpenTX and need the docs for that specific version.
+This content was converted from the original GitBook branch to MkDocs. It is
+kept for reference, so it may not include corrections made in later versions.
+The page content lives in `website/md-docs/`; edit it there.
 
-Please feel free to make suggestions or corrections to the documentation on GitHub, but the prefered method of editing is to use [GitBook](https://www.gitbook.com/), so all changes will need to be made by someone who is authorized as a writer there.&#x20;
+## Local preview
 
-This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX 2.5 operating system with Lua support. Readers should be familiar with EdgeTX/OpenTX, the OpenTX Companion, and know how to transfer files the SD card in the transmitter.
+```sh
+uv run mkdocs serve -a 127.0.0.1:8014
+```
 
-If you are new to Lua programming, you may also find the [Lua Reference Manual](https://www.lua.org/manual/5.2/) of assistance
-
-Part I is an overview of the different script types, along with basic examples of each.
-
-Part II is a programming guide that introduces the types of EdgeTX Lua scripts and how to use them.
-
-Part III is the EdgeTX Lua API Reference
-
-Part IV covers advanced topics with examples
+Pushes to `edgetx_2.5` are published automatically by
+`.github/workflows/publish-versioned-docs.yml`, and pull requests get a
+preview deployment from `.github/workflows/preview-docs.yml`.