docpensieve 0.4.0-beta.1 → 0.4.0

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.

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

@@ -0,0 +1,160 @@
+---
+title: Languages
+description: Publish the same version in several languages — the folders, the addresses, and what happens to a page nobody translated.
+tags: [guide, languages]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Languages
+
+A version can be published in several languages. Each one is a folder of pages
+of its own, standing beside the version it translates.
+
+## Declaring a translation
+
+```js
+lang: 'en',
+versions: [
+  {
+    slug: 'latest',
+    name: '1.0',
+    folder: 'docs/v1.0',
+    current: true,
+    translations: { fr: 'docs/v1.0-fr' },
+  },
+],
+```
+
+`lang` is the language of the site — the one your pages are written in. Every
+entry of `translations` names a language and the folder holding that
+translation.
+
+```
+docs/
+├── v1.0/          the language of the site
+│   ├── index.md
+│   └── guide/
+└── v1.0-fr/       its French translation
+    ├── index.md
+    └── guide/
+```
+
+## The addresses
+
+The language of the site keeps the addresses it has; a translation is served
+under its code:
+
+| Page              | Address                              |
+| ----------------- | ------------------------------------ |
+| The site language | `/versions/latest/guide/install/`    |
+| Its French twin   | `/versions/latest/fr/guide/install/` |
+
+Nothing already published moves, which is the point: a link shared last year
+still leads where it led. The translation lives **inside** the version, so a
+version is still one folder, one orphan branch, one stylesheet.
+
+## A page nobody translated
+
+It does not exist in that language. It is absent from the menu of that
+language and from the sitemap, no `hreflang` claims it, and the language
+switcher names the language without offering it — a reader learns the site has
+a French version, and is never handed English under a French address.
+
+That is what lets a translation start with five pages. Translate what matters
+first; the rest stays in the language it was written in until someone gets to
+it.
+
+## The words around your pages
+
+The menu, the notices, the search field and the dates follow the language of
+the page. English and French ship with the tool.
+
+A language it does not ship keeps the English wording, and the `ui` field is
+where a project writes its own — or corrects a word:
+
+```js
+lang: 'de',
+ui: {
+  de: { search: 'Suchen', onThisPage: 'Auf dieser Seite' },
+},
+```
+
+Anything left out stays in English rather than empty: half a translation is
+still a readable page. A key that does not exist stops the build, listing those
+that do — a typo there would leave the shipped word in place without a word.
+
+### Counting, in the plurals of the language
+
+One key is not a word but a set of them: `pages`, which follows a number.
+
+```js
+ui: {
+  pl: { pages: { one: 'strona', few: 'strony', many: 'stron', other: 'stron' } },
+},
+```
+
+The categories are those of **CLDR**, the reference the browsers and Node
+carry: English has two — `one` and `other` — French puts zero in the singular,
+Polish has four and Arabic six. The build picks the right one through
+`Intl.PluralRules` rather than comparing the count with one, which is an
+English rule.
+
+Fill `other` at least: it is the category every language has, and it answers
+for the ones a translation leaves out.
+
+## What the language decides by itself
+
+Three things follow from the code alone, with nothing to declare:
+
+| From the language    | What it sets                                         |
+| -------------------- | ---------------------------------------------------- |
+| Writing direction    | `dir="rtl"` on `<html>` for Arabic, Hebrew, Persian… |
+| Plural of a count    | The CLDR categories above                            |
+| The date of a byline | Written in the conventions of that language          |
+
+The codes themselves are **BCP 47** tags — `fr`, `pt-BR`, `zh-Hans` — the
+standard `<html lang>` and `hreflang` expect. A tag that is not one stops the
+build: it would otherwise put in the markup a value no browser or screen reader
+knows how to read.
+
+Search engines also receive `hreflang="x-default"`, pointing at the language
+the pages are written in: it is the address to serve a reader whose own
+language the site does not have.
+
+## What each language has of its own
+
+| Its own                              | Shared with the version           |
+| ------------------------------------ | --------------------------------- |
+| Pages, menu, search page             | The stylesheet                    |
+| Author file and images of its folder | The logo and favicon              |
+| The wording of the shell             | The version notice and its number |
+
+The author file is read in each folder, so a biography can be translated with
+the pages it signs.
+
+## What is refused
+
+Three mistakes stop the build rather than publish something wrong in silence:
+
+| Written                                   | Why it is refused                                               |
+| ----------------------------------------- | --------------------------------------------------------------- |
+| `translations` at the root of the file    | It belongs to a version — a version is what has pages           |
+| `lang` on a version                       | The site has one language; a version carries translations of it |
+| A tag that names no language — `francais` | It would land in the markup as `lang="francais"`                |
+
+The third deserves a word. BCP 47 allows a language subtag of five to eight
+letters, so `francais` is **well formed** — it is simply not a language. Left
+to pass, it would serve English wording under a French address, and nothing
+would say so.
+
+## What to check
+
+- **A translation folder named but missing** stops the build, naming the
+  language rather than the folder alone.
+- **`check` after a translation lands**: a page added on one side and linked
+  from the other is the usual first dead link.
+- Use the same page paths on both sides. A page translated under a different
+  file name is a different page: it has no twin, and the switcher says so.

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

