Meshtastic docs: the Docusaurus site that documents firmware, clients and hardware

A repository that holds documentation and no product code

The project's own description is one line long: Meshtastic project website and documentation. The README expands on it, saying the repository publishes meshtastic.org and holds the written documentation for the firmware, the clients and the hardware, then adds the sentence that matters most to anyone browsing the code: the code those pages describe lives elsewhere, with firmware, clients and tooling each in their own repository under the Meshtastic organization.

GitHub reports the primary language as MDX, which is a fair summary of a repository whose product is prose. The tree bears that out. There is a `docs/` directory, a `blog/`, an `i18n/` folder for translations, a `glossary/` folder, `src/` for React components, `static/` for assets, and `scripts/` for helper tooling. The build configuration sits in `docusaurus.config.js` with the sidebar definitions in `sidebars.js`.

The repository has no GitHub releases, and the manifest declares `"version": "0.0.0"` alongside `"private": true`. That version number is a placeholder in a private package rather than a release marker, which is consistent with there being nothing here to release. The last push was on 2026-09-27, and the site itself is deployed through Vercel, which the README's badge row names directly.

One command stands between you and a pull request

The README's Development and Building section is short, because the details live in a separate local development guide on the site itself. What the repository does insist on is the check that runs before you open the pull request:

pnpm run build

That script is `docusaurus build` in the manifest, and the README explains two things about it. It is the status check that branch protection requires, so a pull request without it will not merge regardless of its content. And it fails on a link to a page that does not exist rather than letting the broken link reach the live site. For a documentation repository, that second behaviour is the important one, because cross-references between firmware versions and client pages are the most common way a docs site rots.

Package management is pinned rather than assumed. The manifest declares `packageManager: [email protected]`, the tree carries both `pnpm-lock.yaml` and `pnpm-workspace.yaml`, and there is a `.nvmrc` to fix the Node version and an `.npmrc` alongside it. For previewing a built site locally the manifest offers `docusaurus serve`, which serves the output the same way production does rather than re-running the dev server.

Two lint tools and a strict mode for prose

The lint and format setup is unusual enough to be worth reading closely, because it explains how the project keeps prose and code both consistent. The default linter is `oxlint` and the formatter is `oxfmt`, each with its own config file at the root in `.oxlintrc.json` and `.oxfmtrc.json`.

Then there is `eslint`, still present in `eslint.config.mjs` and used for exactly one job. The `lint:mdx:strict` script runs eslint with `--no-warn-ignored` over `docs/**/*.mdx` and `i18n/**/*.mdx`, and `lint:fix` runs oxlint with the fix flag across the project. So the split is: oxlint for everything, eslint reserved for a stricter pass over documentation files. There is also `lint:mdx`, a shell script at `scripts/lint-mdx.sh`, which is a separate mechanism from the strict eslint pass.

End-to-end checks run through Playwright, with `playwright test` and a `test:e2e:ui` variant for the interactive mode, configured by `playwright.config.ts` with an `e2e/` directory. Git hooks are wired through `husky`, though note the `prepare` script is just `husky` with no argument, a terser form than the `husky install` some projects use. A `patches/` directory is present alongside `.gitmodules`, and `.specify/` at the root suggests a spec-driven workflow with no explanation in the README.

Versioned docs and the two areas that refuse pull requests

Documentation versioning is the structural decision that shapes this repository. The tree has `versioned_docs/` for frozen snapshots, `versioned_sidebars/` for their navigation, and `versions.json` listing the versions. The README explains the rule: documentation for released firmware is frozen under `versioned_docs/`, and edits belong in `docs/` for the current release, which becomes the next snapshot. In other words, the live site shows current content while older firmware versions keep the documentation that matched them, which matters for a project where protocol changes between releases.

Two areas of the tree explicitly do not accept pull requests here, and the README names both. Android and Apple client pages under `docs/software/android` and `docs/software/apple` are written in the client repositories and synced in, so changes go to Meshtastic-Android or Meshtastic-Apple instead. Combined with the frozen versioned directory, that leaves `docs/` as the only editable documentation surface.

