docpensieve 0.4.0 → 0.5.0-beta.2

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")

package/package.json

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

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`)} },`,
     '    },',
     '  ],',
     '',
@@ -353,11 +414,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 +440,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 +465,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 +618,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 +647,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 +686,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 +712,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/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      |
@@ -99,8 +100,9 @@ The documentation `init` installed in `99-docpensieve` stays at the version it
 came with. To refresh it, run `init` in a scratch folder and copy that folder
 over.
 
-Coming from the 0.3, [Migrate from 0.3 to 0.4](./migrate-from-0-3/) says what
-changes on its own and what to check first.
+Coming from the 0.4, [Migrate from latest to beta](./migrate-to-beta/) says
+what changes on its own and what to check first. To try this beta, install
+`docpensieve@beta`, or run `npx docpensieve@beta` alone.
 
 ## Checking
 

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

@@ -0,0 +1,41 @@
+---
+title: Migrate from latest to beta
+description: Move a project from the latest version, the 0.4, to the 0.5 beta — what changes on its own, and what to check.
+tags: [guide, migration]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Migrate from latest to beta
+
+A project on the latest version — the 0.4 — builds with the 0.5 beta as it is:
+every field the 0.5 adds is optional.
+
+## Update
+
+```bash
+npm install docpensieve@beta
+```
+
+Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
+`npm install docpensieve@latest`.
+
+Read your site back once after the update — it is the cheapest check there is:
+
+```bash
+npx docpensieve build
+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.
+
+## What to check afterwards
+
+- **Your own CSS**, if the theme folder styles anything the beta touches.
+- **`npx docpensieve check`**, which reads the built site back and reports dead
+  links and invalid markup.

package/starter/01-guide/10-languages.md

@@ -13,6 +13,19 @@ jsonld:
 A version can be published in several languages. Each one is a folder of pages
 of its own, standing beside the version it translates.
 
+## Starting from init
+
+`init` asks whether the site will be in several languages. Answer yes, give a
+code, and the project comes out wired: the folder beside your pages, the field
+in the configuration, and a home page in that language to start from.
+
+```bash
+npx docpensieve init my-site --translation fr
+```
+
+Everything below is what that answer sets up — and what to do when you add a
+language to a project that already exists.
+
 ## Declaring a translation
 
 ```js

package/starter/03-reference/01-cli.md

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

package/starter/03-reference/05-api.md

@@ -346,6 +346,39 @@ a language nobody thought of.
 
 **Returns** `'ltr' \| 'rtl'` — `ltr` when the language is unknown — the safe default, and what every page did before this existed.
 
+### `isLanguageCode`
+
+`isLanguageCode(value)`
+
+Whether a string names a language, as BCP 47 and CLDR understand it.
+
+The standard is BCP 47, and `Intl` carries it: a regex of our own refused
+`zh-Hans-CN`, which is valid, and accepted shapes that are not. Well formed
+is not the same as real, though — BCP 47 allows a language subtag of five
+to eight letters, so `francais` passes that check and would land in the
+markup as `lang="francais"`, a value no browser maps to a language. CLDR
+knows which tags name one; the subtag alone is asked, so that a region, a
+script or a private extension does not get in the way.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `value` | `string` |  |
+
+**Returns** `boolean`
+
+### `languageName`
+
+`languageName(code, [inLang])`
+
+Name of a language, written in a language.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `code` | `string` | Language code. |
+| `[inLang]` | `string` | Language the name is written in. |
+
+**Returns** `string` — The name, or the code itself when nothing names it.
+
 ## `@docpensieve/core`
 
 Configuration, loading, compilation, structured data and generation.
@@ -1211,11 +1244,11 @@ Sets up a documentation project.
 | Parameter | Type | |
 | --- | --- | --- |
 | `[dir]` | `string` | Target folder, created if needed. |
-| `[options]` | `{ name?: string, theme?: string, siteUrl?: string, version?: string, yes?: boolean, force?: boolean, minimal?: boolean, }` | `minimal` leaves DocPensieve's documentation out of the site. |
+| `[options]` | `{ name?: string, theme?: string, siteUrl?: string, version?: string, translation?: string, yes?: boolean, force?: boolean, minimal?: boolean, }` | `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 }>`
+**Returns** `Promise<{ dir: string, theme: string, docs: boolean, translation: string, }>`
 
-**Throws** `DocPensieveError` — Unknown framework, project already initialised, or documentation to install missing.
+**Throws** `DocPensieveError` — Unknown framework, unknown language, project already initialised, or documentation to install missing.
 
 ### `serve`
 

