docpensieve 0.5.0-beta.1 → 0.5.0-beta.3

package/bin/docpensieve.js

@@ -34,6 +34,7 @@ program
   .option('-t, --theme <framework>', 'tailwind | custom')
   .option('-u, --site-url <url>', 'public URL of the site')
   .option('--version-name <version>', 'first version, e.g. 1.0')
+  .option('--translation <code>', 'code of a second language, e.g. fr')
   .option('-y, --yes', 'accept the defaults without a dialogue')
   .option('-f, --force', 'overwrite an existing configuration')
   .option('--minimal', "leave DocPensieve's documentation out of the new site")
@@ -62,6 +63,7 @@ program
   .command('dev')
   .description('Development server with reload')
   .option('-p, --port <number>', 'listening port', Number, 3000)
+  .option('--host <address>', 'address to listen on; 0.0.0.0 opens it to the network', '127.0.0.1')
   .action(async (options) => {
     await dev(options);
   });
@@ -70,6 +72,7 @@ program
   .command('serve')
   .description('Serves the output folder statically')
   .option('-p, --port <number>', 'listening port', Number, 4000)
+  .option('--host <address>', 'address to listen on; 0.0.0.0 opens it to the network', '127.0.0.1')
   .option('-d, --dir <dir>', 'folder to serve')
   .action(async (options) => {
     await serve(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.3",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.5.0-beta.1",
-    "@docpensieve/core": "0.5.0-beta.1",
-    "@docpensieve/shared": "0.5.0-beta.1",
-    "@docpensieve/theme": "0.5.0-beta.1",
+    "@docpensieve/components": "0.5.0-beta.3",
+    "@docpensieve/core": "0.5.0-beta.3",
+    "@docpensieve/shared": "0.5.0-beta.3",
+    "@docpensieve/theme": "0.5.0-beta.3",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/src/commands/build.js

@@ -11,6 +11,7 @@ import {
   createRegistry,
   setSiteContext,
   setAdmonitionKinds,
+  setSnippetIcons,
 } from '@docpensieve/components';
 import { SiteGenerator, loadConfig, resolveVersion } from '@docpensieve/core';
 
@@ -28,6 +29,7 @@ export async function build(versionSlug, options = {}) {
 
   // The kinds a project declares, beside the ones shipped.
   setAdmonitionKinds(config.admonitions);
+  setSnippetIcons(config.snippetIcons);
 
   const generator = new SiteGenerator(config, {
     // `globalComponents: false` removes the shipped components: a project that

package/src/commands/dev.js

@@ -12,12 +12,20 @@ import {
   createRegistry,
   setSiteContext,
   setAdmonitionKinds,
+  setSnippetIcons,
 } from '@docpensieve/components';
 import { SiteGenerator, loadConfig } from '@docpensieve/core';
 import { CONFIG_FILENAME, DocPensieveError, THEME_FOLDER } from '@docpensieve/shared';
 import chokidar from 'chokidar';
 
-import { RELOAD_PATH, createStaticServer, listen } from '../server.js';
+import {
+  DEFAULT_HOST,
+  RELOAD_PATH,
+  createStaticServer,
+  exposedNotice,
+  isExposed,
+  listen,
+} from '../server.js';
 import { createTheme } from '../theme.js';
 
 /** Default port of `dev`, distinct from that of `serve`. */
@@ -40,7 +48,7 @@ const RELOAD_SCRIPT =
   `.addEventListener("message",()=>location.reload())</script>`;
 
 /**
- * @param {{ port?: number, cwd?: string }} [options]
+ * @param {{ port?: number, host?: string, cwd?: string }} [options]
  * @returns {Promise<{
  *   server: import('node:http').Server,
  *   watcher: import('chokidar').FSWatcher,
@@ -62,6 +70,7 @@ export async function dev(options = {}) {
     // Read again with the rest: a kind added to the configuration must show
     // without restarting the command.
     setAdmonitionKinds(current.admonitions);
+    setSnippetIcons(current.snippetIcons);
     const generator = new SiteGenerator(current, {
       // `globalComponents: false` removes the shipped components: a project
       // that defines its own thus avoids a name collision. The option was
@@ -87,8 +96,10 @@ export async function dev(options = {}) {
     },
   });
 
-  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const host = options.host ?? DEFAULT_HOST;
+  const port = await listen(server, options.port ?? DEFAULT_PORT, 10, host);
   const url = `http://localhost:${port}${config.baseUrl}`;
+  if (isExposed(host)) console.log(exposedNotice(host));
   console.log(`served at ${url}`);
 
   // The project's own stylesheets, re-read by every rebuild.

package/src/commands/init.js

@@ -18,6 +18,8 @@ import {
   DocPensieveError,
   THEME_FOLDER,
   THEME_FRAMEWORKS,
+  isLanguageCode,
+  languageName,
 } from '@docpensieve/shared';
 
 /**
@@ -30,7 +32,16 @@ const FRAMEWORK_LABELS = {
 };
 
 /** Answers used when there is no dialogue. */
-const DEFAULTS = { name: 'My documentation', siteUrl: '', theme: 'tailwind', version: '1.0' };
+const DEFAULTS = {
+  name: 'My documentation',
+  siteUrl: '',
+  theme: 'tailwind',
+  version: '1.0',
+  translation: '',
+};
+
+/** Second language offered first, being the one whose wording ships too. */
+const DEFAULT_TRANSLATION = 'fr';
 
 /**
  * Folder of the installed DocPensieve documentation, inside the version folder.
@@ -125,15 +136,43 @@ async function askDocumentation(rl) {
   }
 }
 
+/**
+ * Asks whether the site will carry a second language, and which one.
+ *
+ * Asked rather than left to the configuration: a translation changes the
+ * shape of the project — a folder per language beside the pages — and that is
+ * cheaper to set up at the start than to retrofit.
+ *
+ * @param {import('node:readline/promises').Interface} rl
+ * @returns {Promise<string>} Language code, or `''` for a single language.
+ */
+async function askTranslation(rl) {
+  for (;;) {
+    const answer = (await rl.question('Will the site be in several languages? [y/N]: '))
+      .trim()
+      .toLowerCase();
+    if (answer === '' || answer === 'n' || answer === 'no') return '';
+    if (answer === 'y' || answer === 'yes') break;
+    console.log('Answer not understood. Expected: y or n.');
+  }
+
+  for (;;) {
+    const code = (await ask(rl, 'Code of the second language', DEFAULT_TRANSLATION)).trim();
+    if (isLanguageCode(code)) return code;
+    console.log(`"${code}" does not name a language. Expected a code: fr, de, pt-BR, zh-Hans.`);
+  }
+}
+
 /**
  * Gathers the answers, through a dialogue or from the options.
  *
  * @param {{
  *   name?: string, theme?: string, siteUrl?: string, version?: string,
- *   yes?: boolean, minimal?: boolean,
+ *   translation?: string, yes?: boolean, minimal?: boolean,
  * }} options
  * @returns {Promise<{
  *   name: string, theme: string, siteUrl: string, version: string, docs: boolean,
+ *   translation: string,
  * }>}
  */
 async function collect(options) {
@@ -142,6 +181,7 @@ async function collect(options) {
     siteUrl: options.siteUrl ?? DEFAULTS.siteUrl,
     theme: options.theme ?? DEFAULTS.theme,
     version: options.version ?? DEFAULTS.version,
+    translation: options.translation ?? DEFAULTS.translation,
     docs: !options.minimal,
   };
 
@@ -154,7 +194,7 @@ async function collect(options) {
   if (!process.stdin.isTTY) {
     console.log('No interactive terminal: no questions asked, the options and defaults apply.');
     console.log(
-      'To choose, pass --name, --site-url, --theme, --version-name or --minimal; --yes silences this notice.',
+      'To choose, pass --name, --site-url, --theme, --version-name, --translation or --minimal; --yes silences this notice.',
     );
     return fromOptions;
   }
@@ -164,9 +204,10 @@ async function collect(options) {
     const name = await ask(rl, 'Project name', fromOptions.name);
     const siteUrl = await ask(rl, 'Public URL of the site (optional)', fromOptions.siteUrl);
     const version = await ask(rl, 'First version', fromOptions.version);
+    const translation = options.translation ?? (await askTranslation(rl));
     const theme = options.theme ?? (await askFramework(rl));
     const docs = options.minimal ? false : await askDocumentation(rl);
-    return { name, siteUrl, version, theme, docs };
+    return { name, siteUrl, version, theme, docs, translation };
   } finally {
     rl.close();
   }
@@ -183,6 +224,18 @@ async function collect(options) {
  */
 const quote = (value) => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 
+/**
+ * Writes a language code as a property name.
+ *
+ * `fr` stands on its own; `pt-BR` and `zh-Hans` carry a hyphen, which is a
+ * minus sign to JavaScript — unquoted, the generated configuration would not
+ * parse.
+ *
+ * @param {string} code
+ * @returns {string}
+ */
+const key = (code) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(code) ? code : quote(code));
+
 /**
  * Renders `docpensieve.config.mjs`.
  *
@@ -190,10 +243,13 @@ const quote = (value) => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g,
  * or commented out with an example — so that the first file a user opens also
  * tells them everything they can change.
  *
- * @param {{ name: string, theme: string, siteUrl: string, version: string }} answers
+ * @param {{
+ *   name: string, theme: string, siteUrl: string, version: string,
+ *   translation?: string,
+ * }} answers
  * @returns {string} Contents of `docpensieve.config.mjs`.
  */
-function renderConfig({ name, theme, siteUrl, version }) {
+function renderConfig({ name, theme, siteUrl, version, translation = '' }) {
   const slug = versionSlug(version);
   // A type annotation rather than an `import`: `defineConfig` transforms
   // nothing, it is only there for autocompletion. Actually importing it would
@@ -233,9 +289,14 @@ function renderConfig({ name, theme, siteUrl, version }) {
     `      name: ${quote(version)}, // label in the version switcher`,
     `      folder: ${quote(`docs/${slug}`)},`,
     '      current: true,',
-    '      // Pages of this version in another language, served under /fr/.',
+    `      // Pages of this version in another language, served under /${translation || 'fr'}/.`,
     '      // Your own language stays where it is, and keeps its addresses.',
-    `      // translations: { fr: ${quote(`docs/${slug}-fr`)} },`,
+    // Written out, not left as an example, once the language is known: the
+    // field is the whole of the feature, and the folder beside it already
+    // holds a page.
+    translation
+      ? `      translations: { ${key(translation)}: ${quote(`docs/${slug}-${translation}`)} },`
+      : `      // translations: { fr: ${quote(`docs/${slug}-fr`)} },`,
     '    },',
     '  ],',
     '',
@@ -307,6 +368,16 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  // Back-to-top button on every page.',
     '  scrollToTop: true,',
     '',
+    '  // A button copying each block of code. It is the one thing that makes a',
+    '  // content page load a script — a small file, shared by every page of the',
+    '  // version — so it stays off until you ask for it.',
+    '  copyCode: false,',
+    '',
+    '  // Icon collection a code block takes the mark of its language from, for',
+    "  // instance 'simple-icons' once @iconify-json/simple-icons is installed.",
+    '  // Left empty, the short name of the language is shown instead.',
+    "  snippetIcons: '',",
+    '',
     '  // The header stays at the top of the screen. false lets it scroll away',
     '  // with the page, and gives its height back to the text.',
     '  stickyHeader: true,',
@@ -353,11 +424,12 @@ function versionSlug(version) {
 }
 
 /**
- * @param {string} name Project name, for the title of the home page.
- * @param {boolean} docs Whether DocPensieve's documentation is installed.
+ * Home page of the project, in the language of the site.
+ *
+ * @param {{ name: string, docs: boolean, slug: string, translation: string }} answers
  * @returns {string}
  */
-const renderIndex = (name, docs) => `---
+const renderIndex = ({ name, docs, slug, translation }) => `---
 title: Introduction
 description: Documentation of ${name}.
 date: ${new Date().toISOString().slice(0, 10)}
@@ -378,6 +450,20 @@ without appearing in the URL.
 
 See the [installation guide](/guide/installation/).
 ${
+  translation
+    ? `
+## In ${languageName(translation)}
+
+The same pages live in \`docs/${slug}-${translation}/\`, and the language switcher
+in the header moves between them.
+
+A page with no twin there does not exist in that language: it stays out of the
+menu and out of the sitemap, and the switcher names the language without
+offering it. The installation page is in that case — write
+\`docs/${slug}-${translation}/01-guide/01-installation.md\` and it appears.
+${docs ? '\nThe [languages guide](/docpensieve/guide/languages/) covers the rest.\n' : ''}`
+    : ''
+}${
   docs
     ? `
 ## Learning DocPensieve
@@ -389,6 +475,70 @@ tool that builds this site, installed along with it. Delete its folder,
     : ''
 }`;
 
+/**
+ * Home page of the second language.
+ *
+ * French is written out, the tool shipping its wording too. Any other
+ * language gets the page in English, saying in its first line that it is
+ * there to be translated: a copy passing for a translation is the one failure
+ * this feature invites — the reader gets English under an address that
+ * promised their language, and nothing reports it.
+ *
+ * Only the home page is written. Its twin, the installation page, is left
+ * untranslated on purpose: it is what shows that an untranslated page does
+ * not exist in that language, which no sentence explains as well as the menu
+ * that lacks it.
+ *
+ * @param {{ name: string, slug: string, translation: string }} answers
+ * @returns {string}
+ */
+function renderTranslatedIndex({ name, slug, translation }) {
+  const french = translation.toLowerCase().split('-')[0] === 'fr';
+  const head = `---
+title: Introduction
+description: ${french ? `Documentation de ${name}.` : `Documentation of ${name}.`}
+date: ${new Date().toISOString().slice(0, 10)}
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# ${name}
+`;
+
+  if (french) {
+    return `${head}
+Bienvenue dans la documentation.
+
+## Une page et sa jumelle
+
+Cette page est la version française de \`docs/${slug}/index.md\`. Le sélecteur
+de langue, dans l'en-tête, passe de l'une à l'autre.
+
+La page d'installation, elle, n'est pas traduite : elle **n'existe pas** en
+français. Elle ne figure ni dans le menu ni dans le plan du site, et le
+sélecteur la nomme sans la proposer. Écrivez
+\`docs/${slug}-${translation}/01-guide/01-installation.md\` pour la voir apparaître.
+`;
+  }
+
+  return `${head}
+**Replace this page with your translation.** It is the ${languageName(translation)}
+twin of \`docs/${slug}/index.md\`, written in English so that the site builds:
+left as it is, a reader who picks ${languageName(translation, translation)} gets English.
+
+## One page, two languages
+
+The language switcher in the header moves between this page and its twin.
+
+The installation page has no twin here, so it does not exist in this language:
+it stays out of the menu and out of the sitemap, and the switcher names the
+language without offering it. Write
+\`docs/${slug}-${translation}/01-guide/01-installation.md\` and it appears.
+`;
+}
+
 /** @returns {string} Sample page, showing ordering and highlighting. */
 const renderGuide = () => `---
 title: Installation
@@ -478,11 +628,14 @@ async function installDocumentation(source, target, slug) {
  * @param {string} [dir] Target folder, created if needed.
  * @param {{
  *   name?: string, theme?: string, siteUrl?: string, version?: string,
- *   yes?: boolean, force?: boolean, minimal?: boolean,
- * }} [options] `minimal` leaves DocPensieve's documentation out of the site.
- * @returns {Promise<{ dir: string, theme: string, docs: boolean }>}
- * @throws {DocPensieveError} Unknown framework, project already initialised,
- *   or documentation to install missing.
+ *   translation?: string, yes?: boolean, force?: boolean, minimal?: boolean,
+ * }} [options] `minimal` leaves DocPensieve's documentation out of the site;
+ *   `translation` is the code of a second language, `fr` for instance.
+ * @returns {Promise<{
+ *   dir: string, theme: string, docs: boolean, translation: string,
+ * }>}
+ * @throws {DocPensieveError} Unknown framework, unknown language, project
+ *   already initialised, or documentation to install missing.
  */
 export async function init(dir = '.', options = {}) {
   const target = path.resolve(dir);
@@ -504,6 +657,14 @@ export async function init(dir = '.', options = {}) {
     });
   }
 
+  // Checked here for the same reason as the framework: a code refused after
+  // five questions would be five questions wasted.
+  if (options.translation && !isLanguageCode(options.translation)) {
+    throw new DocPensieveError(`"${options.translation}" does not name a language.`, {
+      hint: 'Write the code, not the name: "fr" for French, "pt-BR", "zh-Hans". It becomes the lang of the document and a segment of the address.',
+    });
+  }
+
   const answers = await collect(options);
 
   // Located before anything is written: a project left half set up would be
@@ -535,8 +696,21 @@ export async function init(dir = '.', options = {}) {
 
   await mkdir(path.join(docsDir, '01-guide'), { recursive: true });
   await writeFile(configPath, renderConfig(answers), 'utf8');
-  await writeFile(path.join(docsDir, 'index.md'), renderIndex(answers.name, answers.docs), 'utf8');
+  await writeFile(
+    path.join(docsDir, 'index.md'),
+    renderIndex({ name: answers.name, docs: answers.docs, slug, translation: answers.translation }),
+    'utf8',
+  );
   await writeFile(path.join(docsDir, '01-guide', '01-installation.md'), renderGuide(), 'utf8');
+  if (answers.translation) {
+    const folder = path.join(target, 'docs', `${slug}-${answers.translation}`);
+    await mkdir(folder, { recursive: true });
+    await writeFile(
+      path.join(folder, 'index.md'),
+      renderTranslatedIndex({ name: answers.name, slug, translation: answers.translation }),
+      'utf8',
+    );
+  }
   if (documentation) {
     await installDocumentation(documentation, path.join(docsDir, DOCS_FOLDER), slug);
   }
@@ -548,14 +722,31 @@ export async function init(dir = '.', options = {}) {
   console.log(`  ${CONFIG_FILENAME}`);
   console.log(`  docs/${slug}/index.md`);
   console.log(`  docs/${slug}/01-guide/01-installation.md`);
+  if (answers.translation) {
+    const state =
+      answers.translation.toLowerCase().split('-')[0] === 'fr'
+        ? `in ${languageName(answers.translation)}`
+        : 'to translate';
+    console.log(`  docs/${slug}-${answers.translation}/index.md  the home page, ${state}`);
+  }
   if (documentation) {
     console.log(`  docs/${slug}/${DOCS_FOLDER}/  DocPensieve's documentation, to delete when done`);
   }
   for (const line of stylesheets) console.log(`  ${line}`);
   console.log(`\nTheme: ${answers.theme} — ${FRAMEWORK_LABELS[answers.theme]}`);
+  if (answers.translation) {
+    console.log(
+      `Second language: ${languageName(answers.translation)} (${answers.translation}) — served under /${answers.translation}/`,
+    );
+  }
   console.log('\nNext:  npx docpensieve dev');
 
-  return { dir: target, theme: answers.theme, docs: answers.docs };
+  return {
+    dir: target,
+    theme: answers.theme,
+    docs: answers.docs,
+    translation: answers.translation,
+  };
 }
 
 /**

package/src/commands/serve.js

@@ -10,13 +10,13 @@ import path from 'node:path';
 import { loadConfig } from '@docpensieve/core';
 import { DocPensieveError } from '@docpensieve/shared';
 
-import { createStaticServer, listen } from '../server.js';
+import { DEFAULT_HOST, createStaticServer, exposedNotice, isExposed, listen } from '../server.js';
 
 /** Default port of `serve`, distinct from that of `dev`. */
 const DEFAULT_PORT = 4000;
 
 /**
- * @param {{ port?: number, dir?: string, cwd?: string }} [options]
+ * @param {{ port?: number, host?: string, dir?: string, cwd?: string }} [options]
  * @returns {Promise<{ server: import('node:http').Server, port: number, url: string }>}
  * @throws {DocPensieveError} When the folder to serve does not exist.
  */
@@ -34,11 +34,13 @@ export async function serve(options = {}) {
   // The site is mounted under the configuration's baseUrl: otherwise the links
   // of the generated pages would not resolve locally.
   const server = createStaticServer({ root, basePath: config.baseUrl });
-  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const host = options.host ?? DEFAULT_HOST;
+  const port = await listen(server, options.port ?? DEFAULT_PORT, 10, host);
   const url = `http://localhost:${port}${config.baseUrl}`;
 
   console.log(`${root}`);
   console.log(`served at ${url}`);
+  if (isExposed(host)) console.log(exposedNotice(host));
 
   return { server, port, url };
 }

package/src/server.js

@@ -162,16 +162,35 @@ export function createStaticServer({ root, basePath = '/', inject = null, onRelo
   });
 }
 
+/** The loopback address: the site is served to this machine and to no other. */
+export const DEFAULT_HOST = '127.0.0.1';
+
+/**
+ * Whether an address reaches beyond this machine.
+ *
+ * @param {string} host
+ * @returns {boolean}
+ */
+export function isExposed(host) {
+  return !['127.0.0.1', 'localhost', '::1'].includes(host);
+}
+
 /**
  * Starts listening, looking for a free port if needed.
  *
+ * On this machine only, unless asked otherwise. Called without a host, Node
+ * listens on every interface: anyone on the same network — a café, a
+ * coworking space — could read the site being written, drafts included.
+ *
  * @param {import('node:http').Server} server
  * @param {number} port Desired port.
  * @param {number} [attempts] Number of ports tried from `port` on.
+ * @param {string} [host] Address to listen on. `0.0.0.0` opens it to the
+ *   network, which a phone on the same wifi needs.
  * @returns {Promise<number>} The port actually used.
  * @throws {DocPensieveError} When no port is free in the range.
  */
-export function listen(server, port, attempts = 10) {
+export function listen(server, port, attempts = 10, host = DEFAULT_HOST) {
   return new Promise((resolve, reject) => {
     let current = port;
 
@@ -181,7 +200,7 @@ export function listen(server, port, attempts = 10) {
       // the next one beats forcing --port.
       if (error.code === 'EADDRINUSE' && current < port + attempts - 1) {
         current += 1;
-        server.listen(current);
+        server.listen(current, host);
         return;
       }
       server.off('error', onError);
@@ -202,6 +221,17 @@ export function listen(server, port, attempts = 10) {
       const address = server.address();
       resolve(typeof address === 'object' && address !== null ? address.port : current);
     });
-    server.listen(current);
+    server.listen(current, host);
   });
 }
+
+/**
+ * Said when the site is opened to the network, so that it is never done
+ * without the person knowing.
+ *
+ * @param {string} host
+ * @returns {string}
+ */
+export function exposedNotice(host) {
+  return `listening on ${host}: anyone on this network can read the site.`;
+}

package/starter/01-guide/01-installation.md

@@ -46,6 +46,7 @@ npx docpensieve init my-site --yes --name "My documentation"
 | `-t, --theme <framework>`  | `tailwind` or `custom`                                  |
 | `-u, --site-url <url>`     | Public URL, from which the deployment prefix is derived |
 | `--version-name <version>` | First version, `1.0` for instance                       |
+| `--translation <code>`     | Code of a second language, `fr` for instance            |
 | `-y, --yes`                | Accepts the defaults without a dialogue                 |
 | `-f, --force`              | Overwrites an existing configuration                    |
 | `--minimal`                | Leaves DocPensieve's documentation out of the site      |

package/starter/01-guide/02-first-site.md

@@ -98,6 +98,10 @@ online.
     → ignores the deployment prefix "/my-project/"
 ```
 
+Two commands, and the second reads what the first wrote — so they belong
+together. [Deployment](./deployment/) shows how to say that once, in a
+`package.json`, and have a workflow run the same thing you run.
+
 It is the check to run after any change of `baseUrl`, of folder structure or of
 URL. When something does not add up, [When it breaks](./when-it-breaks/) lists
 the failures this tool produces, by the symptom you see.

package/starter/01-guide/06-deployment.md

@@ -88,6 +88,32 @@ the tool through `npx`, which takes the latest published version. To pin it
 from one build to the next, declare `docpensieve` in a `package.json` and add
 `npm ci` before the build.
 
+## One command, for you and for the machine
+
+Two commands are one too many to remember, and a workflow should run exactly
+what you run. A `package.json` is the place to say it once:
+
+```json
+{
+  "scripts": {
+    "docs": "docpensieve dev",
+    "check": "docpensieve build && docpensieve check"
+  }
+}
+```
+
+`npm run check` then generates the site and reads it back. A dead link, a
+nesting the markup cannot carry, a page that stops the build: each one fails
+the command, on your machine and in your workflow, in the same way and with
+the same message.
+
+The `&&` is the point of it. `check` reads what `build` wrote, so a check run
+on its own tells you about the site as it was the last time it was generated —
+which, the day you forget, is the day it matters.
+
+With that in place the recipe above becomes `npm ci` and `npm run check`, and
+the version of the tool stops depending on the day the workflow ran.
+
 ## Reading back before publishing
 
 A generated site can compile without error and contain dead links.

package/starter/01-guide/07-migrate-to-beta.md

@@ -31,8 +31,23 @@ npx docpensieve check
 
 ## What changes on its own
 
-Nothing yet: the 0.5 has just opened. Each change is listed here as it lands,
-beside what it asks of a project already built on the 0.4.
+- **`dev` and `serve` listen on this machine only.** They used to listen on
+  every interface, so anyone on the same network could read the site being
+  written. To look at it from a phone on the same wifi, say so:
+  `npx docpensieve dev --host 0.0.0.0`.
+- **Code blocks carry a background of their own.** A block in a language the
+  highlighter does not know used to sit on the bare page; it now looks like
+  every other block.
+- **An error keeps its hint.** An error the tool raises while a page compiles
+  no longer comes out as a generic syntax complaint.
+
+## What is worth turning on
+
+- [Snippet](../components/snippet/), to show a real file rather than a copy.
+- [Hero](../components/hero/) and [Calendar](../components/calendar/).
+- `copyCode`, a copy button on every code block — off by default, since it is
+  what makes a page load a script. See [the reference](../reference/configuration/).
+- `snippetIcons`, if your project installs an icon collection.
 
 ## What to check afterwards