ci(update): prettier, mardownlint, cspell, and reviewdog

.github/workflows/lint.yml

@@ -0,0 +1,38 @@
+name: Lint
+
+on:
+  pull_request:
+    paths:
+      - "en/**"
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reviewdog/action-markdownlint@v0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review
+          markdownlint_flags: "en/**/*.md --ignore en/messages"
+
+  prettier:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npx prettier --check "en/**/*.md"
+
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: streetsidesoftware/cspell-action@v6
+        with:
+          files: "en/**/*.md"
+          config: cspell.json
+          incremental_files_only: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.markdownlint.yaml

@@ -0,0 +1,35 @@
+default: true
+
+# Allow inline HTML (used for anchors, <br>, etc. throughout the docs)
+MD033: false
+
+# First line need not be a top-level heading (VitePress uses frontmatter)
+MD041: false
+
+# Line length — not enforced (Prettier handles prose wrapping)
+MD013: false
+
+# Allow duplicate headings in different sections
+MD024:
+  siblings_only: true
+
+# Allow bare URLs (many protocol spec links are inline)
+MD034: false
+
+# Table pipe style and column count — too many pre-existing variations; revisit in a separate pass
+MD055: false
+MD056: false
+
+# Link fragment validation — 973 pre-existing broken fragments; track as separate issue
+MD051: false
+
+# Allow tabs inside code blocks (intentional indentation in C/Python examples)
+MD010:
+  code_blocks: false
+
+# Pre-existing violations throughout the codebase — revisit in a separate pass
+MD040: false  # Fenced code blocks without language specifier
+MD045: false  # Images without alt text
+MD001: false  # Heading levels skip (e.g. h2 → h4)
+MD036: false  # Emphasis used instead of a heading
+MD029: false  # Ordered list item prefix style

.prettierignore

@@ -0,0 +1,9 @@
+zh/
+ko/
+de/
+ja/
+ru/
+tr/
+uk/
+.vitepress/
+node_modules/

.prettierrc.yaml

@@ -0,0 +1,5 @@
+proseWrap: preserve
+printWidth: 120
+tabWidth: 2
+singleQuote: false
+embeddedLanguageFormatting: "off"

CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Repo Is
+
+This is the **MAVLink Developer Guide** — a VitePress-based documentation site for the MAVLink drone messaging protocol. Source content lives in `en/` (English), with translations in `zh/` (Chinese) and `ko/` (Korean) managed via Crowdin. The published site is at mavlink.io.
+
+## Commands
+
+```bash
+# Install dependencies
+npm ci         # or: yarn install
+
+# Local dev server with hot reload
+yarn start     # alias for: yarn docs:dev
+
+# Production build (Linux)
+yarn docs:build
+
+# Production build (Windows)
+yarn docs:buildwin
+
+# Preview the built site
+yarn docs:preview
+
+# Check links
+yarn linkcheck
+```
+
+CI (`.github/workflows/docs_deploy.yml`) uses `npm ci` + `npm run docs:build` on Node 20, then deploys to the `mavlink/mavlink.io` repo.
+
+## Architecture
+
+### Directory Layout
+
+- `en/` — primary English source; all editing happens here
+- `zh/`, `ko/` — machine/community translations synced from Crowdin (do not edit directly)
+- `.vitepress/config.mjs` — VitePress site config; sidebars are generated dynamically from `SUMMARY.md` files rather than hard-coded
+- `.vitepress/get_sidebar.js` — parses `SUMMARY.md` GitBook-style files to generate VitePress sidebar config
+- `.vitepress/theme/` — custom theme overrides
+
+### Navigation / Sidebar
+
+The sidebar for each language is built by reading that language's `en/SUMMARY.md` (and equivalent). This file is the authoritative table of contents — adding a new page requires both creating the `.md` file **and** adding it to `SUMMARY.md`.
+
+### Content Structure (`en/`)
+
+- `messages/` — auto-generated message reference docs (one per XML dialect: `common.md`, `ardupilotmega.md`, etc.)
+- `services/` — microservice protocol docs (mission, command, camera, gimbal, FTP, etc.)
+- `guide/` — protocol internals (serialization, routing, MAVLink 2, signing, etc.)
+- `mavgen_c/`, `mavgen_python/` — language-specific library usage guides
+- `contributing/` — contributor guides
+- `about/`, `getting_started/`, `file_formats/` — introductory and reference content
+
+### Excluded from Build
+
+Files matching `**/_*.md` are excluded from the VitePress build (used as includes/partials). Several language folders (`de`, `ja`, `ru`, `tr`, `uk`) are also excluded — only `en`, `zh`, and `ko` are active.
+
+## Authoring Conventions
+
+- VitePress callout syntax: `::: info`, `::: tip`, `::: warning`, `::: danger` (not `> **Note**` or `> **Tip**`)
+- Math is supported via `markdown-it-mathjax3` — use `$...$` inline and `$$...$$` for blocks
+- Tabs component is available via `@red-asuka/vitepress-plugin-tabs`
+- Internal links use relative paths to `.md` files (e.g., `../services/mission.md`)
+- The `EDITOR` environment variable enables "Open in your editor" links during local dev; omit it to get GitHub edit links instead
+
+## Translation Workflow
+
+- Crowdin config (`crowdin.yml`) maps `en/**/*.md` → `{lang}/**/{filename}.md`
+- Only edit English source in `en/`; translation PRs come from the Crowdin bot
+- New pages need to be in `en/SUMMARY.md` before Crowdin will pick them up

