Skip to content

Commit a6fa28b

Browse files
hamishwilleehamishwillee
committed
ci(update): Add prettier, markdownlink, prettier, reviewdog
1 parent ac76cb2 commit a6fa28b

52 files changed

Lines changed: 13914 additions & 9803 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/lint.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Lint
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "en/**"
7+
8+
jobs:
9+
markdownlint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: reviewdog/action-markdownlint@v0
14+
with:
15+
github_token: ${{ secrets.GITHUB_TOKEN }}
16+
reporter: github-pr-review
17+
markdownlint_flags: "en/**/*.md --ignore en/messages"
18+
19+
prettier:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: actions/setup-node@v4
24+
with:
25+
node-version: "20"
26+
- run: npm ci
27+
- run: npx prettier --check "en/**/*.md"
28+
29+
spellcheck:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v4
33+
- uses: streetsidesoftware/cspell-action@v6
34+
with:
35+
files: "en/**/*.md"
36+
config: cspell.json
37+
incremental_files_only: true
38+
github_token: ${{ secrets.GITHUB_TOKEN }}

‎.husky/pre-commit‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
npx lint-staged

‎.markdownlint.yaml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
default: true
2+
3+
# Allow inline HTML (used for anchors, <br>, etc. throughout the docs)
4+
MD033: false
5+
6+
# First line need not be a top-level heading (VitePress uses frontmatter)
7+
MD041: false
8+
9+
# Line length — not enforced (Prettier handles prose wrapping)
10+
MD013: false
11+
12+
# Allow duplicate headings in different sections
13+
MD024:
14+
siblings_only: true
15+
16+
# Allow bare URLs (many protocol spec links are inline)
17+
MD034: false
18+
19+
# Table pipe style and column count — too many pre-existing variations; revisit in a separate pass
20+
MD055: false
21+
MD056: false
22+
23+
# Link fragment validation — 973 pre-existing broken fragments; track as separate issue
24+
MD051: false
25+
26+
# Allow tabs inside code blocks (intentional indentation in C/Python examples)
27+
MD010:
28+
code_blocks: false
29+
30+
# Pre-existing violations throughout the codebase — revisit in a separate pass
31+
MD040: false # Fenced code blocks without language specifier
32+
MD045: false # Images without alt text
33+
MD001: false # Heading levels skip (e.g. h2 → h4)
34+
MD036: false # Emphasis used instead of a heading
35+
MD029: false # Ordered list item prefix style

‎.prettierignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
zh/
2+
ko/
3+
de/
4+
ja/
5+
ru/
6+
tr/
7+
uk/
8+
.vitepress/
9+
node_modules/

‎.prettierrc.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
proseWrap: preserve
2+
printWidth: 120
3+
tabWidth: 2
4+
singleQuote: false
5+
embeddedLanguageFormatting: "off"

