Running the site locally

Build and serve the documentation site on your own machine so you can see a change before you propose it.

Prerequisites

Tool	Version	Why
Node.js	The version in .nvmrc	Docusaurus runs on it
nvm	Any	Selects the Node.js version the repository pins
pnpm	The version in packageManager	The package manager this repository uses
Git	Any	Clones the repository and its submodule

Corepack ships with Node.js and reads the packageManager field, so corepack enable gives you the pinned pnpm without installing it separately.

Set up a local copy

Fork meshtastic/meshtastic on GitHub, then clone your fork. Replace <YOUR_GITHUB_USERNAME> with your own username.

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

cd meshtastic

The site pulls brand assets from the meshtastic/design repository as a submodule, and the build fails without it.

git submodule update --init --recursive

Select the pinned Node.js version and install dependencies.

nvm install

nvm use

pnpm install

Run the development server

pnpm start

The server opens the site in your browser and reloads as you save. Most content edits appear within a second or two.

Front matter changes, sidebar changes, and anything under docusaurus.config.js need a restart. If the site starts behaving oddly after a branch switch, clear the cache and start again.

pnpm clear

Checks to run before opening a pull request

CI runs these, so running them locally saves a round trip.

pnpm run format

pnpm run lint:mdx

pnpm run build

build is the one that matters most, and it is the only status check branch protection requires. A link to a page that doesn't exist fails it rather than reaching the site, while an unresolvable relative Markdown reference is reported and does not. lint:mdx fails on the JSX corruption that breaks an MDX build: a malformed closing tag, a duplicated opening tag, or an import with no from. Its findings on missing alt text and unbalanced div tags are warnings, so they are worth fixing but do not fail the run.

format checks formatting without changing files, and pnpm run format:fix applies it. CI reports formatting but does not fail on it, because much of the repository predates the formatter. Format the files you touched rather than running the fixer across the repository, which would bury your change in unrelated reformatting.

CI also runs oxlint when a pull request touches JavaScript or TypeScript, and a Playwright end-to-end suite against the built site. Run that suite locally only if you changed site behavior rather than content.

pnpm exec playwright install --with-deps chromium

pnpm run test:e2e

Keep your fork current

Check whether an upstream remote is set.

git remote -v

If upstream is missing, add it.

git remote add upstream https://github.com/meshtastic/meshtastic.git

If it exists but points somewhere else, repoint it.

git remote set-url upstream https://github.com/meshtastic/meshtastic.git

Then bring your local master up to date. Commit or stash your work first, because a rebase rewrites the branch and uncommitted changes can be lost.

git fetch upstream

git checkout master

git rebase upstream/master

Work on a branch rather than on master, so the next rebase stays uneventful.