docpensieve 0.1.0 → 0.1.2

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

@@ -0,0 +1,138 @@
+---
+title: Writing pages
+description: Frontmatter, URLs, menu order, links and images.
+tags: [guide, content]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Writing pages
+
+A page is a `.md` or `.mdx` file in the version folder. Both go through the
+same chain: the extension does not change what is possible, it only states the
+intent.
+
+## The frontmatter
+
+```yaml
+---
+title: Installation
+description: What you need, and how to set up a project.
+date: 2026-09-09
+tags: [guide, installation]
+---
+```
+
+`title` becomes the `<title>` tag, the menu entry and the breadcrumb.
+`description` feeds the metadata and the JSON-LD. Everything is optional:
+without `title`, the project name stands in.
+
+The fields are detailed in the [reference](../reference/frontmatter/).
+
+## What the URL depends on
+
+The file path gives the URL path, stripped of its extension and of its sorting
+prefix:
+
+| File                        | URL                    |
+| --------------------------- | ---------------------- |
+| `index.md`                  | `/`                    |
+| `guide/01-installation.md`  | `/guide/installation/` |
+| `guide/index.md`            | `/guide/`              |
+| `components/02-columns.mdx` | `/components/columns/` |
+
+The `01-` prefix **orders the menu without appearing in the URL**. It is the
+only way to sort pages other than alphabetically, and it saves keeping a
+separate list.
+
+## The menu order
+
+The menu is derived from the file tree. Folders become sections, numeric
+prefixes give the order, and an `index.md` in a folder provides the title of
+the section.
+
+```
+docs/v1.0/
+├── index.mdx           →  /
+├── guide/
+│   ├── index.md        →  /guide/        (title of the section)
+│   ├── 01-installation.md
+│   └── 02-first-site.md
+└── components/
+    ├── index.md
+    └── 01-card.mdx
+```
+
+## Internal links
+
+Two spellings, two meanings:
+
+- **relative** — `./sibling/`, `../guide/` — resolves against the folder of the
+  page's file, as between any two files;
+- **absolute** — `/guide/installation/` — starts from the **version root**, not
+  from the domain root.
+
+The second rule deserves a pause. A documentation does not know it may be
+served under `/my-project/versions/v1.0/`: if `/guide/installation/` were taken
+literally, every internal link would break as soon as a prefix comes into play.
+They are therefore rewritten at build time.
+
+To target a real domain URL, the full address remains.
+
+## Images
+
+An image sits next to the page and is written relatively:
+
+```md
+![Pipeline diagram](./diagram.png)
+```
+
+Files that are not pages are copied as is into the output, at the same
+relative place. The path is rewritten like a link.
+
+## Components
+
+In an `.mdx` page, the shipped components are used **without an import**:
+
+```mdx
+<Columns>
+  <Column span={8}>The bulk of the point</Column>
+  <Column span={4}>A side remark</Column>
+</Columns>
+```
+
+They are rendered at build time: the delivered HTML only holds their result.
+The list is in [Components](../components/).
+
+## A trap to know
+
+The content of a JSX tag **left alone on its own line** becomes a paragraph:
+
+```mdx
+<p className="flex gap-3">Some text</p>
+```
+
+produces `<p class="flex gap-3"><p>Some text</p></p>` — two nested paragraphs,
+which is invalid. The browser closes the first one by itself: the wrapper
+disappears, and the intended layout with it.
+
+The formatter makes the trap sneaky. A long string of classes ends up broken
+over several lines, which leaves the text alone on its line **after the fact**,
+without anyone having written it that way.
+
+Three ways to guard against it:
+
+- prefer `<div>` to `<p>` as a wrapper — a paragraph is valid inside it;
+- write short content on the same line as its tags;
+- for repeated cases, put a class in `theme.css` rather than a long string of
+  utilities, so that the line stays short.
+
+`docpensieve check` reports these nestings on the produced site.
+
+## What is not published
+
+A page whose frontmatter carries `draft: true` is loaded but kept out of the
+output. That is what lets a work-in-progress page stay in the repository
+without being published.

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

