docpensieve 0.2.0 → 0.3.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.2",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.2.0",
-    "@docpensieve/core": "0.2.0",
-    "@docpensieve/shared": "0.2.0",
-    "@docpensieve/theme": "0.2.0",
+    "@docpensieve/components": "0.3.0-beta.2",
+    "@docpensieve/core": "0.3.0-beta.2",
+    "@docpensieve/shared": "0.3.0-beta.2",
+    "@docpensieve/theme": "0.3.0-beta.2",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/src/commands/init.js

@@ -266,6 +266,11 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  // version folder.',
     "  sidebar: 'auto',",
     '',
+    '  // Authors described in a JSON file of each version folder: a name, a',
+    '  // biography, an avatar, a link. Left empty, a page still shows the',
+    '  // names its frontmatter gives, without the rest.',
+    "  authors: '',",
+    '',
     '  // The shipped components — Card, Columns, Tooltip… — usable in any .mdx',
     '  // page without an import. false removes them, to use your own names.',
     '  globalComponents: true,',

package/starter/01-guide/01-installation.md

@@ -99,9 +99,9 @@ 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.1, [Migrate from 0.1 to 0.2](./migrate-from-0-1/) says what
-changes on its own and what to check first. To try the version being prepared,
-install `docpensieve@beta`, or run `npx docpensieve@beta` alone.
+Coming from the 0.2, [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.
 
 ## Checking
 

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

@@ -31,6 +31,46 @@ without `title`, the project name stands in.
 
 The fields are detailed in the [reference](../reference/frontmatter/).
 
+## Who wrote the page
+
+A page that names its authors, or carries a date, opens with a byline:
+
+```yaml
+---
+title: Installation
+authors: [ada, grace]
+date: 2026-09-09
+modified: 2026-09-16
+---
+```
+
+The names show as written. To give them a biography, an avatar and a link,
+describe them in a JSON file of the version folder:
+
+```json
+{
+  "ada": {
+    "name": "Ada Lovelace",
+    "bio": "Wrote the first algorithm meant for a machine.",
+    "avatar": "authors/ada.png",
+    "url": "https://example.com/ada"
+  }
+}
+```
+
+Then name that file in the configuration: `authors: 'authors.json'`. It is
+read **in each version folder**, as the menu is — a biography corrected in
+the version being written leaves the published one alone. The file itself is
+not published; the avatars are, and are measured at the build so that the
+text does not jump when they arrive.
+
+A key nobody describes is shown as written, which is what lets a project name
+its authors before describing them. The description also feeds the page data:
+a biography becomes the `description` of its `Person`, a link its `url`.
+
+A date written the day the page was is not repeated as an update, and a home
+page carries no byline at all: it is an entrance hall, not a document.
+
 ## What the URL depends on
 
 The file path gives the URL path, stripped of its extension and of its sorting

package/starter/01-guide/07-migrate-to-beta.md

@@ -0,0 +1,37 @@
+---
+title: Migrate from latest to beta
+description: Move a project from the latest version, the 0.2, to the 0.3 beta — what changes on its own, and what to check.
+tags: [guide, migration]
+---
+
+# Migrate from latest to beta
+
+A project on the latest version — the 0.2 — builds with the 0.3 beta as it is:
+every new field is optional.
+
+## Update
+
+```bash
+npm install docpensieve@beta
+```
+
+Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
+`npm install docpensieve@latest`.
+
+## What changes on its own
+
+| What                                       | In 0.3                                          |
+| ------------------------------------------ | ----------------------------------------------- |
+| Pages with `authors`, `date` or `modified` | Open with a byline naming the authors and dates |
+
+Nothing to change, but something to know: those three fields already existed,
+read by the sitemap and the page data without ever being shown. They are now
+shown, so a page that carries them gains a block it did not have. A page that
+carries none of them looks exactly as before.
+
+## What to turn on
+
+| Field                        | Gives                                                 |
+| ---------------------------- | ----------------------------------------------------- |
+| `authors: 'authors.json'`    | Biographies, avatars and links, described per version |
+| `<Cards />` in an index page | A grid of cards built from the pages of the folder    |

package/starter/01-guide/index.md

@@ -13,20 +13,7 @@ jsonld:
 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.
-7. **[Migrate from 0.1 to 0.2](./migrate-from-0-1/)** — move a 0.1 project to
-   the 0.2.
+<Cards />
 
 ## What to know first
 

package/starter/02-components/10-cards.mdx

@@ -0,0 +1,76 @@
+---
+title: Cards
+description: Grids of clickable cards, built from the pages of the version.
+---
+
+# Cards
+
+A folder is a **series**: its `index` page introduces it, and the pages beside
+that index are its instalments. `Cards` turns that structure into a grid,
+rather than a list written by hand — a hand-written index goes stale at the
+first page renamed, and nothing says so.
+
+## On this page
+
+Placed in a page, the component lists what stands beside it. Here, the other
+component pages:
+
+<Cards />
+
+```mdx
+<Cards />
+```
+
+Written in the `index` page of a folder, it lists that folder instead: a series
+page shows its own instalments, not its neighbours.
+
+## What a card carries
+
+Everything comes from the pages themselves, nothing is declared twice:
+
+| Shown           | Read from                                                      |
+| --------------- | -------------------------------------------------------------- |
+| Title           | `title` of the page                                            |
+| Description     | `description` of the page                                      |
+| Image           | `preview` of the page, resolved from the page that declares it |
+| Number of pages | Counted under the folder — on a series card only               |
+| Update date     | `modified`, or failing that `date`                             |
+
+The **whole card is the link**, never the title alone: a card whose surface
+does nothing invites a click that is lost.
+
+## Narrowing the grid
+
+| Prop        | Effect                                                               |
+| ----------- | -------------------------------------------------------------------- |
+| `of`        | `series` keeps the folders, `pages` keeps the pages beside the index |
+| `from`      | Reads another folder, named by its path within the version           |
+| `className` | Classes added to the grid                                            |
+| `style`     | Inline styling, for a one-off adjustment                             |
+
+```mdx
+<Cards of="series" />
+<Cards from="guide" />
+```
+
+`from` names a folder of **this** version, as it appears in a URL: `guide`, or
+`guide/advanced`. It stops the build when nothing lives under that path, which
+catches a typo rather than rendering an empty grid.
+
+## Sizing
+
+The grid fills the width it is given, with as many columns as fit. To hold it
+narrower, set a width on the block — tokens and lengths work under both
+themes, so this needs no variant:
+
+```mdx
+<div style={{ maxWidth: '32rem' }}>
+  <Cards of="series" />
+</div>
+```
+
+## Without JavaScript
+
+Like every component here, the grid is built at the build. What reaches the
+reader is a list of links: it works with JavaScript turned off, and a card
+never waits for anything to become clickable.

package/starter/02-components/index.mdx

@@ -63,15 +63,7 @@ changes the examples too.
 
 ## Available
 
-- [Card](./card/) — card, with header, body, footer and image
-- [Columns](./columns/) — column grid
-- [TimeTimer](./time-timer/) — display depending on a date
-- [Tooltip](./tooltip/) — tooltip on hover and from the keyboard
-- [Tree](./tree/) — collapsible tree
-- [ScrollToTop](./scroll-to-top/) — back to the top of the page
-- [Skill](./skill/) — level gauge
-- [LogoIcon](./logo-icon/) — SVG icon inlined in the page
-- [ForTheme](./for-theme/) — content kept for one theme only
+<Cards />
 
 ## Without JavaScript
 

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

@@ -177,6 +177,22 @@ Longer rules go in the `theme/` folder, at the root of the project: every
 `docpensieve dev` picks up every change. Under the `custom` theme, `init`
 starts it with `theme/custom.css`.
 
+## `authors`
+
+```js
+authors: 'authors.json',
+```
+
+Names a JSON file **read in each version folder**, describing the authors a
+page names in its frontmatter: a name, a biography, an avatar, a link.
+
+Empty by default, and then a page still shows the names it gives, without the
+rest: the file enriches, it does not command. Named but missing, it stops the
+build — leaving every biography out without a word would be worse.
+
+The file is not published. The avatars are, their path starting at the version
+folder so that they travel with it.
+
 ## `sidebar`
 
 `'auto'` builds the menu from the file tree: folders become categories, and the

package/starter/03-reference/03-frontmatter.md

@@ -38,18 +38,18 @@ jsonld:
 
 ## The fields
 
-| Field         | Effect                                                    |
-| ------------- | --------------------------------------------------------- |
-| `title`       | `<title>` tag, menu entry, breadcrumb, JSON-LD `headline` |
-| `description` | `description` metadata and JSON-LD `description`          |
-| `date`        | Publication date                                          |
-| `modified`    | Last modification date. Default: the publication date     |
-| `authors`     | List of authors                                           |
-| `tags`        | Keywords, carried over as `keywords`                      |
-| `preview`     | Image of the page. The path is resolved like a link       |
-| `draft`       | `true` keeps the page out of the output                   |
-| `layout`      | `doc` (default) or `home`                                 |
-| `jsonld`      | Structured data settings                                  |
+| Field         | Effect                                                                     |
+| ------------- | -------------------------------------------------------------------------- |
+| `title`       | `<title>` tag, menu entry, breadcrumb, JSON-LD `headline`                  |
+| `description` | `description` metadata and JSON-LD `description`                           |
+| `date`        | Publication date                                                           |
+| `modified`    | Last modification date. Default: the publication date. Shown in the byline |
+| `authors`     | Authors of the page, by name or by key of the version's author file        |
+| `tags`        | Keywords, carried over as `keywords`                                       |
+| `preview`     | Image of the page. The path is resolved like a link                        |
+| `draft`       | `true` keeps the page out of the output                                    |
+| `layout`      | `doc` (default) or `home`                                                  |
+| `jsonld`      | Structured data settings                                                   |
 
 ## `layout`
 

package/starter/03-reference/05-api.md

@@ -488,6 +488,75 @@ that carries neither is listed without one rather than with a made-up date.
 
 **Returns** `string`
 
+### `buildAuthorTable`
+
+`buildAuthorTable(description, options)`
+
+Turns the JSON description of a version into a table of authors.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `description` | `unknown` | Parsed content of the file. |
+| `options` | `{ source: string }` | `source` names the file in errors. |
+
+**Returns** `Map<string, Author>`
+
+**Throws** `ConfigError` — When the shape is wrong, naming the offending entry.
+
+### `buildByline`
+
+`buildByline(frontmatter, [table], [where])`
+
+Assembles what the head of a page shows, or nothing when it has none of it.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `frontmatter` | `Record<string, any>` |  |
+| `[table]` | `Map<string, Author>` |  |
+| `[where]` | `string` | Page named in a date error. |
+
+**Returns** `Byline \| null`
+
+**Throws** `ConfigError` — When a date cannot be read.
+
+### `readDate`
+
+`readDate(value, field, where)`
+
+Reads a date of the frontmatter, and gives it in both forms: the machine one
+for `<time datetime>`, the readable one for the reader.
+
+A date is often written unquoted in YAML, which parses it as a Date; quoted,
+it arrives as text. Both are accepted, anything unreadable is refused rather
+than shown as `Invalid Date`.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `value` | `unknown` |  |
+| `field` | `string` | Name of the field, for the error message. |
+| `where` | `string` | Page the date comes from. |
+
+**Returns** `{ iso: string, label: string } \| null` — `null` when absent.
+
+**Throws** `ConfigError` — When the value is not a date.
+
+### `resolvePageAuthors`
+
+`resolvePageAuthors(value, [table])`
+
+The authors of a page, in the order the frontmatter names them.
+
+A key the table does not describe is not an error: the name is shown as
+written. It is what lets a project name its authors before describing them,
+and what keeps pages written before the file working.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `value` | `unknown` | `authors` from the frontmatter: one name or a list. |
+| `[table]` | `Map<string, Author>` |  |
+
+**Returns** `Author[]`
+
 ## `@docpensieve/theme`
 
 The theme providers and the engine that composes them.
@@ -642,6 +711,18 @@ itself (ADR-006).
 | --- | --- | --- |
 | `props` | `{ className?: string, style?: object, src?: string, alt?: string, title?: string, srcSet?: string, sizes?: string, loading?: 'lazy' \| 'eager', }` | `alt` defaults to the empty string: without that attribute, a screen reader would announce the file URL. |
 
+### `Cards`
+
+`Cards(props)`
+
+Grid of cards for the children of a folder.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `props` | `{ className?: string, style?: object, of?: 'all' \| 'series' \| 'pages', from?: string, }` | `of` narrows the grid to the sub-folders (`'series'`) or to the pages beside the index (`'pages'`); `from` reads another folder, named by its slug, instead of the one holding the page. |
+
+**Throws** `Error` — When the page list is missing, or `from` names nothing.
+
 ### `Column`
 
 `Column(props)`

package/starter/03-reference/index.md

@@ -10,13 +10,7 @@ jsonld:
 
 # Reference
 
-- **[Commands](./cli/)** — `init`, `build`, `check`, `dev`, `serve`
-  and their options.
-- **[Configuration](./configuration/)** — every field of
-  `docpensieve.config.mjs`, its default value and its effect.
-- **[Frontmatter](./frontmatter/)** — the fields recognised at the top
-  of a page.
-- **[Theme](./theme/)** — slots, tokens and styling options.
+<Cards />
 
 To learn how to use them rather than look them up, the [guide](../guide/) is the
 right starting point.

package/starter/05-whats-new.md

@@ -1,80 +1,40 @@
 ---
-title: What's new in 0.2
-description: What the 0.2 brings, and what it changes for a 0.1 project.
+title: What's new in 0.3
+description: What the 0.3 brings, and what it changes for a 0.2 project.
 tags: [release]
 ---
 
-# What's new in 0.2
+# What's new in 0.3
 
-This version is **out**. It is what `npx docpensieve init my-site` installs,
-and what the `latest` pages of this site document:
+This version is **in preparation**. Its betas go out under the npm tag `beta`,
+while the version installed by default stays the 0.2, documented in the
+`latest` pages of this site:
 
 ```bash
-npm install docpensieve@latest
+npx docpensieve@beta init my-site
 ```
 
-What follows describes everything it brings, and
-[Migrate from 0.1 to 0.2](./guide/migrate-from-0-1/) says what to check in a
-0.1 project.
-
 ## Already there
 
-### A menu written by hand
-
-`sidebar: 'sidebar.json'` replaces the menu derived from the file tree with
-one you describe — pages in the order you want, categories, links outside the
-site. Each version reads its own file, since each has its own pages. A section
-can keep its automatic menu with a single entry, which is how the DocPensieve
-section stays whole without listing its pages.
-
-See [Writing the menu by hand](./guide/writing-pages/) in the guide, and the
-[`sidebar` field](./reference/configuration/) in the reference.
-
-### Search engines and feed readers
-
-With `siteUrl` set, the build writes `sitemap.xml` for search engines — and
-`robots.txt` when the site sits at the root of its domain. `feed: true` adds an
-RSS feed of the dated pages. See [Sitemap and feed](./reference/configuration/)
-in the reference.
-
-### Search
-
-A search field in the header, and a search page in each version. The index is
-built with the site, and the field is a plain form: only the search page loads
-a script of its own, and without it the page stays the list of every page. See
-[Search](./reference/configuration/) in the reference.
-
-### A colour scheme of your choosing, and a logo per version
-
-`theme.darkMode: 'dark'` keeps the site dark whatever the reader's system —
-`'light'` keeps it light; `'class'`, the default, still follows the system.
-Until now the field was accepted and did nothing. A version can also carry its
-own `logo` and `favicon`, to tell a beta apart at a glance. See the
-[configuration reference](./reference/configuration/).
-
-### A light / dark switch
-
-A button in the header switches between light and dark, and remembers the
-choice from page to page. It is on by default — a few lines of inline script
-in every page; `theme.toggle: false` removes it, and pages then load no script.
-
-### Lighter pages
+### Authors at the head of a page
 
-The stylesheet reaches the reader minified. Every image of a page gets its
-width and height, read from its file, so that the text no longer jumps when it
-arrives; all but the first load lazily, and are no longer preloaded — the
-first, often in view, keeps its normal loading. `CardImage` loads lazily too.
+A page carrying `authors`, `date` or `modified` now opens with a byline: who
+wrote it, and when. The names show as written; a JSON file of the version,
+named by `authors: 'authors.json'`, adds a biography, an avatar and a link —
+and feeds the page data with them. See
+[Who wrote the page](./guide/writing-pages/) in the guide, and the
+[`authors` field](./reference/configuration/) in the reference.
 
-### The API reference, and two example projects
+### Series and cards
 
-Every export of the five packages is in the [API reference](./reference/api/),
-generated from the JSDoc of the sources, so that it cannot drift from the code.
-The repository also holds two complete example projects, one per theme, built
-and checked on every run of its tests.
+A folder is a series: its `index` page introduces it, and the pages beside
+that index are its instalments. The `Cards` component turns that structure
+into a grid of clickable cards — title, description, image, number of pages,
+update date — instead of an index list written by hand, which goes stale at
+the first page renamed. See [Cards](./components/cards/).
 
-## For a 0.1 project
+## For a 0.2 project
 
-Nothing to change: a 0.1 configuration builds as it is. `sidebar: 'auto'`
-stays the default, and every new field is optional.
-[Migrate from 0.1 to 0.2](./guide/migrate-from-0-1/) goes through what changes
-on its own, what to check, and what is worth turning on.
+Nothing to change: a 0.2 configuration builds as it is.
+[Migrate from latest to beta](./guide/migrate-to-beta/) lists what changes on
+its own, what to check, and what is worth turning on.

package/starter/01-guide/07-migrate-from-0-1.md

@@ -1,57 +0,0 @@
----
-title: Migrate from 0.1 to 0.2
-description: Move a project from the 0.1 to the 0.2 — what changes on its own, what to check, what to turn on.
-tags: [guide, migration]
----
-
-# Migrate from 0.1 to 0.2
-
-A project on the 0.1 builds with the 0.2 as it is: every new field is
-optional. A few things change on their own, though, and deserve a look.
-
-## Update
-
-```bash
-npm install docpensieve@latest
-```
-
-Through `npx` alone, `npx docpensieve` fetches the 0.2 by itself. Going back
-is `npm install docpensieve@0.1.5`.
-
-## What changes on its own
-
-| What                | In 0.2                                                                              |
-| ------------------- | ----------------------------------------------------------------------------------- |
-| Search              | A field in the header, and a page at `/search/` in each version                     |
-| `sitemap.xml`       | Written at the root of the site as soon as `siteUrl` is set                         |
-| `robots.txt`        | Written with it, when the site is served at the root of its domain                  |
-| The stylesheet      | Minified                                                                            |
-| Images              | Their width and height are written; all but the first of a page load lazily         |
-| Light / dark switch | A button in the header, remembered from page to page — a few lines of inline script |
-| `theme.darkMode`    | Now read: `'dark'` and `'light'` keep one scheme, `'class'` follows the system      |
-
-Every page now carries the few lines of the light / dark switch —
-`theme.toggle: false` removes them — and the search page loads its own script.
-
-## What to check
-
-- **A page of yours at `/search/`** now stops the build: that address is the
-  search page's. Rename your page, or set `search: false`.
-- **`theme.darkMode`** was accepted and ignored in 0.1. A value other than
-  `'class'` now takes effect — and an unknown one stops the build.
-- **The light / dark switch** is on by default. `theme.toggle: false` removes
-  it, and with it the only script content pages carry.
-- **Your own `robots.txt`**, if you published one next to the site, is now
-  written by the build when the site sits at the root of its domain. Set
-  `sitemap: false` to keep yours.
-
-## What to turn on
-
-| Field                        | Gives                                                         |
-| ---------------------------- | ------------------------------------------------------------- |
-| `sidebar: 'sidebar.json'`    | A menu written by hand, in each version's folder              |
-| `feed: true`                 | An RSS feed of the pages that carry a `date`                  |
-| `versions[].logo`, `favicon` | A logo and a favicon of the version's own — a beta told apart |
-| `search: false`              | No search at all, if the site does not need one               |
-
-Every field is in the [configuration reference](../reference/configuration/).