docpensieve 0.4.0-beta.1 → 0.4.0

package/bin/docpensieve.js

@@ -8,7 +8,7 @@
 
 import { createRequire } from 'node:module';
 
-import { DocPensieveError, NotImplementedError } from '@docpensieve/shared';
+import { DOCUMENTATION_URL, DocPensieveError, NotImplementedError } from '@docpensieve/shared';
 import { Command } from 'commander';
 import chalk from 'chalk';
 
@@ -21,7 +21,10 @@ const program = new Command();
 program
   .name('docpensieve')
   .description('Static documentation site generator')
-  .version(version, '-v, --version');
+  .version(version, '-v, --version')
+  // Someone typing --help is usually stuck: the list of commands alone sends
+  // them back where they started.
+  .addHelpText('after', `\nDocumentation: ${DOCUMENTATION_URL}`);
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.0",
   "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-beta.1",
-    "@docpensieve/core": "0.4.0-beta.1",
-    "@docpensieve/shared": "0.4.0-beta.1",
-    "@docpensieve/theme": "0.4.0-beta.1",
+    "@docpensieve/components": "0.4.0",
+    "@docpensieve/core": "0.4.0",
+    "@docpensieve/shared": "0.4.0",
+    "@docpensieve/theme": "0.4.0",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/src/commands/build.js

@@ -6,7 +6,12 @@
 
 import path from 'node:path';
 
-import { componentsCss, createRegistry, setSiteContext } from '@docpensieve/components';
+import {
+  componentsCss,
+  createRegistry,
+  setSiteContext,
+  setAdmonitionKinds,
+} from '@docpensieve/components';
 import { SiteGenerator, loadConfig, resolveVersion } from '@docpensieve/core';
 
 import { createTheme } from '../theme.js';