@@ -196,7 +196,7 @@ carrying the caption.
   <Column span={4}>
     <Card className="h-full text-center">
       <CardBody>
-        <div className="text-4xl font-semibold text-indigo-600">9</div>
+        <div className="text-4xl font-semibold text-indigo-600">12</div>
         <div className="text-sm">components</div>
       </CardBody>
       <CardFooter>usable without an import</CardFooter>
@@ -229,7 +229,7 @@ carrying the caption.
   <Column span={4}>
     <Card className="full-height centered">
       <CardBody>
-        <div className="figure">9</div>
+        <div className="figure">12</div>
         <div className="small">components</div>
       </CardBody>
       <CardFooter>usable without an import</CardFooter>

package/starter/02-components/02-columns.mdx

@@ -284,3 +284,6 @@ distributes as it likes; with `Columns`, each block stays where you put it.
 
 Below tablet width, the grid columns stack one under the other. Shrink the
 window to check.
+
+The most frequent row is a row of cards; [Card](./card/) shows how to keep
+them to the same height, which a grid alone does not do.

package/starter/02-components/03-time-timer.mdx

@@ -118,3 +118,7 @@ integration, whose time zone is not yours.
 
 A misspelt duration stops the build, and so does an invalid date. The message
 names the faulty value and recalls the expected format.
+
+Announcing a release is what this is usually for, and [Versions](../guide/versions/)
+covers the rest of that cycle — the banner a prerelease carries on its own,
+and the day the two tracks swap.

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

@@ -82,6 +82,43 @@ The bubble is capped at about sixteen rem wide, then wraps.
 
 See the <Tooltip text="A published version stays in the state in which it was produced. Rebuilding it is never necessary, and nothing would guarantee it gives the same result years later.">reason for version branches</Tooltip> for the details.
 
