docpensieve 0.5.0-beta.2 → 0.5.0-beta.3

package/starter/02-components/14-hero.mdx

@@ -0,0 +1,230 @@
+---
+title: Hero
+description: The banner at the head of a page — a name, a sentence, and the way in.
+---
+
+# Hero
+
+A landing page opens on three things: what this is, what it does, and where to
+start. `Hero` is the block that holds them, so that the head of a page is a
+component rather than a `div` and a pile of classes.
+
+It is **not a card**: no border, no panel. What a banner is made of is space, a
+title large enough to be the first thing read, and one way in that stands out
+from the rest. A frame exists for the page that asks for one, and it is not
+what you get by default.
+
+## A banner
+
+<Hero>
+
+## DocPensieve
+
+Your Markdown and MDX files become a static site. No runtime to load, one
+version per branch.
+
+<HeroActions>[Get started](../guide/installation/) [See the components](./)</HeroActions>
+
+</Hero>
+
+```mdx
+<Hero>
+
+# My project
+
+What it does, in one sentence.
+
+<HeroActions>[Get started](../guide/installation/) [Components](./)</HeroActions>
+
+</Hero>
+```
+
+Everything inside is ordinary Markdown: a heading, a paragraph, a row of
+links. The component sets the width of the sentence, the spacing, and turns
+the links into something to press — **the first one carries the accent**,
+because a reader should see one way in rather than three.
+
+## Aligned to the start
+
+`align="start"` leaves the banner where the text of the page is, which suits a
+section that opens a chapter rather than a site.
+
+<Hero align="start">
+
+### A section, not a site
+
+The same block, reading from the left.
+
+<HeroActions>[Read on](../guide/writing-pages/)</HeroActions>
+
+</Hero>
+
+```mdx
+<Hero align="start">
+
+## A section, not a site
+
+The same block, reading from the left.
+
+</Hero>
+```
+
+Accepted values are `center`, the default, and `start`. Anything else stops the
+build and lists the two — a banner silently ignoring its alignment would look
+like a stylesheet that failed.
+
+## With something to show
+
+Put a `HeroVisual` among the children and the banner becomes two columns — the
+words on one side, the picture on the other. Nothing to declare: having a
+visual is what makes it a split, which is the commonest shape of a landing
+page and the reason a project puts a screenshot there.
+
+<Hero>
+  <HeroText>
+
+### My project
+
+What it does, in one sentence, with room to breathe.
+
+<HeroActions>[Get started](../guide/installation/) [Components](./)</HeroActions>
+
+  </HeroText>
+  <HeroVisual>
+
+![A page of the site](./icons/banner.svg)
+
+  </HeroVisual>
+</Hero>
+
+```mdx
+<Hero>
+  <HeroText>
+
+# My project
+
+What it does, in one sentence, with room to breathe.
+
+<HeroActions>[Get started](/guide/installation/) [Components](/components/)</HeroActions>
+
+  </HeroText>
+  <HeroVisual>
+
+![A page of the site](./screenshot.png)
+
+  </HeroVisual>
+</Hero>
+```
+
+`HeroText` holds the words, `HeroVisual` the picture. Below 48rem the two
+columns become one, the picture following the words it illustrates.
+
+## A frame, if you want one
+
+`frame` draws the panel a banner does not have by default — a border, and a
+wash of its tone.
+
+<Hero frame size="small">
+
+### Framed
+
+For a banner that has to be told apart from the page around it.
+
+</Hero>
+
+```mdx
+<Hero frame>...</Hero>
+```
+
+## How much room it takes
+
+`size` decides the air around the words, not the look: `small`, `medium` —
+the default — `large`, and `full`, which takes the height of the screen and
+centres its content in it.
+
+<Hero size="small">
+
+### A small one
+
+For a section that only needs announcing.
+
+</Hero>
+
+```mdx
+<Hero size="small">...</Hero>
+<Hero size="large">...</Hero>
+<Hero size="full">...</Hero>
+```
+
+`full` measures the screen as the browser really shows it, so a phone whose
+address bar comes and goes does not push the banner under it.
+
+## The tone it is lit with
+
+`tone` names a colour the theme already carries — the same tones an admonition
+takes, because a theme defines a colour per tone, not a colour per component.
+A project that gives `attention` its own colour gives it to both at once.
+
+<Hero tone="tip" align="start" size="small">
+
+### Lit by a tone
+
+The wash behind the words, and the first way in, follow it.
+
+<HeroActions>[Read on](../guide/writing-pages/)</HeroActions>
+
+</Hero>
+
+```mdx
+<Hero tone="tip">...</Hero>
+```
+
+Accepted: `note` — the default, which is the accent of the theme — `info`,
+`tip`, `attention` and `danger`. Anything else stops the build and lists them,
+as an unknown size or alignment does: a banner silently ignoring what it was
+asked would look like a stylesheet that failed.
+
+## On a page of your own
+
+A banner belongs on a page that opens something: the home page of a version, a
+landing page for a section. The `home` layout of the frontmatter is its usual
+companion, since it drops the menu and the table of contents:
+
+```mdx
+---
+title: My project
+layout: home
+---
+
+<Hero>
+
+# My project
+
+...
+```
+
+## Properties
+
+| Property    | Type     | Effect                             |
+| ----------- | -------- | ---------------------------------- |
+| `align`     | `string` | `center` (the default) or `start`. |
+| `className` | `string` | Classes added to the banner.       |
+| `style`     | `object` | Inline styles on the banner.       |
+
+Its companions, each taking `className` and `style` as well:
+
+| Component     | What it holds                                                        |
+| ------------- | -------------------------------------------------------------------- |
+| `HeroActions` | The row of ways in. Its children are links, as Markdown writes them. |
+| `HeroText`    | The words, in a split. Not needed in a single column.                |
+| `HeroVisual`  | The picture. Its presence is what makes the banner a split.          |
+
+**One primary action and one alternative** is the shape that reads — a row of
+five buttons is a row of none.
+
+The classes are `dp-banner*`, after what the element is rather than after the
+component: a page that already writes a class of its own around a title keeps
+whatever that class did, and adopting the component stays a decision.
+
+A row of ways in is a row of choices — [Columns](./columns/) shows how to keep
+several blocks the same height when the banner is followed by cards.

