docpensieve 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.1.5",
-    "@docpensieve/core": "0.1.5",
-    "@docpensieve/shared": "0.1.5",
-    "@docpensieve/theme": "0.1.5",
+    "@docpensieve/components": "0.2.0",
+    "@docpensieve/core": "0.2.0",
+    "@docpensieve/shared": "0.2.0",
+    "@docpensieve/theme": "0.2.0",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"
@@ -45,7 +45,7 @@
     "url": "git+https://github.com/Juniors017/docpensieve.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/Juniors017/docpensieve#readme",
+  "homepage": "https://docpensieve.com",
   "bugs": {
     "url": "https://github.com/Juniors017/docpensieve/issues"
   },

package/src/commands/init.js

@@ -56,7 +56,7 @@ const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons', EXAMPLES_CSS]);
 const CUSTOM_CSS = fileURLToPath(new URL('../templates/custom.css', import.meta.url));
 
 /** Where the generated configuration sends readers for every field. */
-const DOCUMENTATION_URL = 'https://juniors017.github.io/docpensieve/';
+const DOCUMENTATION_URL = 'https://docpensieve.com/';
 
 /**
  * Asks a question, with a default value shown between brackets.
@@ -235,7 +235,12 @@ function renderConfig({ name, theme, siteUrl, version }) {
     "    // 'tailwind' compiles the utilities your pages use; 'custom' is a plain",
     '    // stylesheet with no dependency.',
     `    framework: ${quote(theme)},`,
+    "    // 'class' follows the reader's system; 'dark' or 'light' keeps one scheme.",
     "    darkMode: 'class',",
+    '    // A light / dark button in the header, which remembers the choice: a few',
+    '    // lines of inline script in every page. false removes it, and the pages',
+    '    // then load no script.',
+    '    toggle: true,',
     '',
     '    // Design tokens to override, for instance the accent colour:',
     "    // tokens: { '--dp-accent': '#008060', '--dp-radius': '0.75rem' },",
@@ -256,7 +261,9 @@ function renderConfig({ name, theme, siteUrl, version }) {
       : []),
     '  },',
     '',
-    "  // 'auto': the menu follows the folders and the 01-, 02- prefixes.",
+    "  // 'auto': the menu follows the folders and the 01-, 02- prefixes. To write",
+    "  // it by hand, name a JSON file instead — 'sidebar.json' — read from each",
+    '  // version folder.',
     "  sidebar: 'auto',",
     '',
     '  // The shipped components — Card, Columns, Tooltip… — usable in any .mdx',
@@ -268,6 +275,21 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '',
     '  // Structured data (JSON-LD) generated from the frontmatter of each page.',
     '  jsonld: { enabled: true },',
+    '',
+    '  // sitemap.xml of the published versions, for search engines — written',
+    '  // once siteUrl is set. robots.txt joins it when the site is served at',
+    '  // the root of its domain.',
+    // Commented out until siteUrl is known: written explicitly, it asks for a
+    // sitemap that cannot be built yet, and the configuration refuses it.
+    siteUrl ? '  sitemap: true,' : '  // sitemap: true,',
+    '',
+    '  // RSS feed of the pages that carry a date, at the root of the site. It',
+    '  // needs siteUrl.',
+    '  feed: false,',
+    '',
+    '  // A search field in the header, and a search page built with the site.',
+    '  // Content pages load no script: the search page alone does.',
+    '  search: true,',
     '};',
     '',
     '// Every field is described in the reference of the DocPensieve documentation:',

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

@@ -99,6 +99,10 @@ 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.1, [Migrate from 0.1 to 0.2](./migrate-from-0-1/) says what
+changes on its own and what to check first. To try the version being prepared,
+install `docpensieve@beta`, or run `npx docpensieve@beta` alone.
+
 ## Checking
 
 ```bash

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

@@ -95,3 +95,14 @@ online.
 
 It is the check to run after any change of `baseUrl`, of folder structure or of
 URL.
+
+## Searching the site
+
+Every page carries a search field in its header. It leads to the search page
+of the version, at `/search/`, which the build writes with the site: the list
+of every page, that a small script filters as the reader types — best matches
+first, each with an excerpt. It is the only page to load a script of its own,
+and without it, it stays the list of every page.
+
+It works the same under both themes. `search: false` in the configuration
+removes the field and the page.

package/starter/01-guide/03-writing-pages.md

@@ -65,6 +65,30 @@ docs/v1.0/
     └── 01-card.mdx
 ```
 
+## Writing the menu by hand
+
+When the file tree does not give the menu you want, describe it in a JSON file
+of the version's folder, and name it in the configuration:
+
+```js
+// docpensieve.config.mjs
+sidebar: 'sidebar.json',
+```
+
+```json
+[
+  "/",
+  { "label": "Start here", "items": ["guide/installation", "guide/first-site"] },
+  { "auto": "components" },
+  { "label": "Repository", "href": "https://github.com/me/my-project" }
+]
+```
+
+A page is named by its path, as in its URL. `{ "auto": "components" }` keeps
+the automatic menu of a folder — the DocPensieve section stays whole that way.
+A page the file leaves out is still published, only off the menu. Every kind
+of entry is in the [`sidebar` reference](../reference/configuration/).
+
 ## Internal links
 
 Two spellings, two meanings:
@@ -92,6 +116,12 @@ An image sits next to the page and is written relatively:
 Files that are not pages are copied as is into the output, at the same
 relative place. The path is rewritten like a link.
 
+The build reads the width and height of each image from its file — PNG, JPEG,
+GIF, WebP or SVG — and writes them on the page: the browser keeps the room
+before the image arrives, instead of shifting the text when it does. Every
+image but the first loads lazily, when the reader nears it; the first, often in
+view, keeps its normal loading.
+
 ## Components
 
 In an `.mdx` page, the shipped components are used **without an import**:

package/starter/01-guide/04-versions.md

@@ -54,6 +54,27 @@ Two rules to remember:
 The switcher only appears in the header from **two** versions on: a single
 choice is not a choice.
 
+### Naming a version: the number or the channel
+
+The `slug` is the address. Two conventions, and the choice is not neutral.
+
+**The number** — `v1.0`, `v1.1` — gives each version an address that never
+moves: a link captured today leads to the same pages in two years. But the
+address can only carry what stays true for a whole series. `v1.0` still names
+the documentation once `1.0.7` is out, so the URL says less than the switcher,
+which reads the exact version.
+
+**The channel** — `latest`, `beta` — names the role instead. The address a
+reader shares stays right for ever: `/versions/latest/` always leads to the
+documentation that counts, `/versions/beta/` to the one being prepared. What
+moves is what sits behind it — on release day, `latest` becomes the new
+version, and the one it replaces takes a numbered slug as it is archived: its
+content freezes, so its address can freeze with it.
+
+Neither is better. Take the number if your readers link to a precise version,
+the channel if they link to "the documentation". DocPensieve's own
+documentation takes the channel: its versions are `latest` and `beta`.
+
 ## 2. Opening the beta
 
 Start from the current version, and give it its own folder:
@@ -131,9 +152,10 @@ those who use it.
 
 > **The `slug` changes along with the folder, and so does the URL.**
 > `/versions/v1.1-beta/` disappears in favour of `/versions/v1.1/`, and the
-> external links that pointed to the beta lead nowhere any more. To avoid this,
+> external links that pointed to the beta lead nowhere any more. Two ways out:
 > keep the same slug from start to finish — `v1.1` from the start, with only
-> the label mentioning the beta.
+> the label mentioning the beta — or name the channel rather than the number,
+> `beta` then `latest`, which never moves. See _Naming a version_ above.
 
 ## What the build produces
 

package/starter/01-guide/05-themes.md

@@ -81,6 +81,55 @@ theme: {
 
 The content of `css` is appended to the produced stylesheet.
 
+## Colour scheme
+
+`theme.darkMode` decides which palette the reader gets. `'class'`, the default,
+follows the reader's system; `'dark'` or `'light'` keeps one whatever the
+system — the build sets it as a class on `<html>`.
+
+The header also carries a button that switches between light and dark, and
+remembers the reader's choice from page to page — a few hundred bytes of inline
+script, the only one content pages carry. `theme.toggle: false` removes it.
+Without JavaScript, the button does not show.
+
+The dark palette is a set of tokens, the same under both themes. To change it,
+redefine them in the `theme/` folder, for both ways of being dark — the
+system's scheme, and the class that `darkMode: 'dark'` sets:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) {
+    --dp-bg: #060814;
+  }
+}
+
+:root.dark {
+  --dp-bg: #060814;
+}
+```
+
+<ForTheme framework="tailwind">
+
+The `dark:` utilities of your pages follow the same rule: they apply under the
+system's dark scheme, and always once `darkMode: 'dark'` is set.
+
+```mdx
+<div className="bg-white dark:bg-slate-900">…</div>
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
+Your own classes follow it through the same two selectors:
+
+```css
+:root.dark .note {
+  border-color: var(--dp-accent);
+}
+```
+
+</ForTheme>
+
 ## Layer order
 
 Under the `tailwind` theme, the stylesheet declares its layers in this order:

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

@@ -122,3 +122,21 @@ result years later.
 
 The branch model answers this — each compiled version on its own orphan branch,
 with its history. See [Versions](./versions/).
+
+## Search engines and feed readers
+
+With `siteUrl` set, the build writes `sitemap.xml` at the root of the site —
+every published version, a version in preparation excepted. Give its address
+to the search engines you care about; `robots.txt` names it for them when the
+site sits at the root of its domain.
+
+For pages that are news rather than reference — release notes, a changelog —
+give them a `date` and set `feed: true`: `feed.xml` then lists them, newest
+first. The fields are in the [configuration reference](../reference/configuration/).
+
+## What the reader downloads
+
+The build keeps it light on its own. The stylesheet is minified — a third to
+half lighter. Every image of a page gets its width and height, read from its
+file, so that the text does not jump when it arrives, and all but the first
+load lazily, when the reader nears them. There is nothing to configure.

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

@@ -0,0 +1,57 @@
+---
+title: Migrate from 0.1 to 0.2
+description: Move a project from the 0.1 to the 0.2 — what changes on its own, what to check, what to turn on.
+tags: [guide, migration]
+---
+
+# Migrate from 0.1 to 0.2
+
+A project on the 0.1 builds with the 0.2 as it is: every new field is
+optional. A few things change on their own, though, and deserve a look.
+
+## Update
+
+```bash
+npm install docpensieve@latest
+```
+
+Through `npx` alone, `npx docpensieve` fetches the 0.2 by itself. Going back
+is `npm install docpensieve@0.1.5`.
+
+## What changes on its own
+
+| What                | In 0.2                                                                              |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| Search              | A field in the header, and a page at `/search/` in each version                     |
+| `sitemap.xml`       | Written at the root of the site as soon as `siteUrl` is set                         |
+| `robots.txt`        | Written with it, when the site is served at the root of its domain                  |
+| The stylesheet      | Minified                                                                            |
+| Images              | Their width and height are written; all but the first of a page load lazily         |
+| Light / dark switch | A button in the header, remembered from page to page — a few lines of inline script |
+| `theme.darkMode`    | Now read: `'dark'` and `'light'` keep one scheme, `'class'` follows the system      |
+
+Every page now carries the few lines of the light / dark switch —
+`theme.toggle: false` removes them — and the search page loads its own script.
+
+## What to check
+
+- **A page of yours at `/search/`** now stops the build: that address is the
+  search page's. Rename your page, or set `search: false`.
+- **`theme.darkMode`** was accepted and ignored in 0.1. A value other than
+  `'class'` now takes effect — and an unknown one stops the build.
+- **The light / dark switch** is on by default. `theme.toggle: false` removes
+  it, and with it the only script content pages carry.
+- **Your own `robots.txt`**, if you published one next to the site, is now
+  written by the build when the site sits at the root of its domain. Set
+  `sitemap: false` to keep yours.
+
+## What to turn on
+
+| Field                        | Gives                                                         |
+| ---------------------------- | ------------------------------------------------------------- |
+| `sidebar: 'sidebar.json'`    | A menu written by hand, in each version's folder              |
+| `feed: true`                 | An RSS feed of the pages that carry a `date`                  |
+| `versions[].logo`, `favicon` | A logo and a favicon of the version's own — a beta told apart |
+| `search: false`              | No search at all, if the site does not need one               |
+
+Every field is in the [configuration reference](../reference/configuration/).

package/starter/01-guide/index.md

@@ -25,6 +25,8 @@ up.
    touching the HTML.
 6. **[Deployment](./deployment/)** — publish, and keep past versions
    online.
+7. **[Migrate from 0.1 to 0.2](./migrate-from-0-1/)** — move a 0.1 project to
+   the 0.2.
 
 ## What to know first
 

package/starter/02-components/01-card.mdx

@@ -188,9 +188,9 @@ carrying the caption.
     <Card className="h-full text-center">
       <CardBody>
         <div className="text-4xl font-semibold text-indigo-600">0</div>
-        <div className="text-sm">bytes of JavaScript</div>
+        <div className="text-sm">bytes of JavaScript runtime</div>
       </CardBody>
-      <CardFooter>on every delivered page</CardFooter>
+      <CardFooter>on every page</CardFooter>
     </Card>
   </Column>
   <Column span={4}>
@@ -221,9 +221,9 @@ carrying the caption.
     <Card className="full-height centered">
       <CardBody>
         <div className="figure">0</div>
-        <div className="small">bytes of JavaScript</div>
+        <div className="small">bytes of JavaScript runtime</div>
       </CardBody>
-      <CardFooter>on every delivered page</CardFooter>
+      <CardFooter>on every page</CardFooter>
     </Card>
   </Column>
   <Column span={4}>

package/starter/02-components/04-tooltip.mdx

@@ -93,7 +93,7 @@ The shipped components avoid that clipping wherever they can — a `Card` rounds
 the corners of its image one by one rather than clipping its content.
 
 The bubble does not close with the Escape key: listening for it would take a
-script, and the site loads none. It disappears when the pointer or the focus
+script, and components load none. It disappears when the pointer or the focus
 leaves the term.
 
 A `Tooltip` without text stops the build: a hover with no effect goes

package/starter/02-components/08-logo-icon.mdx

@@ -146,5 +146,4 @@ folder: each one stops the build, naming the expected path. A missing icon
 would otherwise leave an empty box that nobody notices.
 
 The scripts and event handlers present in a file are removed before inlining.
-The produced site loads no JavaScript, and a component is not going to
-introduce any.
+A component loads no JavaScript, and this one is not going to introduce any.

package/starter/02-components/index.mdx

@@ -75,7 +75,7 @@ changes the examples too.
 
 ## Without JavaScript
 
-The produced site loads no script. Whatever needs interaction therefore goes
+No component loads a script. Whatever needs interaction therefore goes
 through native elements or through CSS: `details` for expanding, a link for
 moving, `animation-timeline` for appearing on scroll.
 

package/starter/03-reference/02-configuration.md

@@ -49,22 +49,25 @@ can change.
 
 ## The fields
 
-| Field              | Default             | Effect                                                                      |
-| ------------------ | ------------------- | --------------------------------------------------------------------------- |
-| `projectName`      | `'Documentation'`   | Name shown in the header and in the JSON-LD                                 |
-| `siteUrl`          | `''`                | Public URL. Used for the `canonical` and the JSON-LD                        |
-| `baseUrl`          | `'/'`               | Deployment prefix. Derived from `siteUrl` when omitted                      |
-| `outDir`           | `'dist'`            | Output folder, relative to the root                                         |
-| `versions`         | `[]`                | At least one entry                                                          |
-| `theme`            | see below           | Styling                                                                     |
-| `sidebar`          | `'auto'`            | `'auto'`: the sidebar follows the file tree. The only value written so far  |
-| `globalComponents` | `true`              | Shipped components available without an import                              |
-| `scrollToTop`      | `true`              | Back-to-top button on every page                                            |
-| `jsonld`           | `{ enabled: true }` | Structured data                                                             |
-| `lang`             | `'en'`              | Language of the document, in `<html lang>`. The shell's labels stay English |
-| `logo`             | `''`                | Image beside the project name, in the header                                |
-| `favicon`          | `''`                | Icon of the browser tab: `.ico`, `.png` or `.svg`                           |
-| `socialImage`      | `''`                | Preview of a shared page. Needs `siteUrl`                                   |
+| Field              | Default             | Effect                                                                             |
+| ------------------ | ------------------- | ---------------------------------------------------------------------------------- |
+| `projectName`      | `'Documentation'`   | Name shown in the header and in the JSON-LD                                        |
+| `siteUrl`          | `''`                | Public URL. Used for the `canonical` and the JSON-LD                               |
+| `baseUrl`          | `'/'`               | Deployment prefix. Derived from `siteUrl` when omitted                             |
+| `outDir`           | `'dist'`            | Output folder, relative to the root                                                |
+| `versions`         | `[]`                | At least one entry                                                                 |
+| `theme`            | see below           | Styling                                                                            |
+| `sidebar`          | `'auto'`            | `'auto'`: the menu follows the file tree. Or a `.json` file of each version folder |
+| `globalComponents` | `true`              | Shipped components available without an import                                     |
+| `scrollToTop`      | `true`              | Back-to-top button on every page                                                   |
+| `jsonld`           | `{ enabled: true }` | Structured data                                                                    |
+| `lang`             | `'en'`              | Language of the document, in `<html lang>`. The shell's labels stay English        |
+| `logo`             | `''`                | Image beside the project name, in the header                                       |
+| `favicon`          | `''`                | Icon of the browser tab: `.ico`, `.png` or `.svg`                                  |
+| `socialImage`      | `''`                | Preview of a shared page. Needs `siteUrl`                                          |
+| `sitemap`          | `true`              | `sitemap.xml` of the published versions, once `siteUrl` is set                     |
+| `feed`             | `false`             | RSS feed of the dated pages. Needs `siteUrl`                                       |
+| `search`           | `true`              | Search field in the header, and a search page built with the site                  |
 
 ## Images
 
@@ -87,6 +90,45 @@ version, under `assets/`, so that a version stays whole on its own branch.
 
 A declared image that does not exist stops the build, naming the field.
 
+## Sitemap and feed
+
+```js
+siteUrl: 'https://example.com',
+sitemap: true, // the default
+feed: true,
+```
+
+Once `siteUrl` is set, the build writes `sitemap.xml` at the root of the site:
+every page of every version, except a version in preparation, whose pages
+carry `noindex`. Each page is dated by its `modified` frontmatter, or failing
+that its `date`. `sitemap: false` turns it off.
+
+`robots.txt` joins it when the site is served at the root of its domain.
+Search engines only read that file there: under a sub-path, it would be
+written for nobody — declare the sitemap to them directly.
+
+`feed: true` writes `feed.xml`, an RSS feed of the pages of the current version
+that carry a `date`, newest first, and every page announces it in its head.
+It is off by default: most documentation pages carry no date.
+
+Both list absolute addresses: asked for without `siteUrl`, they stop the build.
+
+## Search
+
+`search: true`, the default, puts a search field in the header and builds a
+search page in each version, at `/search/`. The build writes the index of the
+version — the plain text of every page — and the search page already lists
+every page with its description.
+
+The field is a plain form that leads to that page: it needs no script. The
+search page loads one of its own, of a few kilobytes, which filters
+the list as you type, best matches first, with an excerpt of each. Without
+JavaScript, the page stays the full list of pages.
+
+The search page is kept out of search engines (`noindex`) and out of the
+sitemap. A page of your own at `/search/` would take its place: the build
+refuses it, and `search: false` frees the address.
+
 ## `versions`
 
 ```js
@@ -96,14 +138,16 @@ versions: [
 ],
 ```
 
-| Field        | Role                                                             |
-| ------------ | ---------------------------------------------------------------- |
-| `slug`       | URL and branch identifier                                        |
-| `name`       | Label shown in the switcher                                      |
-| `folder`     | Source folder, relative to the root                              |
-| `current`    | Version served by default. At most one                           |
-| `archived`   | Version kept but no longer maintained. Banner, but stays indexed |
-| `prerelease` | Version in preparation. Banner **and** `noindex`                 |
+| Field        | Role                                                                                                                           |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `slug`       | URL and branch identifier. A number (`v1.0`) freezes the address; a channel (`latest`, `beta`) keeps it right as versions move |
+| `name`       | Label shown in the switcher                                                                                                    |
+| `folder`     | Source folder, relative to the root                                                                                            |
+| `current`    | Version served by default. At most one                                                                                         |
+| `archived`   | Version kept but no longer maintained. Banner, but stays indexed                                                               |
+| `prerelease` | Version in preparation. Banner **and** `noindex`                                                                               |
+| `logo`       | This version's logo, instead of the project's — a beta told apart at a glance                                                  |
+| `favicon`    | This version's favicon, instead of the project's                                                                               |
 
 ## `theme`
 
@@ -117,13 +161,14 @@ theme: {
 },
 ```
 
-| Field       | Effect                                    |
-| ----------- | ----------------------------------------- |
-| `framework` | `'tailwind'` or `'custom'`                |
-| `darkMode`  | Dark theme strategy                       |
-| `tokens`    | Redefined `--dp-*` tokens                 |
-| `css`       | CSS appended to the produced stylesheet   |
-| `source`    | Stylesheet handed to the utility compiler |
+| Field       | Effect                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `framework` | `'tailwind'` or `'custom'`                                                                                                          |
+| `darkMode`  | `'class'` follows the reader's system; `'dark'` or `'light'` keeps one scheme                                                       |
+| `toggle`    | On by default: a light / dark button in the header, remembered from page to page — a few lines of inline script. `false` removes it |
+| `tokens`    | Redefined `--dp-*` tokens                                                                                                           |
+| `css`       | CSS appended to the produced stylesheet                                                                                             |
+| `source`    | Stylesheet handed to the utility compiler                                                                                           |
 
 The available tokens are listed in [Themes](../guide/themes/).
 
@@ -132,6 +177,42 @@ Longer rules go in the `theme/` folder, at the root of the project: every
 `docpensieve dev` picks up every change. Under the `custom` theme, `init`
 starts it with `theme/custom.css`.
 
+## `sidebar`
+
+`'auto'` builds the menu from the file tree: folders become categories, and the
+`01-`, `02-` prefixes set the order. To write it by hand, name a JSON file:
+
+```js
+sidebar: 'sidebar.json',
+```
+
+It is read from **each version's folder** — `docs/v1.0/sidebar.json` — since
+each version has its own pages. It holds an array of entries, kept in the order
+written:
+
+```json
+[
+  "/",
+  { "label": "Guide", "page": "guide", "items": ["guide/installation", "guide/first-site"] },
+  { "page": "reference/cli", "label": "Commands" },
+  { "auto": "docpensieve" },
+  { "label": "Repository", "href": "https://github.com/me/my-project" }
+]
+```
+
+| Entry                           | What it gives                                                                   |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| `"guide/installation"`          | A page, by its path within the version, as in its URL — `"/"` for the home page |
+| `{ "page", "label" }`           | The same page, with a label of its own                                          |
+| `{ "label", "items", "page"? }` | A category, clickable when it names a page                                      |
+| `{ "label", "href" }`           | A link outside the site                                                         |
+| `{ "auto": "folder" }`          | The automatic menu of a folder: the DocPensieve section keeps its own this way  |
+
+A page left out stays published: it is only absent from the menu. A path that
+names no page, a page listed twice, or an entry of no known kind stops the
+build, naming the file and the paths close to the one written. The file itself
+is not published.
+
 ## `baseUrl`, and why you rarely write it
 
 A `siteUrl` with a sub-path already gives it: `https://example.com/my-project`

package/starter/03-reference/04-theme.md

@@ -25,13 +25,14 @@ theme: {
 },
 ```
 
-| Field       | Default                  | Effect                                                |
-| ----------- | ------------------------ | ----------------------------------------------------- |
-| `framework` | `'tailwind'`             | `'tailwind'` or `'custom'`                            |
-| `darkMode`  | `'class'`                | Dark theme strategy                                   |
-| `tokens`    | —                        | Redefined `--dp-*` tokens, merged with the provider's |
-| `css`       | `''`                     | CSS appended to the produced stylesheet               |
-| `source`    | `@import "tailwindcss";` | Stylesheet handed to the utility compiler             |
+| Field       | Default                  | Effect                                                                                                    |
+| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `framework` | `'tailwind'`             | `'tailwind'` or `'custom'`                                                                                |
+| `darkMode`  | `'class'`                | `'class'`: the reader's system, unless a class on `<html>` decides. `'dark'` or `'light'` sets that class |
+| `toggle`    | `true`                   | A light / dark button in the header, remembered from page to page                                         |
+| `tokens`    | —                        | Redefined `--dp-*` tokens, merged with the provider's                                                     |
+| `css`       | `''`                     | CSS appended to the produced stylesheet                                                                   |
+| `source`    | `@import "tailwindcss";` | Stylesheet handed to the utility compiler                                                                 |
 
 `source` only concerns the `tailwind` provider: it is the entry stylesheet it
 compiles. Replacing it lets you add directives — a `@theme` block, for
@@ -98,6 +99,8 @@ the `dp-*` class below.
 | `footer`        | `dp-footer`               | Page footer                                     |
 | `scrollTop`     | `dp-scroll-top`           | Back-to-top button                              |
 | `scrollTopIcon` | `dp-scroll-top-icon`      | Arrow of that button                            |
+| `search`        | `dp-search`               | Search field of the header                      |
+| `schemeToggle`  | `dp-scheme-toggle`        | Light / dark button of the header               |
 
 A slot can carry **variants**, suffixed `--variant`: `column` gives
 `dp-column--span-8`, `skill` gives `dp-skill--circle`.