+## The look through className
+
+A `className` lands on the term, not on the bubble: it is the term the reader
+sees before hovering anything.
+
+<ForTheme framework="tailwind">
+
+A term marked <Tooltip className="text-indigo-500 font-medium" text="It now carries the accent colour, and a heavier weight.">more firmly</Tooltip> than the others.
+
+```mdx
+<Tooltip className="text-indigo-500 font-medium" text="…">
+  more firmly
+</Tooltip>
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
+A term marked <Tooltip className="accent-text" text="It now carries the accent colour of the theme.">more firmly</Tooltip> than the others.
+
+```mdx
+<Tooltip className="accent-text" text="…">
+  more firmly
+</Tooltip>
+```
+
+```css
+/* theme/99-docpensieve.css */
+.accent-text {
+  color: var(--dp-accent);
+}
+```
+
+</ForTheme>
+
+`style` works the same way, for a one-off adjustment that needs no class.
+
 ## What it cannot do
 
 The bubble is positioned absolutely: inside a container that **clips its
@@ -98,3 +135,6 @@ leaves the term.
 
 A `Tooltip` without text stops the build: a hover with no effect goes
 unnoticed for a long time. So does an unknown side.
+
+A tooltip explains a term without leaving the sentence. A remark that needs
+its own space is an [Admonition](./admonition/) instead.

package/starter/02-components/05-tree.mdx

@@ -191,3 +191,7 @@ announcing it would lie about what the page can do.
 A `TreeItem` written outside a `Tree` is refused — it would produce an `<li>`
 outside any list, invalid HTML that no browser reports. An entry without a
 label is refused too.
+
+A tree is how this documentation shows the shape of a project. What those
+folders become once built — the order, the addresses — is in
+[Writing pages](../guide/writing-pages/).

package/starter/02-components/06-scroll-to-top.mdx

@@ -141,3 +141,6 @@ And a less happy side effect, better known in advance: what depends on the
 moment is frozen at build time. A page that shows “the offer ends tomorrow”
 will still say so in six months if the site has not been rebuilt. A scheduled
 build is enough to keep it right.
+
+Setting one up takes a few lines in the pipeline that already builds the
+site: [Deployment](../guide/deployment/) has the recipe.

package/starter/02-components/07-skill.mdx

@@ -157,6 +157,36 @@ every gauge it holds.
 keeps announcing it to screen readers. Hiding a piece of information is not
 deleting it.
 
+## A name that is not a text
+
+`name` accepts more than a string — an icon beside a word, a term carrying a
+tooltip. A screen reader then has nothing to announce, so `label` says in plain
+words what the gauge measures:
+
+<Skill
+  name={
+    <>
+      <LogoIcon src="./icons/shield.svg" /> Coverage
+    </>
+  }
+  label="Test coverage"
+  level={97}
+/>
+
+```mdx
+<Skill
+  name={
+    <>
+      <LogoIcon src="./icons/shield.svg" /> Coverage
+    </>
+  }
+  label="Test coverage"
+  level={97}
+/>
+```
+
+With a plain string in `name`, `label` is not needed: the name already says it.
+
 ## A dashboard
 
 Several gauges in columns, each in its card.

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

@@ -139,6 +139,27 @@ readers — which is right when nearby text already says the same thing. With
 In the list above, the icons have no `label`: the text next to them already
 carries the meaning, and announcing it twice would tell nothing.
 
+## An icon from a set
+
+Beside a file of your project, `src` accepts the name of an icon from a
+collection, written `prefix:name`:
+
+```mdx
+<LogoIcon src="simple-icons:github" label="Repository" />
+```
+
+The set is a package your project installs, and the drawing is placed in the
+page at the build, exactly as a file of yours would be:
+
+```bash
+npm install --save-dev @iconify-json/simple-icons
+```
+
+Nothing is fetched while the page is read — those collections offer an online
+service, which would mean a request for every icon and a script to make it.
+A set that is not installed stops the build and names the package to install;
+so does a name the set does not hold.
+
 ## What it refuses
 
 A missing file, a file without an `svg` tag, a target leaving the version
@@ -147,3 +168,6 @@ would otherwise leave an empty box that nobody notices.
 
 The scripts and event handlers present in a file are removed before inlining.
 A component loads no JavaScript, and this one is not going to introduce any.
+
+A kind of admonition takes its mark through this same component — see
+[Admonition](./admonition/).

package/starter/02-components/09-for-theme.mdx

@@ -43,3 +43,6 @@ This site is built with the **custom** theme.
 A `framework` other than `tailwind` or `custom` stops the build, with the
 accepted values: a typo would otherwise hide the content under every theme,
 without a word.
+
+Which theme a project runs is one field of its configuration, and the whole
+of what it changes is in [Themes](../guide/themes/).

package/starter/02-components/11-menu.mdx

@@ -0,0 +1,129 @@
+---
+title: Menu
+description: A menu of links placed anywhere in a page, folded behind a button on a narrow screen.
+---
+
+# Menu
+
+The header carries the navigation of the site, and the sidebar that of the
+documentation. This menu belongs to a **page**: the links a section offers
+where it stands — a summary at the top of a landing page, the chapters of a
+guide, the entries of a portal.
+
+## A row of links
+
+<Menu label="Guide">
+  <MenuLink href="../guide/installation/">Installation</MenuLink>
+  <MenuLink href="../guide/first-site/">First site</MenuLink>
+  <MenuLink href="../guide/writing-pages/">Writing pages</MenuLink>
+</Menu>
+
+```mdx
+<Menu label="Guide">
+  <MenuLink href="../guide/installation/">Installation</MenuLink>
+  <MenuLink href="../guide/first-site/">First site</MenuLink>
+</Menu>
+```
+
+A target resolves as anywhere else: relative to the page, or absolute from the
+version root. `label` names the menu for screen readers, and labels the button
+it folds into.
+
+## Groups
+
+An entry may open a group rather than lead somewhere:
+
+<Menu label="Sections">
+  <MenuLink href="../guide/">Guide</MenuLink>
+  <MenuGroup title="Reference">
+    <MenuLink href="../reference/cli/">Commands</MenuLink>
+    <MenuLink href="../reference/configuration/">Configuration</MenuLink>
+    <MenuLink href="../reference/frontmatter/">Frontmatter</MenuLink>
+  </MenuGroup>
+  <MenuLink href="../components/">Components</MenuLink>
+</Menu>
+
+```mdx
+<MenuGroup title="Reference">
+  <MenuLink href="../reference/cli/">Commands</MenuLink>
+</MenuGroup>
+```
+
+In the row the group opens as a panel below its title. Once the menu is folded,
+it unfolds in place instead: on a narrow screen a panel would open off screen.
+
+## On a narrow screen
+
+Below 40rem the row gives way to a button carrying the `label`. Everything is
+written once and rendered twice — a row and a fold — of which the stylesheet
+shows one.
+
+That costs a little markup, and buys a menu that works with JavaScript turned
+off: the button is a native element. The lighter alternative relies on a recent
+CSS pseudo-element, and where the browser does not know it, the links vanish
+altogether.
+
+**Narrow this window** to see the row become a button.
+
+## Styling
+
+The menu takes the palette of the active theme through the `--dp-*` tokens.
+What it does not decide is how far it stands from the text, or whether it sits
+in a box — that is set at use.
+
+<ForTheme framework="tailwind">
+
+A `className` holds utilities:
+
+<Menu className="rounded-lg border border-slate-200 p-3 dark:border-slate-800" label="Boxed">
+  <MenuLink href="../guide/">Guide</MenuLink>
+  <MenuLink href="../reference/">Reference</MenuLink>
+</Menu>
+
+```mdx
+<Menu className="rounded-lg border border-slate-200 p-3 dark:border-slate-800">
+  <MenuLink href="../guide/">Guide</MenuLink>
+</Menu>
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
+A `className` names a class of your own, written in the `theme/` folder:
+
+<Menu className="menu-boxed" label="Boxed">
+  <MenuLink href="../guide/">Guide</MenuLink>
+  <MenuLink href="../reference/">Reference</MenuLink>
+</Menu>
+
+```mdx
+<Menu className="menu-boxed">
+  <MenuLink href="../guide/">Guide</MenuLink>
+</Menu>
+```
+
+```css
+/* theme/99-docpensieve.css */
+.menu-boxed {
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--dp-border);
+  border-radius: var(--dp-radius);
+  background: var(--dp-bg-soft);
+}
+```
+
+</ForTheme>
+
+A one-off adjustment needs no class at all: `style` understands the tokens
+under both themes.
+
+```mdx
+<Menu style={{ marginBlock: '2.5rem' }}>…</Menu>
+```
+
+## What it refuses
+
+A `MenuLink` or a `MenuGroup` written outside a `Menu` stops the build, and so
+does an entry without a target or a group without a title. Each of these would
+otherwise render something that looks like a menu and leads nowhere — the kind
+of fault a review does not catch.