package/starter/05-whats-new.md

@@ -1,92 +1,46 @@
 ---
-title: What's new in 0.4
-description: What the 0.4 brings, and what it changes for a 0.3 project.
+title: What's new in 0.5
+description: What the 0.5 brings, and what it changes for a 0.4 project.
 tags: [release]
 ---
 
-# What's new in 0.4
+# What's new in 0.5
 
-The 0.4 is out, and installs by default:
+This version is **in preparation**. Its betas go out under the npm tag `beta`,
+while the version installed by default stays the 0.4, documented in the
+`latest` pages of this site:
 
 ```bash
-npx docpensieve init my-site
+npx docpensieve@beta init my-site
 ```
 
-Each feature below links to the guide and to the reference: this page gathers
-them, it is never the only place something is written.
+Each feature is announced here as it lands, with a link to the guide and to the
+reference: this page announces, it is never the only place something is
+written.
 
-## What it brings
+## Already there
 
-The 0.4 turns on the navigation. A site of forty pages was asking its reader to
-scroll past what did not concern them; it can now fold its menu, carry its own
-links in the header, and set a passage apart in the middle of a page.
+### init asks about languages
 
-### A menu that folds
+`init` now asks whether the site will be in several languages, and sets the
+answer up: the folder beside your pages, `translations` written out in the
+configuration, and a home page in that language to start from. The second
+sample page is deliberately left untranslated, so that the menu shows what an
+untranslated page does — nothing, in that language.
 