‎CLAUDE.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## What This Repo Is
6+
7+
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.
8+
9+
## Commands
10+
11+
```bash
12+
# Install dependencies
13+
npm ci # or: yarn install
14+
15+
# Local dev server with hot reload
16+
yarn start # alias for: yarn docs:dev
17+
18+
# Production build (Linux)
19+
yarn docs:build
20+
21+
# Production build (Windows)
22+
yarn docs:buildwin
23+
24+
# Preview the built site
25+
yarn docs:preview
26+
27+
# Check links
28+
yarn linkcheck
29+
```
30+
31+
CI (`.github/workflows/docs_deploy.yml`) uses `npm ci` + `npm run docs:build` on Node 20, then deploys to the `mavlink/mavlink.io` repo.
32+
33+
## Architecture
34+
35+
### Directory Layout
36+
37+
- `en/` — primary English source; all editing happens here
38+
- `zh/`, `ko/` — machine/community translations synced from Crowdin (do not edit directly)
39+
- `.vitepress/config.mjs` — VitePress site config; sidebars are generated dynamically from `SUMMARY.md` files rather than hard-coded
40+
- `.vitepress/get_sidebar.js` — parses `SUMMARY.md` GitBook-style files to generate VitePress sidebar config
41+
- `.vitepress/theme/` — custom theme overrides
42+
43+
### Navigation / Sidebar
44+
45+
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`.
46+
47+
### Content Structure (`en/`)
48+
49+
- `messages/` — auto-generated message reference docs (one per XML dialect: `common.md`, `ardupilotmega.md`, etc.)
50+
- `services/` — microservice protocol docs (mission, command, camera, gimbal, FTP, etc.)
51+
- `guide/` — protocol internals (serialization, routing, MAVLink 2, signing, etc.)
52+
- `mavgen_c/`, `mavgen_python/` — language-specific library usage guides
53+
- `contributing/` — contributor guides
54+
- `about/`, `getting_started/`, `file_formats/` — introductory and reference content
55+
56+
### Excluded from Build
57+
58+
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.
59+
60+
## Authoring Conventions
61+
62+
- VitePress callout syntax: `::: info`, `::: tip`, `::: warning`, `::: danger` (not `> **Note**` or `> **Tip**`)
63+
- Math is supported via `markdown-it-mathjax3` — use `$...$` inline and `$$...$$` for blocks
64+
- Tabs component is available via `@red-asuka/vitepress-plugin-tabs`
65+
- Internal links use relative paths to `.md` files (e.g., `../services/mission.md`)
66+
- The `EDITOR` environment variable enables "Open in your editor" links during local dev; omit it to get GitHub edit links instead
67+
68+
## Translation Workflow
69+
70+
- Crowdin config (`crowdin.yml`) maps `en/**/*.md` → `{lang}/**/{filename}.md`
71+
- Only edit English source in `en/`; translation PRs come from the Crowdin bot
72+
- New pages need to be in `en/SUMMARY.md` before Crowdin will pick them up

‎cspell.json‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
{
2+
"version": "0.2",
3+
"language": "en,en-GB",
4+
"include": [
5+
"en/**/*.md"
6+
],
7+
"ignorePaths": [
8+
"en/messages/**",
9+
"en/services/camera_def.md"
10+
],
11+
"words": [
12+
"ADSB",
13+
"Agro",
14+
"Ardu",
15+
"ardupilot",
16+
"ardupilotmega",
17+
"ARINC",
18+
"ASLUAV",
19+
"ASTM",
20+
"AUTOCONTINUE",
21+
"Autoquad",
22+
"Avionix",
23+
"AVSSUAS",
24+
"Bbuild",
25+
"bitfield",
26+
"bitmask",
27+
"Bytewise",
28+
"CCITT",
29+
"cdeg",
30+
"codegen",
31+
"COLORMODE",
32+
"compid",
33+
"configurators",
34+
"CRCS",
35+
"CREAT",
36+
"cubepilot",
37+
"dataflash",
38+
"Datapilot",
39+
"datestamp",
40+
"DCMAKE",
41+
"deconflict",
42+
"deconflicting",
43+
"deconfliction",
44+
"dezi",
45+
"DMAVLINK",
46+
"dpixels",
47+
"Dronecode",
48+
"Dronefleet",
49+
"Errno",
50+
"eulers",
51+
"EXPMODE",
52+
"firmwares",
53+
"FLARM",
54+
"Flightzoomer",
55+
"geofence",
56+
"geofences",
57+
"gomavlib",
58+
"halfword",
59+
"Hask",
60+
"icarous",
61+
"IFLAG",
62+
"imagestreamer",
63+
"incompat",
64+
"Inexa",
65+
"irectory",
66+
"IRLOCK",
67+
"JAGCS",
68+
"joysticksend",
69+
"Kinect",
70+
"libevents",
71+
"loweheiser",
72+
"lxml",
73+
"matrixpilot",
74+
"mavconn",
75+
"mavcrc",
76+
"mavexpression",
77+
"mavextra",
78+
"MAVFTP",
79+
"mavgen",
80+
"mavgenerate",
81+
"MAVLINK",
82+
"mavlinkcamera",
83+
"mavlogdump",
84+
"MAVPACKED",
85+
"mavparm",
86+
"mavparse",
87+
"MAVROS",
88+
"mavschema",
89+
"MAVSDK",
90+
"mavset",
91+
"mavtest",
92+
"mavutil",
93+
"mavwp",
94+
"MCRF",
95+
"MDEF",
96+
"memcpy",
97+
"memset",
98+
"microcontrollers",
99+
"mkfifo",
100+
"multicopter",
101+
"multicopters",
102+
"mydescriptivebranchname",
103+
"Nutt",
104+
"nuttx",
105+
"OCTOROTOR",
106+
"ODID",
107+
"opendroneid",
108+
"packetization",
109+
"parameterrange",
110+
"parameterranges",
111+
"PHOTOEV",
112+
"PHOTOFMT",
113+
"PHOTOISO",
114+
"PHOTOQUAL",
115+
"PHOTORATIO",
116+
"PHOTOSHUTSPD",
117+
"PHOTOSIZE",
118+
"PITCHYAW",
119+
"Pixhawk",
120+
"posx",
121+
"pymavlink",
122+
"PYTHONPATH",
123+
"QUADROTOR",
124+
"rallypoints",
125+
"rawimage",
126+
"resends",
127+
"reserialize",
128+
"roption",
129+
"rosversion",
130+
"RTSP",
131+
"SBUS",
132+
"Sentera",
133+
"serialnumber",
134+
"setpoint",
135+
"setpoints",
136+
"SHUTTERSPD",
137+
"SITL",
138+
"SIYI",
139+
"Skydio",
140+
"STATUSTEXT",
141+
"subcomponent",
142+
"Synturian",
143+
"SYSID",
144+
"systemid",
145+
"tcpdump",
146+
"tcpin",
147+
"THISMAV",
148+
"TIMESYNC",
149+
"TRUNC",
150+
"Tukaani",
151+
"TXRX",
152+
"ualberta",
153+
"UART",
154+
"UAVCAN",
155+
"udpbcast",
156+
"udpin",
157+
"udpout",
158+
"UNINIT",
159+
"unitless",
160+
"UNLIM",
161+
"unscalable",
162+
"usbmodem",
163+
"usec",
164+
"VIDEV",
165+
"VIDFMT",
166+
"VIDFOV",
167+
"VIDFPS",
168+
"VIDISO",
169+
"VIDRES",
170+
"VIDSHUTSPD",
171+
"VIDSTREAM",
172+
"Waddress",
173+
"WBMODE",
174+
"Wingtra",
175+
"Wireshark",
176+
"WIRIS",
177+
"Workswell",
178+
"WPNEXT",
179+
"WRONLY",
180+
"Xtrack",
181+
"Yuneec"
182+
]
183+
}

‎en/SUMMARY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@
7171
- [Dialects & Tests](messages/dialects.md)
7272
- [ardupilotmega.xml](messages/ardupilotmega.md)
7373
- [ASLUAV.xml](messages/ASLUAV.md)
74-
- [AVSSUAS.xml](messages/AVSSUAS.md)
74+
- [AVSSUAS.xml](messages/AVSSUAS.md)
7575
- [csAirLink.xml](messages/csAirLink.md)
7676
- [cubepilot.xml](messages/cubepilot.md)
7777
- [icarous.xml](messages/icarous.md)

‎en/about/faq.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
</dd>
2222

2323
<dt>What version of MAVLink should I use?</dt>
24-
<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).
25-
The <em>MAVLink 2</em> libraries also support <em>MAVLink 1</em>, so you can use them to communicate with legacy systems if needed.
24+
<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).
25+
The <em>MAVLink 2</em> libraries also support <em>MAVLink 1</em>, so you can use them to communicate with legacy systems if needed.
2626
</dd>
2727

2828
<dt>How often is MAVLink updated/released?</dt>
@@ -58,15 +58,15 @@
5858
<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>
5959

6060
<dt>Why is CRC_EXTRA needed in the packet checksum?</dt>
61-
<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
61+
<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
6262
(required because as a lightweight protocol, the message structure isn't included in the payload).
6363
<br><br>
64-
In MAVLink 0.9 the CRC was not used (although there was a length check).
65-
There were a small number of cases where XML describing a message changed without changing the message length,
64+
In MAVLink 0.9 the CRC was not used (although there was a length check).
65+
There were a small number of cases where XML describing a message changed without changing the message length,
6666
leading to badly corrupted fields when messages were read.</dd>
6767

6868
<dt>I would like to help improve the decoding/encoding routines or other features. Can MAVLink be changed?</dt>
69-
<dd>Yes, but only very, very carefully with safety testing.
69+
<dd>Yes, but only very, very carefully with safety testing.
7070
<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>
7171

7272
<dt>How can I further reduce the generated C library size?</dt>

0 commit comments

Comments
 (0)