docpensieve 0.5.0-beta.2 → 0.5.0-beta.4

package/starter/02-components/13-snippet.mdx

@@ -0,0 +1,230 @@
+---
+title: Snippet
+description: A code block that names a real file of your project, read when the page is generated, so that the example cannot go stale.
+---
+
+# Snippet
+
+An example written by hand is a copy. It stops being true the day the code
+changes, and nothing reports it: the page goes on showing something that
+worked once. `Snippet` names the file instead, and the file is read when the
+page is generated — there is no copy left to drift.
+
+The idea comes from **Christophe Avonture**, who built it for his own site.
+
+## Naming a file
+
+<Snippet source="./snippet-example.js" />
+
+```mdx
+<Snippet source="./snippet-example.js" />
+```
+
+The file name labels the block, and the highlighting is the one every code
+block gets. A path beginning with `./` or `../` is read **from the page**, as
+a link is; any other path is read **from the root of your project**, so that
+`src/index.js` means the same file from every page.
+
+## Part of a file
+
+Two ways, and they do not age the same.
+
+A **range of lines** is quick to write and means line 12 of the file as it is
+today:
+
+<Snippet source="./snippet-example.js" lines="9-10" title="The words it drops" />
+
+```mdx
+<Snippet source="./snippet-example.js" lines="9-10" title="The words it drops" />
+```
+
+Write `lines="9"` for one line, `"9-10"` for a range, `"9-"` from there to the
+end, `"-10"` from the start. It says what the file holds today, and only
+today.
+
+A **region** is a marker left in the source file itself, in a comment. It
+follows the code when the code moves, which is the whole point of naming a
+file rather than copying it:
+
+<Snippet source="./snippet-example.js" region="guard" title="The guard" />
+
+```mdx
+<Snippet source="./snippet-example.js" region="guard" title="The guard" />
+```
+
+In the file, the marker is an ordinary comment — the one editors already fold
+on:
+
+```js
+// #region guard
+if (!name) {
+  throw new Error('greet needs a name');
+}
+// #endregion
+```
+
+The indentation the kept lines share is removed, so a region marked inside a
+function does not come out shifted.
+
+## Folding a long file
+
+`collapsed` puts the block inside a `details`. No script: a long file can sit
+in a page without burying what follows it.
+
+<Snippet source="./snippet-example.js" collapsed title="The whole file" />
+
+```mdx
+<Snippet source="./snippet-example.js" collapsed title="The whole file" />
+```
+
+## Code you write yourself
+
+Without `source`, the component frames the code written in the page. A fenced
+block inside the tag is the dependable way to write it: it carries anything,
+braces and `<` included, and no formatter touches what is inside it.
+
+<Snippet title="greet.py">
+
+```python
+def greet(name, greetings={'en': 'Hello'}):
+    return f"{greetings['en']}, {name}!"
+```
+
+</Snippet>
+
+````mdx
+<Snippet title="greet.py">
+
+```python
+def greet(name, greetings={'en': 'Hello'}):
+    return f"{greetings['en']}, {name}!"
+```
+
+</Snippet>
+````
+
+The extension of the title names the language; `lang` says it where the title
+does not, as for a shell:
+
+<Snippet title="Build the site" lang="bash">
+
+```bash
+npm install
+npx docpensieve build
+```
+
+</Snippet>
+
+````mdx
+<Snippet title="Build the site" lang="bash">
+
+```bash
+npm install
+npx docpensieve build
+```
+
+</Snippet>
+````
+
+### Code typed straight into the tag
+
+Code written bare inside the tag is read too, from the page as you typed it —
+indentation kept, nothing taken for Markdown:
+
+```mdx
+<Snippet title="who_are_you.py">name = input("What's your name? ")</Snippet>
+```
+
+Two things it cannot carry, both of which happen before any component sees the
+code. A page is MDX, so `{`, `}` and `<` are read as MDX and stop the build on
+a syntax error. And a formatter run over your pages reflows what it takes for
+prose: two lines of shell come back as one. Where either applies — which is
+most real code — use the fenced form above.
+
+## The mark of the language
+
+A block carries the colour of its language — a rule above it, and a short mark
+beside the file name. The colour is set as a variable on the frame, so the
+theme decides what it paints and a project can set another.
+
+The same function, in the other file this page reads. Nothing was said about
+the language: the extension carried it, and with it the mark and the colour.
+
+<Snippet source="./snippet-example.py" region="guard" title="The same guard, in Python" />
+
+```mdx
+<Snippet source="./snippet-example.py" region="guard" title="The same guard, in Python" />
+```
+
+A block the page writes says its language in the fence, and is marked the same
+way:
+
+<Snippet title="deploy.yml">
+
+```yaml
+steps:
+  - run: npx docpensieve build
+  - run: npx docpensieve check
+```
+
+</Snippet>
+
+<Snippet title="A first build" lang="bash">
+
+```bash
+npx docpensieve init my-site
+npx docpensieve dev
+```
+
+</Snippet>
+
+Where a project installs an icon collection and names it, the drawing replaces
+the mark:
+
+```js
+snippetIcons: 'simple-icons',
+```
+
+It is never a reason to fail. The icon is the tool's idea, not something your
+page asked for: a collection you do not have, or a language it does not draw,
+brings back the mark. `icon="simple-icons:docker"` on a single block wins over
+both.
+
+### A language nobody marked
+
+Twenty-one languages have a mark and a colour. Any other is shown without
+one — the frame, the name, and the code.
+
+Highlighting is a separate matter, and a wider one: the highlighter knows
+several hundred languages, and a block in one it does not know comes out as
+plain text rather than stopping the build. You can write a snippet in anything
+your project is written in.
+
+## What it refuses
+
+Nothing fails quietly, because a snippet that resolved to nothing would leave
+an empty frame — and an empty frame looks deliberate.
+
+| Written                             | What happens                                                    |
+| ----------------------------------- | --------------------------------------------------------------- |
+| a file that is not there            | The build stops, saying which path was looked for.              |
+| a path leading outside the project  | Refused: a page is content, and content does not read the disk. |
+| a region no marker opens, or closes | The build stops, naming the region and the file.                |
+| a range that reads backwards        | The build stops.                                                |
+
+## Properties
+
+| Property    | Type      | Effect                                                                      |
+| ----------- | --------- | --------------------------------------------------------------------------- |
+| `source`    | `string`  | File to read. From the page with `./` or `../`, from the project otherwise. |
+| `title`     | `string`  | Label above the block. Defaults to the name of the file.                    |
+| `lines`     | `string`  | `8`, `8-14`, `8-` or `-14`.                                                 |
+| `region`    | `string`  | Name marked by `#region` and `#endregion` in the file.                      |
+| `lang`      | `string`  | Language for the highlighting, when the extension says the wrong thing.     |
+| `collapsed` | `boolean` | Folds the block into a `details`.                                           |
+| `icon`      | `string`  | An icon for this block, instead of the mark of its language.                |
+| `className` | `string`  | Classes added to the frame.                                                 |
+| `style`     | `object`  | Inline styles on the frame.                                                 |
+
+The file this page reads is installed along with it, so every example above
+works in your project exactly as it does here.

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)