docpensieve 0.3.0-beta.1 → 0.3.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.3.0-beta.1",
+  "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.3.0-beta.1",
-    "@docpensieve/core": "0.3.0-beta.1",
-    "@docpensieve/shared": "0.3.0-beta.1",
-    "@docpensieve/theme": "0.3.0-beta.1",
+    "@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/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

@@ -20,5 +20,18 @@ Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
 
 ## What changes on its own
 
-Nothing yet: the 0.3 has just opened. Each change is listed here as it lands,
-beside what it asks of a project already built on the 0.2.
+| 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 latest to beta](./migrate-to-beta/)** — move a 0.2 project
-   to the 0.3 beta.
+<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

@@ -16,10 +16,22 @@ npx docpensieve@beta init my-site
 
 ## Already there
 
-Nothing yet: the 0.3 has just opened, and its pages are still those of the 0.2.
-Each feature is announced here as it lands, with a link to the guide and to the
-reference — this page announces, it is never the only place something is
-written.
+### Authors at the head of a page
+
+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.
+
+### Series and cards
+
+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.2 project