@@ -0,0 +1,179 @@
+---
+title: Versions
+description: Keep the current version and the one being prepared side by side.
+tags: [guide, versions]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Versions
+
+A version is a **source folder** and a **configuration entry**. Nothing else.
+Everything else — URL, menu, switcher, branch — follows from them.
+
+## The two-track model
+
+It is the most common arrangement, and the one DocPensieve's own documentation uses:
+
+| Version     | Role                                        | Who sees it          |
+| ----------- | ------------------------------------------- | -------------------- |
+| **current** | the one that is online and being fixed      | everyone, by default |
+| **beta**    | the one being prepared for the next release | those who pick it    |
+
+A visitor arriving at the root is sent to the **current** one. The beta exists,
+it is reachable, but nobody lands there by chance.
+
+## 1. Declaring the versions
+
+In `docpensieve.config.mjs`:
+
+```js
+versions: [
+  { slug: 'v1.1-beta', name: '1.1 (beta)', folder: 'docs/v1.1-beta', prerelease: true },
+  { slug: 'v1.0', name: '1.0', folder: 'docs/v1.0', current: true },
+],
+```
+
+| Field        | Role                                                          |
+| ------------ | ------------------------------------------------------------- |
+| `slug`       | URL and branch identifier. It shows up in `/versions/<slug>/` |
+| `name`       | What the visitor reads in the switcher                        |
+| `folder`     | Source folder, relative to the project root                   |
+| `current`    | The version served by default. **At most one**                |
+| `archived`   | Version kept but no longer receiving fixes                    |
+| `prerelease` | Version in preparation, not yet the current one               |
+
+Two rules to remember:
+
+- **only one version can carry `current`** — two stop the build;
+- if **none** carries it, the first in the list becomes current. A
+  single-version configuration therefore has nothing to specify.
+
+The switcher only appears in the header from **two** versions on: a single
+choice is not a choice.
+
+## 2. Opening the beta
+
+Start from the current version, and give it its own folder:
+
+```bash
+cp -r docs/v1.0 docs/v1.1-beta
+```
+
+Then declare the entry with `prerelease` — and **without** `current`, which the
+current version keeps:
+
+```js
+versions: [
+  { slug: 'v1.1-beta', name: '1.1 (beta)', folder: 'docs/v1.1-beta', prerelease: true },
+  { slug: 'v1.0', name: '1.0', folder: 'docs/v1.0', current: true },
+],
+```
+
+`prerelease` is not just a label. It puts on **every page** of the version a
+banner pointing to the current one, and a
+`<meta name="robots" content="noindex, follow">` in the head.
+
+This second point matters more than it seems. A beta is a near-identical copy
+of the current version: without it, both compete for the same place in search
+engines, and it is often the wrong one that comes up. Someone would then read a
+documentation in progress while believing they read the one that counts.
+`follow` still lets the page's links be followed.
+
+A version cannot be both `current` and `prerelease`: the build stops. The
+notice of one would contradict the role of the other.
+
+```bash
+npx docpensieve build
+npx docpensieve serve
+```
+
+The switcher now offers both. The root still leads to `1.0`.
+
+From there, the two folders live their own lives: what you write in
+`docs/v1.1-beta` does not touch the online documentation.
+
+### A fix that applies to both
+
+Fixing a typo in the current version does not fix it in the beta: they are two
+separate folders. It is the price of frozen versions, and it is paid at every
+fix — carrying it over into both folders is part of the work.
+
+## 3. Promoting the beta
+
+On release day, the beta becomes the current version. Only one thing changes:
+**where `current` sits**.
+
+```js
+versions: [
+  { slug: 'v1.1', name: '1.1', folder: 'docs/v1.1', current: true },
+  { slug: 'v1.0', name: '1.0', folder: 'docs/v1.0', archived: true },
+],
+```
+
+In practice, three steps:
+
+1. rename the `docs/v1.1-beta` folder to `docs/v1.1`;
+2. in the configuration, change the `slug`, the `name`, the `folder`, and move
+   `current`;
+3. remove `prerelease` from the new one, and mark the old one `archived`.
+
+```bash
+npx docpensieve build
+```
+
+`archived` says the version will no longer receive fixes. It **stays online**:
+it is not a shutdown, it is information. Its pages also carry a banner pointing
+to the current version, but **stay indexed** — a past version still matters to
+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,
+> keep the same slug from start to finish — `v1.1` from the start, with only
+> the label mentioning the beta.
+
+## What the build produces
+
+```
+dist/
+├── index.html          redirect to the current version
+├── versions.json       the list, for whoever wants to read it
+└── versions/
+    ├── v1.1-beta/
+    └── v1.0/
+```
+
+The root is an **HTML redirect**, not a server rule: the output stays
+publishable on any static host, without configuration.
+
+`versions.json` describes each version — its slug, its label, its URL, whether
+it is current, whether it is archived.
+
+## Building a single version
+
+```bash
+npx docpensieve build v1.1-beta
+```
+
+Only this version is written, in `versions/v1.1-beta/`. The others are not
+touched — handy when working on the beta without wanting to rebuild the rest.
+
+One caveat: this form writes **neither the manifest nor the root redirect**,
+which concern no version in particular. After adding, renaming or removing a
+version, run a full build.
+
+## One branch per version
+
+The model goes further than the folder: each compiled version can live on its
+**own orphan branch**, named after its slug, with a history separate from that
+of the sources.
+
+The point is not storage, it is time. A version published two years ago stays
+what it was, in the state in which it was produced — without depending on
+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.

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