package/starter/02-components/15-calendar.mdx

@@ -0,0 +1,130 @@
+---
+title: Calendar
+description: A month of dates and what happens on them — built at generation, navigable once the page has loaded its script.
+---
+
+# Calendar
+
+Dates read badly as a list. A release plan, a course schedule, the weeks of a
+migration: what matters is where they fall, and how far apart. `Calendar`
+draws the months, and puts each event on its day.
+
+## Days and what is on them
+
+<Calendar>
+  <Event date="2026-10-14" label="Release 0.5" href="../whats-new/" />
+  <Event date="2026-10-14" label="Blog post" />
+  <Event date="2026-10-28" label="Workshop" />
+</Calendar>
+
+```mdx
+<Calendar>
+  <Event date="2026-10-14" label="Release 0.5" href="/whats-new/" />
+  <Event date="2026-10-14" label="Blog post" />
+  <Event date="2026-10-28" label="Workshop" />
+</Calendar>
+```
+
+A day is written `2026-10-14` — four digits, two, two. Several events may fall
+on the same day, and they are drawn in the order they are written. `href` is
+resolved like any other link of a page: relative to the page, or from the
+version root.
+
+The events are written in the page. Nothing is read from the frontmatter of
+other pages: a calendar says what its author put in it, and says it where it
+is read.
+
+## Several months
+
+Every month between the first event and the last is drawn — including the ones
+with nothing in them, because a gap is something a reader should see.
+
+<Calendar>
+  <Event date="2026-11-18" label="Beta" />
+  <Event date="2027-01-06" label="Release" />
+</Calendar>
+
+```mdx
+<Calendar>
+  <Event date="2026-11-18" label="Beta" />
+  <Event date="2027-01-06" label="Release" />
+</Calendar>
+```
+
+Without JavaScript, the months are stacked one after the other and the whole
+calendar is readable. With it, they fold into one, two arrows move between
+them, and today is outlined. The arrows are **written hidden** and revealed by
+the script, so they never appear without the code that makes them work.
+
+That script is the client file of the version: a couple of kilobytes, loaded
+only by the pages that hold a calendar, and shared with any other behaviour
+the version uses. See [copyCode](../reference/configuration/) for what that
+file is.
+
+## The small model
+
+`compact` draws the grid small and writes the events out under it, at every
+width — beside a paragraph, or in a column of its own.
+
+**A narrow screen takes this model whatever the page asked for.** Seven columns
+of full cells on a phone give each day a few millimetres, and a label written
+in one is a word per line. Both forms are in the page and the stylesheet shows
+one, as the menu of the header is written twice: no script decides it, and
+nothing is read twice by a screen reader.
+
+<Calendar compact>
+  <Event date="2026-10-14" label="Release 0.5" href="../whats-new/" />
+  <Event date="2026-10-14" label="Blog post" />
+  <Event date="2026-10-28" label="Workshop" />
+</Calendar>
+
+```mdx
+<Calendar compact>
+  <Event date="2026-10-14" label="Release 0.5" />
+  <Event date="2026-10-28" label="Workshop" />
+</Calendar>
+```
+
+A day that holds something carries a dot, or the number of things it holds —
+a day with three should say three rather than look like a day with one. The
+list underneath is what says what they are: **nothing is only a colour**,
+which no screen reader reads and no colour-blind reader sees.
+
+## The language of the page
+
+Month and weekday names come from the language of the page, and so does the
+name a screen reader announces. A French page says `octobre`, an English one
+`October` — nothing to declare.
+
+## What it refuses
+
+| Written                       | What happens                                                       |
+| ----------------------------- | ------------------------------------------------------------------ |
+| a calendar with no event      | The build stops: an empty calendar shows nothing.                  |
+| `2026-10` or `14/10/2026`     | The build stops, saying how a day is written.                      |
+| `2026-09-31`                  | Refused: September has thirty days, so this is a typo, not a date. |
+| an event without a label      | The build stops, naming its day.                                   |
+| an `Event` outside a calendar | The build stops: nothing would know which month to draw it in.     |
+| anything else inside          | The build stops: a calendar holds events.                          |
+
+## Properties
+
+`Calendar`:
+
+| Property    | Type      | Effect                                                           |
+| ----------- | --------- | ---------------------------------------------------------------- |
+| `label`     | `string`  | Name announced to a screen reader. Default: `Calendar`.          |
+| `compact`   | `boolean` | The small model at every width. A narrow screen takes it anyway. |
+| `className` | `string`  | Classes added to the calendar.                                   |
+| `style`     | `object`  | Inline styles on the calendar.                                   |
+
+`Event`:
+
+| Property | Type     | Effect                                         |
+| -------- | -------- | ---------------------------------------------- |
+| `date`   | `string` | The day, `2026-10-14`. Required.               |
+| `label`  | `string` | What happens that day. Required.               |
+| `href`   | `string` | Where the event leads. Resolved like any link. |
+
+Writing a block twice and showing one is how this site handles a narrow screen
+throughout — [Columns](./columns/) makes the same choice.