cspell.json

@@ -0,0 +1,183 @@
+{
+  "version": "0.2",
+  "language": "en,en-GB",
+  "include": [
+    "en/**/*.md"
+  ],
+  "ignorePaths": [
+    "en/messages/**",
+    "en/services/camera_def.md"
+  ],
+  "words": [
+    "ADSB",
+    "Agro",
+    "Ardu",
+    "ardupilot",
+    "ardupilotmega",
+    "ARINC",
+    "ASLUAV",
+    "ASTM",
+    "AUTOCONTINUE",
+    "Autoquad",
+    "Avionix",
+    "AVSSUAS",
+    "Bbuild",
+    "bitfield",
+    "bitmask",
+    "Bytewise",
+    "CCITT",
+    "cdeg",
+    "codegen",
+    "COLORMODE",
+    "compid",
+    "configurators",
+    "CRCS",
+    "CREAT",
+    "cubepilot",
+    "dataflash",
+    "Datapilot",
+    "datestamp",
+    "DCMAKE",
+    "deconflict",
+    "deconflicting",
+    "deconfliction",
+    "dezi",
+    "DMAVLINK",
+    "dpixels",
+    "Dronecode",
+    "Dronefleet",
+    "Errno",
+    "eulers",
+    "EXPMODE",
+    "firmwares",
+    "FLARM",
+    "Flightzoomer",
+    "geofence",
+    "geofences",
+    "gomavlib",
+    "halfword",
+    "Hask",
+    "icarous",
+    "IFLAG",
+    "imagestreamer",
+    "incompat",
+    "Inexa",
+    "irectory",
+    "IRLOCK",
+    "JAGCS",
+    "joysticksend",
+    "Kinect",
+    "libevents",
+    "loweheiser",
+    "lxml",
+    "matrixpilot",
+    "mavconn",
+    "mavcrc",
+    "mavexpression",
+    "mavextra",
+    "MAVFTP",
+    "mavgen",
+    "mavgenerate",
+    "MAVLINK",
+    "mavlinkcamera",
+    "mavlogdump",
+    "MAVPACKED",
+    "mavparm",
+    "mavparse",
+    "MAVROS",
+    "mavschema",
+    "MAVSDK",
+    "mavset",
+    "mavtest",
+    "mavutil",
+    "mavwp",
+    "MCRF",
+    "MDEF",
+    "memcpy",
+    "memset",
+    "microcontrollers",
+    "mkfifo",
+    "multicopter",
+    "multicopters",
+    "mydescriptivebranchname",
+    "Nutt",
+    "nuttx",
+    "OCTOROTOR",
+    "ODID",
+    "opendroneid",
+    "packetization",
+    "parameterrange",
+    "parameterranges",
+    "PHOTOEV",
+    "PHOTOFMT",
+    "PHOTOISO",
+    "PHOTOQUAL",
+    "PHOTORATIO",
+    "PHOTOSHUTSPD",
+    "PHOTOSIZE",
+    "PITCHYAW",
+    "Pixhawk",
+    "posx",
+    "pymavlink",
+    "PYTHONPATH",
+    "QUADROTOR",
+    "rallypoints",
+    "rawimage",
+    "resends",
+    "reserialize",
+    "roption",
+    "rosversion",
+    "RTSP",
+    "SBUS",
+    "Sentera",
+    "serialnumber",
+    "setpoint",
+    "setpoints",
+    "SHUTTERSPD",
+    "SITL",
+    "SIYI",
+    "Skydio",
+    "STATUSTEXT",
+    "subcomponent",
+    "Synturian",
+    "SYSID",
+    "systemid",
+    "tcpdump",
+    "tcpin",
+    "THISMAV",
+    "TIMESYNC",
+    "TRUNC",
+    "Tukaani",
+    "TXRX",
+    "ualberta",
+    "UART",
+    "UAVCAN",
+    "udpbcast",
+    "udpin",
+    "udpout",
+    "UNINIT",
+    "unitless",
+    "UNLIM",
+    "unscalable",
+    "usbmodem",
+    "usec",
+    "VIDEV",
+    "VIDFMT",
+    "VIDFOV",
+    "VIDFPS",
+    "VIDISO",
+    "VIDRES",
+    "VIDSHUTSPD",
+    "VIDSTREAM",
+    "Waddress",
+    "WBMODE",
+    "Wingtra",
+    "Wireshark",
+    "WIRIS",
+    "Workswell",
+    "WPNEXT",
+    "WRONLY",
+    "Xtrack",
+    "Yuneec"
+  ]
+}

