Maintaining documentation

Documentation is part of the product. A setting that isn't documented, or that is explained in language the reader can't parse, fails the same goal as a control with no label.

This section covers the software stack, how the site is organized, and the rules writing follows.

Where the rules live

Section 11 of the Meshtastic Client Design Standards governs writing across the project, including this site. Writing style is the working guide here. Where the two disagree, the standard decides.

Software stack

The site is built with Docusaurus, a documentation platform built on React that renders MDX. MDX is Markdown that can import and use React components, so most content changes are ordinary Markdown edits.

Dependencies are managed with pnpm, and the repository pins both the Node.js and pnpm versions. Brand assets come from the meshtastic/design repository as a Git submodule.

All documentation lives on GitHub. Read the GitHub setup instructions if you haven't contributed before.

How the site is organized

Section	Path	Contents
About Meshtastic	docs/about	What Meshtastic is, how the mesh works, and the FAQ
Getting started	docs/getting-started	Flashing firmware, serial drivers, and initial configuration
Configuration	docs/configuration	Radio, module, and device UI settings, with per-client instructions
Hardware	docs/hardware	Supported devices, antennas, peripherals, and accessories
Software	docs/software	Clients and integrations, including Android, Apple, Web, and the Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic.
meshtasticd	docs/meshtasticd	The Linux native daemon: installation, hardware, and usage
Development	docs/development	Contributing to the firmware, the clients, and this site
Community	docs/community	Community projects, local groups, and enclosures
Glossary	docs/terms	Definitions behind the term tooltips used across the site
Legal	docs/legal	Trademark, licensing, privacy policy, and the code of conduct
Shared partials	docs/blocks	Reusable MDX imported by other pages, not published on its own

Two directories under docs/software are generated. Android and Apple client documentation is written in the client repositories and synced here weekly, and a CI guard rejects pull requests that edit it. Read Covering every client for where those changes belong.

Documentation for released firmware is frozen under versioned_docs/, and docs/ is the release in development. Read Versioning before cutting a snapshot or editing an archived page.

Quick start

With the prerequisites installed, a local site takesTAK (Team Awareness Kit). A situational awareness ecosystem. Meshtastic bridges to it by converting mesh messages to and from Cursor on Target format. four steps.

1. Clone your fork of meshtastic/meshtastic and change into it.

   git clone https://github.com/<YOUR_GITHUB_USERNAME>/meshtastic.git

   cd meshtastic

2. Fetch the design submodule, without which the build fails.

   git submodule update --init --recursive

3. Install dependencies.

   pnpm install

4. Start the development server, which opens the site in your browser.

   pnpm start

Run pnpm run build before opening a pull request, since broken links fail the build. See Running the site locally for the full set of checks CI runs.

Proposing a change

Every pull request here links to an issue. The issue is where the problem gets agreed on before anyone writes the fix, and it carries the context a diff can't: which page is wrong, what it should say, and who reported it.

1. Search the open issues for the problem you found.
2. Open a documentation change request if no issue covers it. Say what the page claims now and what is wrong with it.
3. Take the issue. Assign it to yourself if the assignee field is available to you, and otherwise comment that you are working on it, since GitHub offers self-assignment only to accounts with write access to the repository. Either way the issue records that the work is claimed, so two people don't write the same page twice.
4. Branch from master, make the change, and run the checks CI runs.
5. Open a pull request whose description contains Closes #<ISSUE_NUMBER>.

Closes is what links the two on GitHub. It puts the issue in the pull request's sidebar and closes the issue when the pull request merges. Linking by hand in prose looks similar but does neither.

A typo fix needs an issue too. The issue can be one sentence, and the minute it costs buys a record of what changed and why for a site nobody reads end to end.

Changes to the Android and Apple client pages are the exception, because those pages are generated. Open the issue and the pull request in the client repository instead, as Covering every client describes.