-`foldedSidebar: true` folds the categories of the documentation menu, and opens
-the branch the reader stands in. On a narrow screen the whole menu folds above
-the content, whatever that setting — nothing to configure for that one. See
-[Navigation](./guide/navigation/).
-
-### Links and panels in the header
-
-A `headerLinks` entry adds a link beside the version switcher. An entry
-carrying `columns` opens a **panel** of links instead of leading anywhere, so a
-site can navigate from the header alone, from the menu alone, or from both with
-different links. A `version` field points every version at a single one, which
-is how this site leads to its examples. See
-[Navigation](./guide/navigation/) and
-[the configuration reference](./reference/configuration/).
-
-### A header held, or not
-
-`stickyHeader` decides whether the header holds to the top of the screen or
-scrolls away with the page, giving its height back to the text. It stays held
-by default. See [Navigation](./guide/navigation/).
-
-### A menu of links, anywhere in a page
-
-The `Menu` component places a row of links where a page needs them — a summary
-at the top of a landing page, the chapters of a guide. Entries can be grouped
-under a title, and the row folds behind a button on a narrow screen, without a
-script. See [Menu](./components/menu/).
-
-### Blocks that stand apart
-
-`Admonition` sets a passage apart and says how to read it: `note`, `info`,
-`tip`, `attention`, `alert`, `danger`. A project declares **its own kinds** in
-the `admonitions` field — a label and a tone taken from the theme — so the list
-does not have to grow for a team to have the block it needs. See
-[Admonition](./components/admonition/).
-
-### Icons from a set
-
-`LogoIcon` accepts the name of an icon from a collection, written
-`simple-icons:github`, beside a file of your project. The set is a package your
-project installs and the drawing is placed in the page at the build, like any
-other icon: your reader downloads nothing, and no request leaves their browser.
-An admonition kind takes its mark the same way. See
-[LogoIcon](./components/logo-icon/).
-
-### A site in several languages
-
-A version declares the folder of each translation:
-
-```js
-versions: [
-  { slug: 'latest', name: '1.0', folder: 'docs/v1.0', current: true,
-    translations: { fr: 'docs/v1.0-fr' } },
-],
+```bash
+npx docpensieve init my-site --translation fr
 ```
 
-The language of the site keeps the addresses it has, and a translation is
-served under its code — `/versions/latest/fr/`. The shell follows: English and
-French ship with the tool, and the `ui` field corrects a word or adds a
-language. A page nobody translated is not offered in that language rather than
-served in another. See [Languages](./guide/languages/).
+A code is a BCP 47 one: `fr`, `pt-BR`, `zh-Hans`. French and English ship with
+their wording for the shell; any other language keeps the English wording
+until the `ui` field gives it its own.
+
+[Languages](./guide/languages/) · [The init options](./reference/cli/)
 
-## For a 0.3 project
+## For a 0.4 project
 
-Nothing to change: a 0.3 configuration builds as it is, every new field being
-optional. [Migrate from 0.3 to 0.4](./guide/migrate-from-0-3/) lists what
-changes on its own, and what is worth turning on.
+Nothing to change: a 0.4 configuration builds as it is, and a site already in
+two languages is untouched — the question only shapes a **new** project.
+[Migrate from latest to beta](./guide/migrate-to-beta/) lists what changes on
+its own, and what is worth turning on.

package/types/commands/init.d.ts

@@ -9,17 +9,21 @@
  * @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 declare function init(dir?: string, options?: {
     name?: string;
     theme?: string;
     siteUrl?: string;
     version?: string;
+    translation?: string;
     yes?: boolean;
     force?: boolean;
     minimal?: boolean;
@@ -27,4 +31,5 @@ export declare function init(dir?: string, options?: {
     dir: string;
     theme: string;
     docs: boolean;
+    translation: string;
 }>;

package/starter/01-guide/07-migrate-from-0-3.md

@@ -1,125 +0,0 @@
----
-title: Migrate from 0.3 to 0.4
-description: Move a project from the 0.3 to the 0.4 — what changes on its own, and what to turn on.
-tags: [guide, migration]
----
-
-# Migrate from 0.3 to 0.4
-
-A project on the 0.3 builds with the 0.4 as it is: every field the 0.4 adds is
-optional, and leaving them out keeps the site you have.
-
-## Update
-
-```bash
-npm install docpensieve@latest
-```
-
-Through `npx` alone, `npx docpensieve` already runs it.
-
-Read your site back once after the update — it is the cheapest check there is:
-
-```bash
-npx docpensieve build
-npx docpensieve check
-```
-
-## What changes on its own
-
-**On a narrow screen, the documentation menu now folds above the content**
-instead of standing open between the header and the text. Nothing to
-configure, and nothing to undo: on a wide screen the menu is unchanged.
-
-Nothing else moves. Your pages, your configuration and your theme folder are
-read exactly as before.
-
-## What is worth turning on
-
-Each of these is one line of `docpensieve.config.mjs`. None depends on
-another.
-
-### A menu that folds
-
-Past twenty or so pages, a menu that shows everything asks the reader to scroll
-past what does not concern them:
-
-```js
-foldedSidebar: true,
-```
-
-The categories fold, and the branch of the page being read opens on its own.
-A category that is also a page keeps its page as the first entry — the handle
-of a fold cannot be a link.
-
-### Links in the header
-
-```js
-headerLinks: [
-  { label: 'Blog', href: '/blog/' },
-  { label: 'Repository', href: 'https://example.com/repo' },
-],
-```
-
-A target starts from the root of a version, or is a full address. An entry
-carrying `columns` opens a panel instead of leading anywhere; `href` and
-`columns` together are refused, an entry doing one thing or the other.
-
-See [Navigation](./navigation/) for the panel and for what happens on a phone.
-
-### A header that scrolls away
-
-```js
-stickyHeader: false,
-```
-
-The header gives its height back to the text instead of holding to the top of
-the screen. It stays held by default.
-
-### Blocks that stand apart
-
-Six kinds ship — `note`, `info`, `tip`, `attention`, `alert`, `danger` — and
-need no configuration:
-
-```mdx
-<Admonition type="attention">Read this before upgrading.</Admonition>
-```
-
-Kinds of your own take a label and a tone:
-
-```js
-admonitions: {
-  review: { label: 'To review', tone: 'attention' },
-},
-```
-
-A kind nobody declared stops the build rather than rendering a block with no
-colour and no label. See [Admonition](../components/admonition/).
-
-### Icons from a set
-
-Beside a file of your project, `LogoIcon` accepts the name of an icon from a
-collection:
-
-```bash
-npm install --save-dev @iconify-json/simple-icons
-```
-
-```mdx
-<LogoIcon src="simple-icons:github" label="Repository" />
-```
-
-The set is read at the build and the drawing placed in the page: no request
-leaves your reader's browser. See [LogoIcon](../components/logo-icon/).
-
-## What to check afterwards
-
-- **Your own CSS**, if the theme folder styles the header or the menu: the
-  folded menu adds `details` and `summary` elements where there were only
-  links, and a static header no longer carries `position: sticky`.
-- **A link to a heading**, if you turned the sticky header off: the space kept
-  above an anchor goes away with it, which is the point.
-- **`npx docpensieve check`**, which reads the built site back and reports dead
-  links and invalid markup.
-
-None of this is required. A project that turns none of it on is a 0.3 project
-that happens to be running the 0.4.