@@ -0,0 +1,116 @@
+---
+title: Themes
+description: Style the site, and change the classes without touching the HTML.
+tags: [guide, theme]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Themes
+
+## Two stylings
+
+```js
+theme: {
+  framework: 'tailwind',
+  darkMode: 'class',
+},
+```
+
+`tailwind` compiles on demand only the classes actually used in the produced
+pages. `custom` does without it entirely: a stylesheet written in the package
+styles the site, with no styling dependency.
+
+The templates are the same in both cases. Switching values requires touching
+no page.
+
+## 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/).
+
+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
+itself does not change.
+
+Components follow the same rule. When the theme does not answer, they fall
+back on a `dp-*` class that their stylesheet styles from the `--dp-*` tokens:
+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
+redefined from the configuration:
+
+```js
+theme: {
+  framework: 'tailwind',
+  tokens: {
+    '--dp-accent': 'oklch(55% 0.2 250)',
+    '--dp-radius': '0.75rem',
+  },
+},
+```
+
+| 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                                                   |
+
+A redefined token propagates everywhere: components included, without any of
+them having to know.
+
+## Adding CSS
+
+```js
+theme: {
+  framework: 'tailwind',
+  css: '.dp-article h2 { letter-spacing: -0.01em; }',
+},
+```
+
+The content of `css` is appended to the produced stylesheet.
+
+## Layer order
+
+Under the `tailwind` theme, the stylesheet declares its layers in this order:
+
+```css
+@layer theme, base, components, utilities;
+```
+
+Component rules live in `components`, **below** the utilities. A `className`
+set at use therefore always wins, whatever the place of the rule in the file:
+
+```mdx
+<Card className="border-0 shadow-none">…</Card>
+```
+
+Without this layer, a component rule written after a utility would beat it at
+equal specificity, and the author's `className` would be ignored without a
+word.
+
+The `custom` theme has no utilities: a `className` there designates your own
+classes. Declare them in `theme.css` — outside any layer, they come before the
+component rules.
+
+## The stylesheet is compiled last
+
+A utility theme only emits the rules of the classes actually used: it
+therefore needs the rendered pages before it can compile. The build first
+writes every page, collecting the classes along the way, then compiles the
+stylesheet.
+
+That is also why the slot classes are available **without** waiting for that
+compilation: the templates need them to be rendered. The two things are kept
+apart for this reason alone.

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