The process rules are stated with unusual bluntness for a public project. The README says to read CONTRIBUTING.md first and that every pull request links to an issue, a one-line typo fix included. It then points at Section 11 of the Meshtastic Client Design Standards as governing writing across the whole project, with a writing style guide as the working document reviewers check against. A CLA assistant badge is present in the README, so contributions pass through a contributor licensing agreement before review.

Search, comments, diagrams and translations

Four integrations explain most of what the site does beyond rendering Markdown. Search is Algolia, via `@algolia/client-search`, and the only environment variable in the repository is an empty `API_URL` in `.env.example`, which is where the credentials and index identifiers are expected to be supplied. The fact that the example file contains one blank variable says something about the deployment: configuration is injected rather than committed.

Comments come from giscus, `@giscus/react`, which is GitHub Discussions rendered in place. That choice keeps discussion inside GitHub instead of requiring a separate comment database. Diagrams are supported through `@docusaurus/theme-mermaid` with `@mermaid-js/layout-elk` for layout, which is what makes the hardware and protocol pages legible. Styling goes through `tailwind.config.ts` with a `tsconfig.json` for the TypeScript side.

Translations run through Crowdin, configured by `crowdin.yml`. The manifest has a `crowdin:sync` script that chains `docusaurus write-translations`, then `crowdin upload`, then `crowdin download`, and separate upload and download scripts for one-directional runs. Writing to a translated page in `i18n/` is therefore a poor instinct, because the next sync will overwrite it; the English page under `docs/` is the source.

There is also a PDF export path, which is unusual for a docs site to wire up:

npx docusaurus-prince-pdf -u http://localhost:3000/docs/about/ --dest ./static/documents/pdf --output ./static/documents/pdf/Meshtastic-Documentation.pdf

The script name is `pdf` and it targets the About page, writing the result into `static/documents/pdf/`. It depends on a local server already running on port 3000, so it is a maintenance task rather than something a contributor runs routinely.

Where this repository will not help you

The limitation is structural rather than a gap in the documentation, and the README is clear about it. If you are trying to understand how Meshtastic firmware behaves, how a radio range figure is derived, whether devices can be tracked, or what the hardware actually contains, none of that is answered here. Those pages exist on the site, but they are authored content about code that lives in other repositories, and the metadata of this one tells you nothing about them.

The same applies to the clients. Android and Apple documentation is written where the client code is, so a question about a mobile app's behaviour has to be taken to Meshtastic-Android or Meshtastic-Apple. Someone evaluating Meshtastic as a platform would get very little from reading this repository, and that is by design rather than by neglect.

There is also a maintenance pattern worth naming. The frozen `versioned_docs/` directory accumulates a copy of the documentation for every firmware release, and the synced-in mobile pages mean a meaningful share of the site's content is generated from elsewhere. Neither is a problem in itself, but both mean the tree overstates how much of the site a contributor can actually change, and the two rules in the README are the guide to which parts those are. What remains genuinely local is the firmware-independent documentation under `docs/`, plus the blog, the glossary and the site components in `src/`.

Editorial conclusion

This repository is worth contributing to if you want to change what Meshtastic users read, and it is the wrong place to look for firmware behaviour, since the README states plainly that the code those pages describe lives in other repositories under the Meshtastic organization. The build is one required command, `pnpm run build`, gated by branch protection, and the two closed areas are the Android and Apple client pages and the frozen `versioned_docs/` snapshots. Start by reading CONTRIBUTING.md, since every pull request has to link to an issue, then make the edit under `docs/` for the current release rather than under a versioned snapshot. If you are evaluating Meshtastic itself rather than its documentation, this repository will tell you nothing about radio range or hardware, because those pages are generated content this repo only hosts.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. meshtastic/meshtastic on GitHub
4. Project website
5. README