en/SUMMARY.md

@@ -71,7 +71,7 @@
 - [Dialects & Tests](messages/dialects.md)
   - [ardupilotmega.xml](messages/ardupilotmega.md)
   - [ASLUAV.xml](messages/ASLUAV.md)
-  - [AVSSUAS.xml](messages/AVSSUAS.md)  
+  - [AVSSUAS.xml](messages/AVSSUAS.md)
   - [csAirLink.xml](messages/csAirLink.md)
   - [cubepilot.xml](messages/cubepilot.md)
   - [icarous.xml](messages/icarous.md)

en/about/faq.md

@@ -21,8 +21,8 @@
   </dd>
 
   <dt>What version of MAVLink should I use?</dt>
-  <dd>You should use the <a href="../guide/mavlink_2.md">MAVLink 2</a> protocol where at all possible (it fixes a number of limitations of earlier versions). 
-  The <em>MAVLink 2</em> libraries also support <em>MAVLink 1</em>, so you can use them to communicate with legacy systems if needed. 
+  <dd>You should use the <a href="../guide/mavlink_2.md">MAVLink 2</a> protocol where at all possible (it fixes a number of limitations of earlier versions).
+  The <em>MAVLink 2</em> libraries also support <em>MAVLink 1</em>, so you can use them to communicate with legacy systems if needed.
   </dd>
 
  <dt>How often is MAVLink updated/released?</dt>
@@ -58,15 +58,15 @@
   <dd>MAVLink is part of the safety critical components of an unmanned air system. A bad communication link dropping many packets can endanger the flight safety of the aircraft and has to be monitored. Having the sequence in the header allows MAVLink to continuously provide feedback about the packet drop rate and thus allows the aircraft or ground control station to take action.</dd>
 
   <dt>Why is CRC_EXTRA needed in the packet checksum?</dt>
-  <dd>The CRC_EXTRA CRC is used to verify that the sender and receiver have a shared understanding of the over-the-wire format of a particular message 
+  <dd>The CRC_EXTRA CRC is used to verify that the sender and receiver have a shared understanding of the over-the-wire format of a particular message
   (required because as a lightweight protocol, the message structure isn't included in the payload).
   <br><br>
-  In MAVLink 0.9 the CRC was not used (although there was a length check). 
-  There were a small number of cases where XML describing a message changed without changing the message length, 
+  In MAVLink 0.9 the CRC was not used (although there was a length check).
+  There were a small number of cases where XML describing a message changed without changing the message length,
   leading to badly corrupted fields when messages were read.</dd>
 
   <dt>I would like to help improve the decoding/encoding routines or other features. Can MAVLink be changed?</dt>
-  <dd>Yes, but only very, very carefully with safety testing. 
+  <dd>Yes, but only very, very carefully with safety testing.
   <br>MAVLink is used as a safety-critical component in many autopilot systems and has undergone many years of testing. Please suggest new features on the MAVLink <a href="../index.md#support">support channels</a>.</dd>
 
   <dt>How can I further reduce the generated C library size?</dt>