package/starter/02-components/index.mdx

@@ -67,9 +67,15 @@ changes the examples too.
 
 ## Without JavaScript
 
-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.
+No component loads a script but one: `Calendar`, whose arrows between months
+come from the client file of the version — and only on the pages that hold a
+calendar. Whatever else needs interaction goes through native elements or
+through CSS: `details` for expanding, a link for moving, `animation-timeline`
+for appearing on scroll.
+
+The site itself can add a behaviour to a page — `copyCode` puts a copy button
+on each block of code — but that is a field you turn on, it lands in one file
+shared by the version, and only pages that use it load it.
 
 When the browser does not know one of these properties yet, the component stays
 usable in its simplest state — visible, full, expanded. None of them waits for

package/starter/02-components/snippet-example.js

@@ -0,0 +1,32 @@
+/**
+ * A file the Snippet page reads, rather than quoting.
+ *
+ * It is installed along with the documentation, so the examples on that page
+ * work in your project exactly as they do on this site. Change a line here
+ * and the page changes with it — which is the whole point of the component.
+ */
+
+/** Words a slug drops, so that titles do not all begin alike. */
+const SKIPPED = new Set(['a', 'an', 'the', 'of', 'to']);
+
+/**
+ * Turns the title of a page into the last segment of its address.
+ *
+ * @param {string} title Title, as the frontmatter gives it.
+ * @returns {string} A slug: lower case, accents dropped, words joined by a dash.
+ */
+export function slugOf(title) {
+  // #region guard
+  if (typeof title !== 'string' || title.trim() === '') {
+    throw new TypeError('slugOf needs a title');
+  }
+  // #endregion
+
+  return title
+    .normalize('NFD')
+    .replace(/\p{M}/gu, '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word && !SKIPPED.has(word))
+    .join('-');
+}

package/starter/02-components/snippet-example.py

@@ -0,0 +1,19 @@
+"""A second file, in another language, so the page can show what changes.
+
+Nothing here is read by the tool: it is only the source of an example. The
+extension is what tells the block which language it holds, and therefore
+which mark and which colour it carries.
+"""
+
+SKIPPED = {"a", "an", "the", "of", "to"}
+
+
+def slug_of(title: str) -> str:
+    """Turn the title of a page into the last segment of its address."""
+    # #region guard
+    if not isinstance(title, str) or not title.strip():
+        raise TypeError("slug_of needs a title")
+    # #endregion
+
+    words = "".join(c if c.isalnum() else " " for c in title.lower()).split()
+    return "-".join(w for w in words if w not in SKIPPED)

package/starter/03-reference/01-cli.md

@@ -113,9 +113,14 @@ Development server, which rebuilds on every save.
 npx docpensieve dev
 ```
 
-| Option                | Effect                          |
-| --------------------- | ------------------------------- |
-| `-p, --port <number>` | Listening port. Default: `3000` |
+| Option                | Effect                                                        |
+| --------------------- | ------------------------------------------------------------- |
+| `-p, --port <number>` | Listening port. Default: `3000`                               |
+| `--host <address>`    | Address to listen on. Default: `127.0.0.1`, this machine only |
+
+`0.0.0.0` opens the server to the network — to look at the site from a phone on
+the same wifi. Anyone on that network can then read it, drafts included, and
+the command says so when it starts.
 
 ## `serve`
 
@@ -125,10 +130,11 @@ Serves the output folder statically, without rebuilding anything.
 npx docpensieve serve
 ```
 
-| Option                | Effect                          |
-| --------------------- | ------------------------------- |
-| `-p, --port <number>` | Listening port. Default: `4000` |
-| `-d, --dir <dir>`     | Folder to serve                 |
+| Option                | Effect                                                        |
+| --------------------- | ------------------------------------------------------------- |
+| `-p, --port <number>` | Listening port. Default: `4000`                               |
+| `--host <address>`    | Address to listen on. Default: `127.0.0.1`, this machine only |
+| `-d, --dir <dir>`     | Folder to serve                                               |
 
 It is the command that faithfully reproduces what a host will do: to check what
 will be published, chain `build` then `serve`.

package/starter/03-reference/02-configuration.md

@@ -65,6 +65,8 @@ can change.
 | `stickyHeader`     | `true`              | The header stays at the top of the screen; `false` lets it scroll away                             |
 | `globalComponents` | `true`              | Shipped components available without an import                                                     |
 | `scrollToTop`      | `true`              | Back-to-top button on every page                                                                   |
+| `copyCode`         | `false`             | A button copying each block of code — the one field that makes a content page load a script        |
+| `snippetIcons`     | `''`                | Icon collection a code block takes the mark of its language from, `'simple-icons'`                 |
 | `jsonld`           | `{ enabled: true }` | Structured data                                                                                    |
 | `lang`             | `'en'`              | Language of the site: `<html lang>`, and the wording of the shell                                  |
 | `ui`               | `{}`                | Wording of the shell, by language — corrects a word, or adds a language                            |
@@ -135,6 +137,23 @@ The search page is kept out of search engines (`noindex`) and out of the
 sitemap. A page of your own at `/search/` would take its place: the build
 refuses it, and `search: false` frees the address.
 
+## `copyCode`
+
+`copyCode: true` puts a button on every block of code, which copies it.
+
+It is off by default, because it is the one field that makes an ordinary page
+load a script. Turned on, the behaviour is written **once per version**, in
+`assets/client.js` beside the stylesheet, and shared by every page and every
+language — a reader who has it in cache pays for it once. Only the pages that
+hold a block of code load it; the others go on loading nothing.
+
+About two kilobytes, compressed. No framework, no hydration: the code is plain
+DOM, and the button is drawn by the script itself. Without JavaScript the
+block is exactly what it was, text you can select — nothing is missing but
+the button.
+
+The label follows the language of the page, in English and in French.
+
 ## `versions`
 
 ```js