Behind the scenes (about)
Welcome backstage, Crawler. 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. In the dungeon, each group is a floor:
- 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 troubleshooting page is where Crawlers go after they die, which makes it the most visited floor.
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 is exempt from the Google style rules, because exclamation points and a narrator who says “I” are the whole point. Vale still checks its spelling. The System can’t spell its way out of everything.
Crawler mode
Section titled “Crawler mode”You’re in it, Crawler. The switch next to the theme selector turns Crawler
mode on and off. It changes the narration only: commands, flags, examples, and
tables match the normal pages. Pages that the System doesn’t retell, such
as the command-line reference, show their normal text under a notice. The
repository file Website/CRAWLER_VOICE.md explains how to write and maintain
these pages, in case you want to apply for the System’s job. You don’t.
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. The
System doesn’t narrate those pages. Help text is sacred, and also very long.
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. Pushing straight to main to see how it looks
publishes it to everyone, so build locally first, Crawler.
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. |