docpensieve 0.4.0-beta.2 → 0.5.0-beta.1

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.2",
+  "version": "0.5.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.4.0-beta.2",
-    "@docpensieve/core": "0.4.0-beta.2",
-    "@docpensieve/shared": "0.4.0-beta.2",
-    "@docpensieve/theme": "0.4.0-beta.2",
+    "@docpensieve/components": "0.5.0-beta.1",
+    "@docpensieve/core": "0.5.0-beta.1",
+    "@docpensieve/shared": "0.5.0-beta.1",
+    "@docpensieve/theme": "0.5.0-beta.1",
     "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`)} },`,
     '    },',
     '  ],',
     '',
@@ -288,6 +290,16 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  // 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,',
@@ -295,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,7 +99,7 @@ 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
+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.
 

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-to-beta.md

@@ -1,13 +1,17 @@
 ---
 title: Migrate from latest to beta
-description: Move a project from the latest version, the 0.3, to the 0.4 beta — what changes on its own, and what to check.
+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.3 — builds with the 0.4 beta as it is:
-every new field is optional.
+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
 
@@ -18,10 +22,20 @@ 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.4 has just opened. Each change is listed here as it lands,
-beside what it asks of a project already built on the 0.3.
+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
 
-One thing changes on its own: on a narrow screen, the menu of the documentation
-now folds above the content instead of standing open. Nothing to configure.
+- **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/08-navigation.mdx

@@ -17,6 +17,18 @@ 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

package/starter/01-guide/09-when-it-breaks.md

@@ -0,0 +1,176 @@
+---
+title: When it breaks
+description: The failures this tool actually produces, what causes each one, and the fix — by the symptom you see.
+tags: [guide, troubleshooting]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# When it breaks
+
+Every expected error carries a message **and a hint** saying what is expected
+instead, and the command exits with code 1 without a stack trace. The failures
+below are the ones that say nothing, or say it somewhere you were not looking:
+the site builds, the suite is green, and something is still wrong.
+
+Each heading is the symptom as you would describe it.
+
+## `init` asked me nothing and built a site I did not choose
+
+The dialogue needs a real terminal. Run from a script, a pipeline or through a
+pipe, `init` takes the options given on the command line and the defaults for
+everything else — it announces this before starting, unless `--yes` says you
+meant it.
+
+Pass what matters explicitly:
+
+```bash
+npx docpensieve init my-site --name "Acme docs" --theme custom --site-url https://acme.example.com
+```
+
+## `npx` runs a version older than the one I just published
+
+A freshly published version takes a few minutes to reach every mirror of the
+registry, and `npx` keeps what it already has. During those minutes,
+installing can even fail outright with `ETARGET`, because the packages pin each
+other to the exact same version and one of the five is not there yet.
+
+```bash
+npx --prefer-online docpensieve@latest init my-site
+```
+
+Wait rather than republish: a version number burned is not recoverable, and
+nothing is wrong with the one being propagated.
+
+## The site works on my machine and every link is dead online
+
+The site is served from a subfolder and `baseUrl` was not set. Locally,
+`serve` and `dev` answer at the root, so nothing shows.
+
+```js
+siteUrl: 'https://acme.example.com/docs',
+baseUrl: '/docs/',
+```
+
+`baseUrl` prefixes every internal link. Without it, a link written
+`/guide/installation/` points one level above the site.
+
+## `check` says a link "ignores the deployment prefix"
+
+The file exists, but the link was written without the prefix — it will lead
+nowhere once online, and hitting it locally hides that.
+
+```
+  index.html
+    /guide/installation/
+    → ignores the deployment prefix "/docs/"
+```
+
+Write the link the way the documentation does — relative to the page
+(`../components/card/`) or from the root of the version (`/components/card/`,
+which the build rewrites) — rather than typing the deployed path by hand.
+
+## My page does not appear anywhere
+
+Three causes, in the order worth checking:
+
+- **`draft: true`** in its frontmatter keeps it out of the output, on purpose.
+- **The file is outside a version folder.** Only what lives under a `folder`
+  declared in `versions` is read.
+- **The extension.** `.md` and `.mdx` are read; nothing else is.
+
+The build says nothing in these three cases, because none of them is an error:
+a folder you did not declare is simply not documentation.
+
+## A colour I set in `tokens` changes nothing
+
+`theme.tokens` sets the **light** palette. A site carrying
+`theme.darkMode: 'dark'` is always dark, so it never shows those values — the
+dark ones come from the theme's stylesheet.
+
+Redefine them in the `theme/` folder, for both ways of being dark:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) {
+    --dp-accent: #a78bfa;
+  }
+}
+
+:root.dark {
+  --dp-accent: #a78bfa;
+}
+```
+
+## Node warns at every build, or refuses the configuration
+
+A `.js` configuration file is read as a module only when the nearest
+`package.json` says `"type": "module"` — and the one `npm init -y` writes says
+the opposite, which makes Node refuse the file outright.
+
+Name it `docpensieve.config.mjs`. The extension settles it whatever the
+`package.json` says.
+
+The build also stops when **both** files are present:
+
+```
+Two configuration files in /path/to/project: docpensieve.config.mjs and docpensieve.config.js.
+```
+
+Keep one. Guessing which you meant would sooner or later publish a site built
+from the wrong settings.
+
+## A component stops the build, or renders nothing
+
+The components that need a parent check for it: a `Column` outside `Columns`,
+a `MenuLink` outside a `Menu` stop the build rather than render an element
+with no effect. That is deliberate — a tag that quietly does nothing survives
+review, an error does not.
+
+`globalComponents: false` removes the shipped components from every page. A
+page still using one then stops the build, naming it:
+
+```
+Error Unknown component "Cards" in docs/v1.0/99-docpensieve/01-guide/index.mdx.
+No global component is registered for this compilation.
+```
+
+Either turn them back on, or remove the installed documentation with the
+components it uses — `--minimal` at `init` leaves it out from the start.
+
+A `.md` page using a component works, but its extension no longer says what the
+page does. Rename it `.mdx`; the two compile identically.
+
+## A utility class in a page has no effect
+
+Under the `tailwind` theme, the stylesheet is compiled from the classes found
+in the **rendered** pages. A class whose name does not survive being written
+into HTML is never emitted, and nothing reports it — an `&` becomes `&`,
+so `[&_.x]:underline` produces no rule.
+
+Pass through a variable of the component instead:
+
+```mdx
+<Skill name="Coverage" level={97} color="#10b981" />
+```
+
+## Nothing above matches
+
+Run the two commands that look at different things, in this order:
+
+```bash
+npx docpensieve build
+npx docpensieve check
+```
+
+The build compiles pages and stops on what it cannot do. `check` reads the
+produced site back and follows its links — a renamed page compiles perfectly
+and leaves every link to it dead.
+
+An unexpected failure — one without a hint — comes out with its stack trace,
+and is worth reporting with the version printed by `npx docpensieve --version`.
+
+Each message comes from a command, and the [CLI reference](../reference/cli/)
+lists what each one does, with the exit codes a pipeline reads.