docpensieve 0.2.0-beta.1 → 0.3.0-beta.1

package/package.json

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

package/src/commands/init.js

@@ -237,6 +237,10 @@ function renderConfig({ name, theme, siteUrl, version }) {
     `    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' },",

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.2, [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
 
 ```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/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

@@ -133,3 +133,10 @@ 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-to-beta.md

@@ -0,0 +1,24 @@
+---
+title: Migrate from latest to beta
+description: Move a project from the latest version, the 0.2, to the 0.3 beta — what changes on its own, and what to check.
+tags: [guide, migration]
+---
+
+# Migrate from latest to beta
+
+A project on the latest version — the 0.2 — builds with the 0.3 beta as it is:
+every new field is optional.
+
+## Update
+
+```bash
+npm install docpensieve@beta
+```
+
+Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
+`npm install docpensieve@latest`.
+
+## What changes on its own
+
+Nothing yet: the 0.3 has just opened. Each change is listed here as it lands,
+beside what it asks of a project already built on the 0.2.

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 latest to beta](./migrate-to-beta/)** — move a 0.2 project
+   to the 0.3 beta.
 
 ## 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 content 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 content 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 content pages load 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.
-Content pages load 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,8 +75,7 @@ changes the examples too.
 
 ## Without JavaScript
 
-Content pages load no script — the search page alone does. 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

@@ -120,8 +120,8 @@ 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: **content pages load no
-script**. The search page alone loads one, of a few kilobytes, which filters
+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.
 
@@ -138,16 +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`                              |
-| `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                              |
+| 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`
 
@@ -161,13 +161,14 @@ theme: {
 },
 ```
 
-| Field       | Effect                                                                        |
-| ----------- | ----------------------------------------------------------------------------- |
-| `framework` | `'tailwind'` or `'custom'`                                                    |
-| `darkMode`  | `'class'` follows the reader's system; `'dark'` or `'light'` keeps one scheme |
-| `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/).
 

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

@@ -29,6 +29,7 @@ theme: {
 | ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
 | `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                                                                 |
@@ -99,6 +100,7 @@ the `dp-*` class below.
 | `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`.

package/starter/04-architecture.md

@@ -36,9 +36,10 @@ utility theme needs to know which classes were actually used.
 
 ## React does not leave the build
 
-Components are rendered to HTML during the build. Content pages load no
-runtime: what reaches the reader is markup and a stylesheet. The search page
-alone adds a script, of a few kilobytes, to filter its list.
+Components are rendered to HTML during the build. Pages load no runtime: what
+reaches the reader is markup and a stylesheet, plus the few lines of the
+light / dark switch; the search page adds a script, of a few kilobytes, to
+filter its list.
 
 That explains the shape of the shipped components. None of them has state or
 an event listener, because there would be nothing to bring them to life.

package/starter/05-whats-new.md

@@ -1,73 +1,28 @@
 ---
-title: What's new in 0.2
-description: What the 0.2 brings, what it is still to bring, and what it changes for a 0.1 project.
+title: What's new in 0.3
+description: What the 0.3 brings, and what it changes for a 0.2 project.
 tags: [release]
 ---
 
-# What's new in 0.2
+# What's new in 0.3
 
 This version is **in preparation**. Its betas go out under the npm tag `beta`,
-while the version installed by default stays the 0.1, documented in the 0.1
-pages of this site:
+while the version installed by default stays the 0.2, documented in the
+`latest` pages of this site:
 
 ```bash
 npx docpensieve@beta init my-site
 ```
 
-What follows describes the 0.2 as it stands, and
-[Moving from 0.1 to 0.2](./migrating/) says what to check in a 0.1 project.
-
 ## Already there
 
-### A menu written by hand
-
-`sidebar: 'sidebar.json'` replaces the menu derived from the file tree with
-one you describe — pages in the order you want, categories, links outside the
-site. Each version reads its own file, since each has its own pages. A section
-can keep its automatic menu with a single entry, which is how the DocPensieve
-section stays whole without listing its pages.
-
-See [Writing the menu by hand](./guide/writing-pages/) in the guide, and the
-[`sidebar` field](./reference/configuration/) in the reference.
-
-### Search engines and feed readers
-
-With `siteUrl` set, the build writes `sitemap.xml` for search engines — and
-`robots.txt` when the site sits at the root of its domain. `feed: true` adds an
-RSS feed of the dated pages. See [Sitemap and feed](./reference/configuration/)
-in the reference.
-
-### Search
-
-A search field in the header, and a search page in each version. The index is
-built with the site; content pages still load no script — the search page
-alone does, and without it the page stays the list of every page. See
-[Search](./reference/configuration/) in the reference.
-
-### A colour scheme of your choosing, and a logo per version
-
-`theme.darkMode: 'dark'` keeps the site dark whatever the reader's system —
-`'light'` keeps it light; `'class'`, the default, still follows the system.
-Until now the field was accepted and did nothing. A version can also carry its
-own `logo` and `favicon`, to tell a beta apart at a glance. See the
-[configuration reference](./reference/configuration/).
-
-### Lighter pages
-
-The stylesheet reaches the reader minified. Every image of a page gets its
-width and height, read from its file, so that the text no longer jumps when it
-arrives; all but the first load lazily, and are no longer preloaded — the
-first, often in view, keeps its normal loading. `CardImage` loads lazily too.
-
-### The API reference, and two example projects
-
-Every export of the five packages is in the [API reference](./reference/api/),
-generated from the JSDoc of the sources, so that it cannot drift from the code.
-The repository also holds two complete example projects, one per theme, built
-and checked on every run of its tests.
+Nothing yet: the 0.3 has just opened, and its pages are still those of the 0.2.
+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.
 
-## For a 0.1 project
+## For a 0.2 project
 
-Nothing to change: a 0.1 configuration builds as it is. `sidebar: 'auto'`
-stays the default, and every new field is optional. A guide to moving from
-0.1 to 0.2 will come with the release.
+Nothing to change: a 0.2 configuration builds as it is.
+[Migrate from latest to beta](./guide/migrate-to-beta/) lists what changes on
+its own, what to check, and what is worth turning on.

package/starter/06-migrating.md

@@ -1,53 +0,0 @@
----
-title: Moving from 0.1 to 0.2
-description: What the 0.2 changes on its own, what to check, and what to turn on.
-tags: [release, migration]
----
-
-# Moving from 0.1 to 0.2
-
-A 0.1 project 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@beta   # while the 0.2 is in beta
-npm install docpensieve@latest # once it is released
-```
-
-Through `npx` alone, `npx docpensieve@beta` runs the beta.
-
-## 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    |
-| `theme.darkMode` | Now read: `'dark'` and `'light'` keep one scheme, `'class'` follows the system |
-
-Content pages still load no script: the search page alone does.
-
-## 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.
-- **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/).