chore: convert 2.11 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

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

README.md

@@ -1,36 +1,18 @@
-# EdgeTX LUA Reference Guide
+# EdgeTX 2.11 Lua Reference Guide
 
-This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX operating system with Lua support. Readers should be familiar with EdgeTX, the EdgeTX Companion, and know how to transfer files the SD card in the transmitter.
+Source for the EdgeTX 2.11 version of the Lua Reference Guide, published at
+<https://luadoc.edgetx.org/2.11/>.
 
-{% hint style="info" %}
-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 and need the docs for that specific version.
-{% endhint %}
+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.
 
-## Sections
+## Local preview
 
-| Chapter                                     | Content                                                                       |
-| ------------------------------------------- | ----------------------------------------------------------------------------- |
-| [Overview](overview/)                       | Covers various topics of LUA implementation in EdgeTX operating system system |
-| [LUA API Reference](lua-api-reference/)     | Reference of all constants and functions available in EdgeTX LUA API          |
-| [LUA API Programming](lua-api-programming/) | EdgeTX LUA programming guide that covers coding techniques with examples.     |
-| [Appendixes](appendix/)                     |                                                                               |
+```sh
+uv run mkdocs serve -a 127.0.0.1:8014
+```
 
-## EdgeTX LUA development support
-
-Quickest way to get support from seasoned EdgeTX LUA developers is to join our Discord server and ask on dedicated #lua channel
-
-[Join the chat on Discord](https://discord.gg/DrHkAn28sq)
-
-## LUA Reference guide collaboration
-
-Please feel free to make suggestions or corrections to the documentation.
-
-* Preferred method of editing is to use [GitBook](https://www.gitbook.com), as it uses WYSWIG editor allowing two-stage publication. If you want to change or add whole page or become collaborator _<mark style="color:purple;">\<decribe what to do></mark>_.
-
-## Project support
-
-The EdgeTX team has no intention of making a profit from their work - EdgeTX is free and open source and will remain free and open source. However, the project is more expensive to maintain than most open source projects. This in mainly because there is a never ending flood of hardware to integrate and maintain code for. Hardware that costs. In addition, in order to develop for this hardware, certain specalised test and measurement equipment is also required.
-
-In order to support this, EdgeTX has chosen to use OpenCollective to allow for donations from the community, as well as funding from manufacturers who choose to partner with and sponsor the project. This also allows for transparent accounting of what the funds are spent on.
-
-Please visit [our OpenCollective page](https://opencollective.com/edgetx) if you would like to financially help support the project!
+Pushes to `edgetx_2.11` are published automatically by
+`.github/workflows/publish-versioned-docs.yml`, and pull requests get a
+preview deployment from `.github/workflows/preview-docs.yml`.