About these docs
This page explains how the Pomme documentation is organized and how to work on it.
How the documentation is organized
Section titled “How the documentation is organized”The documentation separates pages by what you’re trying to do:
- Get started pages help you install Pomme and create your first VM.
- Concept pages explain how Pomme works and why it behaves the way it does.
- How-to guides give you the steps to complete one task.
- Reference pages list facts to look up, such as commands, flags, fields, and exit codes.
- Resources include troubleshooting, a glossary, and release notes.
The documentation follows the
Google developer documentation style guide.
The repository file Website/CONTRIBUTING.md summarizes the rules that these
pages use most, including page structure, voice, formatting, and a word list.
The site checks prose with Vale and the Google style package.
Crawler mode
Section titled “Crawler mode”The switch next to the theme selector turns on Crawler mode, which retells
the guides in the voice of a sarcastic game-show System at
/crawler/. Crawler mode changes the narration only. Its
commands, flags, examples, and tables match the normal pages. Pages that it
doesn’t retell, such as the command-line reference, show their normal text
under a notice. The repository file Website/CRAWLER_VOICE.md describes how
to write and maintain these pages.
Command-line reference
Section titled “Command-line reference”The command-line reference is generated from the help text
of the installed pomme executable, so it matches the version that you run.
Each generated page names the version and commit that it came from.
Build the site locally
Section titled “Build the site locally”The site uses Starlight, and it’s published
at https://pommevm.dev from the main branch. To preview a change, build and
view the site on your own Mac.
To build and view the site, do the following:
-
Install Node.js.
-
In a terminal, go to the
Websitedirectory of the Pomme repository:Terminal window cd Website -
Install the site’s dependencies:
Terminal window npm install -
Start the development server:
Terminal window npm run dev -
In a browser, open
http://localhost:4321.
The development server reloads pages when you save a change. The site’s search
box works only in a built site. To build the site and serve the result, run
npm run build and then npm run preview.
Check and regenerate content
Section titled “Check and regenerate content”The following commands check and regenerate site content:
| Command | Description |
|---|---|
npm run lint:style |
Checks every page against the Google style rules. |
npm run reference |
Regenerates the command-line reference from ~/.local/bin/pomme. To use a different executable, set POMME_RUNNER to its absolute path. |
npm run check:crawler |
Checks that each Crawler mode page keeps the code blocks and tables of its normal page, and that its links stay in Crawler mode. |
npm run build |
Builds the static site into Website/dist and checks that every page compiles. |