@@ -0,0 +1,124 @@
+---
+title: Deployment
+description: Publish the site, and keep past versions online.
+tags: [guide, deployment]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Deployment
+
+## The deployment prefix
+
+It is the setting that breaks the most sites, and the only one you really have
+to understand.
+
+A site served at the root of a domain has nothing to set. A site served under a
+sub-path — `https://example.com/my-project/` — must know it, otherwise every
+internal link will point one notch too high.
+
+```js
+siteUrl: 'https://example.com/my-project',
+```
+
+The sub-path of `siteUrl` **is enough**: `baseUrl` is derived from it when it
+is not set. Setting it only serves to depart from it.
+
+```js
+siteUrl: 'https://example.com/my-project',
+baseUrl: '/other-path/',
+```
+
+## Building for going live
+
+```bash
+npx docpensieve build
+```
+
+The output folder is self-contained: HTML files, one stylesheet per version,
+the copied resources. No server rule is needed — the root is an HTML redirect,
+and each page is a folder with its `index.html`.
+
+## Continuous integration
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - run: npx docpensieve build
+
+      # A successful build says nothing of a dead link.
+      - run: npx docpensieve check
+
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+      - id: deployment
+        uses: actions/deploy-pages@v5
+```
+
+The pages source must be set to "GitHub Actions" in the repository settings:
+otherwise the artifact is produced but never served.
+
+A project created by `init` has no `package.json`: the recipe therefore calls
+the tool through `npx`, which takes the latest published version. To pin it
+from one build to the next, declare `docpensieve` in a `package.json` and add
+`npm ci` before the build.
+
+## Reading back before publishing
+
+A generated site can compile without error and contain dead links.
+
+```bash
+npx docpensieve check
+```
+
+The command exits with code 1 if any remain: placed after the build, it stops
+the publication rather than put online a site whose links lead nowhere. It is
+the only safeguard that looks at the result rather than at the sources.
+
+## A scheduled build
+
+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.
+
+For those pages, a periodic build is enough:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 4 * * *'
+```
+
+## Keeping past versions
+
+Already published versions do not need to be rebuilt: their output is the one
+produced at the time, and nothing would guarantee that a rebuild gives the same
+result years later.
+
+The branch model answers this — each compiled version on its own orphan branch,
+with its history. See [Versions](./versions/).

package/starter/01-guide/index.md

@@ -0,0 +1,38 @@
+---
+title: Guide
+description: From installation to deployment, in order.
+tags: [guide]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Guide
+
+These pages are read in order. Each one starts from what the previous one set
+up.
+
+1. **[Installation](./installation/)** — what you need, and how to set up
+   a project.
+2. **[First site](./first-site/)** — build, serve, look at what was
+   produced.
+3. **[Writing pages](./writing-pages/)** — frontmatter, URLs, menu, links,
+   images.
+4. **[Versions](./versions/)** — several documentation versions, one
+   branch each.
+5. **[Themes](./themes/)** — style the site, change the classes without
+   touching the HTML.
+6. **[Deployment](./deployment/)** — publish, and keep past versions
+   online.
+
+## What to know first
+
+The produced site is **entirely static**. Each page is a complete HTML file,
+served as is, along with a single stylesheet. Nothing is computed on the
+reader's side.
+
+This has a consequence to keep in mind throughout: what depends on the moment —
+a date, a countdown — is frozen at build time, not at reading time.
+[TimeTimer](../components/time-timer/) says so explicitly, and a scheduled build
+is enough to keep it right.