@@ -21,6 +26,9 @@ export async function build(versionSlug, options = {}) {
   const config = await loadConfig(cwd);
   const outDir = path.resolve(cwd, options.out ?? config.outDir);
 
+  // The kinds a project declares, beside the ones shipped.
+  setAdmonitionKinds(config.admonitions);
+
   const generator = new SiteGenerator(config, {
     // `globalComponents: false` removes the shipped components: a project that
     // defines its own thus avoids a name collision. The option was declared

package/src/commands/dev.js

@@ -7,7 +7,12 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
-import { componentsCss, createRegistry, setSiteContext } from '@docpensieve/components';
+import {
+  componentsCss,
+  createRegistry,
+  setSiteContext,
+  setAdmonitionKinds,
+} from '@docpensieve/components';
 import { SiteGenerator, loadConfig } from '@docpensieve/core';
 import { CONFIG_FILENAME, DocPensieveError, THEME_FOLDER } from '@docpensieve/shared';
 import chokidar from 'chokidar';
@@ -54,6 +59,9 @@ export async function dev(options = {}) {
     // The configuration is read again every time: changing it must show
     // without restarting the command.
     const current = await loadConfig(cwd);
+    // Read again with the rest: a kind added to the configuration must show
+    // without restarting the command.
+    setAdmonitionKinds(current.admonitions);
     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

package/src/commands/init.js

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import {
   CONFIG_FILENAME,
   CONFIG_FILENAMES,
+  DOCUMENTATION_URL,
   DocPensieveError,
   THEME_FOLDER,
   THEME_FRAMEWORKS,
@@ -64,9 +65,6 @@ const NOT_INSTALLED = new Set([
 /** Starting point of the project's own stylesheet, under the custom theme. */
 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://docpensieve.com/';
-
 /**
  * Asks a question, with a default value shown between brackets.
  *
@@ -228,12 +226,16 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  //   current     the version the site root leads to — at most one',
     '  //   prerelease  in preparation: a banner on every page, kept out of search',
     '  //   archived    no longer maintained: a banner, still indexed',
+    '  //   translations  a folder per language, served under its code',
     '  versions: [',
     '    {',
     `      slug: ${quote(slug)}, // URL segment, and name of the version's branch`,
     `      name: ${quote(version)}, // label in the version switcher`,
     `      folder: ${quote(`docs/${slug}`)},`,
     '      current: true,',
+    '      // Pages of this version in another language, served under /fr/.',
+    '      // Your own language stays where it is, and keeps its addresses.',
+    `      // translations: { fr: ${quote(`docs/${slug}-fr`)} },`,
     '    },',
     '  ],',
     '',
@@ -284,6 +286,20 @@ function renderConfig({ name, theme, siteUrl, version }) {
     "  // on a narrow screen. For instance [{ label: 'Blog', href: '/blog/' }].",
     '  headerLinks: [],',
     '',
+    '  // Categories of the menu fold, opened on the branch of the page being',
+    '  // read. Useful once the documentation is long.',
+    '  foldedSidebar: false,',
+    '',
+    '  // Wording of the shell — the menu, the notices, the search field.',
+    '  // English and French ship with the tool and follow `lang`; this field',
+    "  // corrects a word or adds a language: { de: { search: 'Suchen' } }.",
+    '  ui: {},',
+    '',
+    '  // Kinds of admonition, beside the six shipped — note, info, tip,',
+    '  // attention, alert and danger. A kind is a label and a tone, which',
+    "  // carries its colour: { review: { label: 'Review', tone: 'info' } }.",
+    '  admonitions: {},',
+    '',
     '  // The shipped components — Card, Columns, Tooltip… — usable in any .mdx',
     '  // page without an import. false removes them, to use your own names.',
     '  globalComponents: true,',
@@ -291,6 +307,10 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  // Back-to-top button on every page.',
     '  scrollToTop: true,',
     '',
+    '  // 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,',
+    '',
     '  // Structured data (JSON-LD) generated from the frontmatter of each page.',
     '  jsonld: { enabled: true },',
     '',

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

@@ -99,9 +99,8 @@ 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 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.
+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.
 
 ## Checking
 

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

@@ -72,6 +72,11 @@ actually used in order to emit only those.
 **The `versions.json` at the root** describes the available versions. It is
 what lets versions built long ago stay online without ever rebuilding them.
 
+The folder itself is `dist/`, which `outDir` changes — to `public/`, or to
+whatever your host expects. The build empties the folders it writes and leaves
+the rest of that folder alone, so an output folder shared with something else
+keeps what is not its own.
+
 ## Reading the output back
 
 A successful build says nothing of a dead link: nothing in the chain looks at
@@ -94,7 +99,8 @@ online.
 ```
 
 It is the check to run after any change of `baseUrl`, of folder structure or of
-URL.
+URL. When something does not add up, [When it breaks](./when-it-breaks/) lists
+the failures this tool produces, by the symptom you see.
 
 ## Searching the site
 

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

@@ -197,6 +197,10 @@ In an `.mdx` page, the shipped components are used **without an import**:
 They are rendered at build time: the delivered HTML only holds their result.
 The list is in [Components](../components/).
 
+`globalComponents: false` removes them from every page. It is meant for a
+project that would rather bring its own: a page still using one then stops the
+build, naming it.
+
 ## A trap to know
 
 The content of a JSX tag **left alone on its own line** becomes a paragraph:

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

@@ -199,3 +199,7 @@ today's generator or today's sources. Rebuilding it is never necessary, and
 nothing would guarantee it gives the same result.
 
 The sources stay on the working branch. The two never mix.
+
+What the day of a release looks like from the outside — the addresses, the
+pipeline, the check that stops a bad publication — is in
+[Deployment](./deployment/).

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

@@ -26,12 +26,43 @@ styles the site, with no styling dependency.
 The templates are the same in both cases. Switching values requires touching
 no page.
 
+## The images of the site
+
+Three images carry the identity of a project, and none of them is a stylesheet
+matter — they are declared once, from the root of the project:
+
+```js
+logo: 'branding/logo.png',
+favicon: 'branding/favicon.png',
+socialImage: 'branding/social.jpg',
+```
+
+| Field         | Where it shows                 | What to give it                                                                       |
+| ------------- | ------------------------------ | ------------------------------------------------------------------------------------- |
+| `logo`        | In the header, beside the name | Any web image. A detailed logo reads badly at header size: crop the mark alone        |
+| `favicon`     | In the browser tab             | `.ico`, `.png` or `.svg` — nothing else is shown by browsers                          |
+| `socialImage` | The preview of a shared link   | A PNG or JPEG, 1200 × 630 pixels as a rule. Social networks read neither SVG nor AVIF |
+
+A version may carry its own `logo` and `favicon`, which is how a beta tells
+itself apart at a glance in the tab.
+
+`socialImage` needs `siteUrl`, and the build refuses the pair when it is
+missing rather than publish a preview nobody can fetch:
+
+```
+socialImage needs siteUrl.
+Social networks only read an absolute address: set siteUrl, the public address of the site.
+```
+
+A preview is fetched by another machine, from the outside: a path that works in
+your browser means nothing to it.
+
 ## The principle: slots, not classes
 
 The templates **hard-code no class**. They ask the theme for the class of each
 slot — the header, the menu, a navigation link — and the theme answers.
 
-The twenty-four slots are listed in the [reference](../reference/theme/).
+The fifty slots are listed in the [reference](../reference/theme/).
 
 That is what lets a utility styling and a classic styling share the same HTML:
 one answers `dp-nav-link`, the other a handful of utilities. The template
@@ -43,7 +74,7 @@ they therefore follow the active palette without knowing anything about it.
 
 ## Changing the colours
 
-The fifteen tokens are listed in the [reference](../reference/theme/). They are
+The tokens are listed in the [reference](../reference/theme/). They are
 redefined from the configuration:
 
 ```js
@@ -56,19 +87,22 @@ theme: {
 },
 ```
 
-| Token                                  | What it sets                                                   |
-| -------------------------------------- | -------------------------------------------------------------- |
-| `--dp-bg`, `--dp-bg-soft`              | Backgrounds                                                    |
-| `--dp-text`, `--dp-text-soft`          | Text                                                           |
-| `--dp-border`, `--dp-rule`             | Borders and rules                                              |
-| `--dp-accent`, `--dp-accent-soft`      | Accent colour                                                  |
-| `--dp-radius`                          | Corner rounding                                                |
-| `--dp-font`, `--dp-font-mono`          | Font families                                                  |
-| `--dp-content-width`                   | Reading width. `none` by default: the content fills its column |
-| `--dp-sidebar-width`, `--dp-toc-width` | Side columns                                                   |
+| Token                                                           | What it sets                                                   |
+| --------------------------------------------------------------- | -------------------------------------------------------------- |
+| `--dp-bg`, `--dp-bg-soft`                                       | Backgrounds                                                    |
+| `--dp-text`, `--dp-text-soft`                                   | Text                                                           |
+| `--dp-border`, `--dp-rule`                                      | Borders and rules                                              |
+| `--dp-accent`, `--dp-accent-soft`                               | Accent colour                                                  |
+| `--dp-tip`, `--dp-attention`, `--dp-danger` (and their `-soft`) | Tones of the blocks set apart from the text                    |
+| `--dp-radius`                                                   | Corner rounding                                                |
+| `--dp-font`, `--dp-font-mono`                                   | Font families                                                  |
+| `--dp-content-width`                                            | Reading width. `none` by default: the content fills its column |
+| `--dp-sidebar-width`, `--dp-toc-width`                          | Side columns                                                   |
 
 A redefined token propagates everywhere: components included, without any of
-them having to know.
+them having to know. It sets the **light** palette; the dark one is a set of
+tokens of its own, redefined in the `theme/` folder — see below. A site held
+dark by `darkMode: 'dark'` therefore shows nothing of a token set here.
 
 ## Adding CSS
 

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

@@ -0,0 +1,125 @@
+---
+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.

package/starter/01-guide/08-navigation.mdx

@@ -0,0 +1,138 @@
+---
+title: Navigation
+description: The menu of the documentation, the links of the header, and what becomes of both on a phone.
+tags: [guide, navigation]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Navigation
+
+A reader finds a page in one of two ways: the menu of the documentation, on the
+left, or the header, at the top. They answer different questions — _where am I
+in this documentation_ and _where else can I go_ — and a site may use one, the
+other, or both.
+
+Neither loads a script. Everything here folds and unfolds with native elements.
+
+## The header, held or not
+
+The header stays at the top of the screen. To let it scroll away with the page:
+
+```js
+stickyHeader: false,
+```
+
+Held, it keeps the search field and the version switcher within reach. Let go,
+it gives back its height — a third of a phone screen — and anchors stop
+reserving room for it.
+
+## The menu of the documentation
+
+It follows the file tree, or the file you describe — that is
+[Writing the menu by hand](./writing-pages/). What changes here is how much of
+it shows at once.
+
+### Folding the categories
+
+```js
+// docpensieve.config.mjs
+foldedSidebar: true,
+```
+
+Every category becomes a fold. **The branch holding the page being read is
+open, the others closed**, so a menu of a hundred entries stops asking the
+reader to scroll past what does not concern them.
+
+<Columns>
+  <Column span={6}>
+    <Card style={{ height: '100%' }}>
+      <CardHeader>Unfolded — the default</CardHeader>
+      <CardBody>
+        Everything is visible at once. Right for a documentation of a few dozen pages, where
+        scrolling the menu costs nothing.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card style={{ height: '100%', borderColor: 'var(--dp-accent)' }}>
+      <CardHeader>Folded</CardHeader>
+      <CardBody>
+        Only the branch being read is open. Right once the menu is long enough that its end is out
+        of sight.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+A category that is also a page gains that page as its first entry. The handle
+of a fold cannot be a link as well — a click would mean two things, and the
+page would become unreachable.
+
+## The header
+
+`headerLinks` puts links beside the version switcher.
+
+```js
+headerLinks: [{ label: 'Blog', href: '/blog/' }],
+```
+
+A target starts from the root of a version — `/blog/` — or is a full address. A
+relative target is refused: the header is on every page, and `blog/` would mean
+something else on each.
+
+### A section that lives in one version
+
+A link may name the version it leads to:
+
+```js
+{ label: 'Examples', href: '/examples/', version: 'latest' },
+```
+
+Every version then leads there, which is what keeps a section written in one
+version reachable from all of them. This site does exactly that for its
+examples.
+
+### A panel of links
+
+An entry carrying `columns` opens a panel instead of leading anywhere:
+
+```js
+{
+  label: 'Product',
+  columns: [
+    {
+      title: 'Guide',
+      items: [
+        { label: 'Installation', href: '/guide/installation/' },
+        { label: 'First site', href: '/guide/first-site/' },
+      ],
+    },
+    { items: [{ label: 'Repository', href: 'https://github.com/me/my-project' }] },
+  ],
+}
+```
+
+A column may go without a title. An entry cannot carry both `href` and
+`columns`: it either leads somewhere or opens a panel.
+
+The panel is declared here, **not derived from the menu of the documentation**.
+The two are therefore free to show different things — or a site without a
+sidebar can navigate from the header alone.
+
+## On a phone
+
+Nothing is left to overflow off the screen.
+
+| What                                   | Below 48rem                          | Below 56rem                                     |
+| -------------------------------------- | ------------------------------------ | ----------------------------------------------- |
+| Version switcher, links, panel, search | Behind the menu button of the header | —                                               |
+| Menu of the documentation              | —                                    | Folded above the content, behind its own button |
+
+The panel of links unfolds inside the header menu rather than over it, and the
+documentation menu starts closed: open, it would fill the first screen before a
+word is read.
+
+Both buttons are native elements. With JavaScript turned off, they still open.