docpensieve 0.5.0-beta.3 → 0.5.0-beta.4

package/package.json

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

package/src/commands/init.js

@@ -399,6 +399,10 @@ function renderConfig({ name, theme, siteUrl, version, translation = '' }) {
     '  // A search field in the header, and a search page built with the site.',
     '  // Content pages load no script: the search page alone does.',
     '  search: true,',
+    '',
+    '  // llms.txt at the root of the site, and a Markdown copy beside each',
+    '  // page: what a program reads instead of the HTML. It needs no siteUrl.',
+    '  llms: false,',
     '};',
     '',
     '// Every field is described in the reference of the DocPensieve documentation:',

package/src/server.js

@@ -4,8 +4,7 @@
  * @module docpensieve/server
  */
 
-import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import path from 'node:path';
 
@@ -134,9 +133,15 @@ export function createStaticServer({ root, basePath = '/', inject = null, onRelo
       return;
     }
 
-    let stats;
+    // Read whole, then answer. `dev` empties the version folder at every
+    // rebuild while a browser may still be asking for it: between a `stat`
+    // and a stream the file could vanish, the stream then threw with nobody
+    // listening, and the server went down in the middle of a save. Read at
+    // once, a file is either there or answered 404 — and its length is the
+    // one actually sent, not the one a rebuild was busy changing.
+    let body;
     try {
-      stats = await stat(filepath);
+      body = await readFile(filepath);
     } catch {
       response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
       response.end(`404 — ${url.pathname}`);
@@ -147,18 +152,17 @@ export function createStaticServer({ root, basePath = '/', inject = null, onRelo
     const headers = { 'content-type': type, 'cache-control': 'no-cache' };
 
     if (inject && type.startsWith('text/html')) {
-      const { readFile } = await import('node:fs/promises');
-      const html = await readFile(filepath, 'utf8');
-      const body = html.includes('</body>')
+      const html = body.toString('utf8');
+      const page = html.includes('</body>')
         ? html.replace('</body>', `${inject}</body>`)
         : html + inject;
-      response.writeHead(200, { ...headers, 'content-length': Buffer.byteLength(body) });
-      response.end(body);
+      response.writeHead(200, { ...headers, 'content-length': Buffer.byteLength(page) });
+      response.end(page);
       return;
     }
 
-    response.writeHead(200, { ...headers, 'content-length': stats.size });
-    createReadStream(filepath).pipe(response);
+    response.writeHead(200, { ...headers, 'content-length': body.length });
+    response.end(body);
   });
 }
 

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

@@ -160,6 +160,10 @@ For pages that are news rather than reference — release notes, a changelog —
 give them a `date` and set `feed: true`: `feed.xml` then lists them, newest
 first. The fields are in the [configuration reference](../reference/configuration/).
 
+For programs that read documentation on someone's behalf, `llms: true` writes
+`llms.txt` at the root and a Markdown copy beside each page — the text
+without the markup. It needs no `siteUrl`.
+
 ## What the reader downloads
 
 The build keeps it light on its own. The stylesheet is minified — a third to

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

@@ -48,6 +48,7 @@ npx docpensieve check
 - `copyCode`, a copy button on every code block — off by default, since it is
   what makes a page load a script. See [the reference](../reference/configuration/).
 - `snippetIcons`, if your project installs an icon collection.
+- `llms`, for `llms.txt` and a Markdown copy of each page.
 
 ## What to check afterwards
 

package/starter/02-components/01-card.mdx

@@ -344,3 +344,25 @@ in none: a class of yours always wins, even to undo the default style.
 
 The commonest row is a row of cards; [Columns](./columns/) shows how to keep
 them the same height, which a grid alone does not.
+
+## Properties
+
+`Card`:
+
+| Property    | Type      | Effect                                                           |
+| ----------- | --------- | ---------------------------------------------------------------- |
+| `elevated`  | `boolean` | Adds a shadow.                                                   |
+| `href`      | `string`  | Makes the whole card a link, resolved like any link of the page. |
+| `className` | `string`  | Classes added to the card.                                       |
+| `style`     | `object`  | Inline styles on the card.                                       |
+
+`CardImage`:
+
+| Property                   | Type     | Effect                                                           |
+| -------------------------- | -------- | ---------------------------------------------------------------- |
+| `src`                      | `string` | The image, resolved like any link of the page.                   |
+| `alt`                      | `string` | What the image shows. Empty by default: the image is decorative. |
+| `loading`                  | `string` | `lazy`, the default, or `eager`.                                 |
+| `title`, `srcSet`, `sizes` | `string` | Passed to the image as they are.                                 |
+
+`CardHeader`, `CardBody` and `CardFooter` take `className` and `style`.

package/starter/02-components/02-columns.mdx

@@ -287,3 +287,15 @@ window to check.
 
 The most frequent row is a row of cards; [Card](./card/) shows how to keep
 them to the same height, which a grid alone does not do.
+
+## Properties
+
+`Column`:
+
+| Property    | Type     | Effect                                                                                                            |
+| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `span`      | `number` | Tracks taken out of twelve — `6` for a half, `8` for two thirds. Without it, the columns share the space equally. |
+| `className` | `string` | Classes added to the column.                                                                                      |
+| `style`     | `object` | Inline styles on the column.                                                                                      |
+
+`Columns` takes `className` and `style`. A `Column` outside a `Columns` stops the build.

package/starter/02-components/03-time-timer.mdx

@@ -122,3 +122,22 @@ names the faulty value and recalls the expected format.
 Announcing a release is what this is usually for, and [Versions](../guide/versions/)
 covers the rest of that cycle — the banner a prerelease carries on its own,
 and the day the two tracks swap.
+
+## Properties
+
+`TimeTimer`:
+
+| Property   | Type      | Effect                                                                                |
+| ---------- | --------- | ------------------------------------------------------------------------------------- |
+| `date`     | `string`  | A single day, `DD/MM/YYYY`, optionally followed by `HH:mm`. The year may be left out. |
+| `start`    | `string`  | Start of a period, in the same format, with `duration`.                               |
+| `duration` | `string`  | Length of the period from `start`: `30d`, `2h`, `45m`.                                |
+| `strict`   | `boolean` | Reads the dates in UTC rather than in local time.                                     |
+| `now`      | `Date`    | For tests only: without it, the moment of the build stands.                           |
+
+The fallbacks each take one bound:
+
+| Property                    | Type     | Effect                                                                  |
+| --------------------------- | -------- | ----------------------------------------------------------------------- |
+| `start` on `FallbackBefore` | `string` | From when the content before the period shows. Without it, from always. |
+| `end` on `FallbackAfter`    | `string` | Until when the content after the period shows. Without it, for good.    |

package/starter/02-components/04-tooltip.mdx

@@ -138,3 +138,12 @@ unnoticed for a long time. So does an unknown side.
 
 A tooltip explains a term without leaving the sentence. A remark that needs
 its own space is an [Admonition](./admonition/) instead.
+
+## Properties
+
+| Property    | Type     | Effect                                                             |
+| ----------- | -------- | ------------------------------------------------------------------ |
+| `text`      | `string` | Content of the bubble. Required: an empty bubble would never show. |
+| `placement` | `string` | `top`, the default, `bottom`, `left` or `right`.                   |
+| `className` | `string` | Classes added to the term.                                         |
+| `style`     | `object` | Inline styles on the term.                                         |

package/starter/02-components/05-tree.mdx

@@ -195,3 +195,16 @@ label is refused too.
 A tree is how this documentation shows the shape of a project. What those
 folders become once built — the order, the addresses — is in
 [Writing pages](../guide/writing-pages/).
+
+## Properties
+
+`TreeItem`:
+
+| Property    | Type            | Effect                                      |
+| ----------- | --------------- | ------------------------------------------- |
+| `label`     | text or element | What the line shows.                        |
+| `open`      | `boolean`       | Opens the branch as soon as the page opens. |
+| `className` | `string`        | Classes added to the line.                  |
+| `style`     | `object`        | Inline styles on the line.                  |
+
+`Tree` takes `className` and `style`.

package/starter/02-components/06-scroll-to-top.mdx

@@ -144,3 +144,13 @@ build is enough to keep it right.
 
 Setting one up takes a few lines in the pipeline that already builds the
 site: [Deployment](../guide/deployment/) has the recipe.
+
+## Properties
+
+| Property    | Type     | Effect                                                                                                        |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string` | Name read by a screen reader. By default, the words of the page's language — "Back to top", "Retour en haut". |
+| `className` | `string` | Classes added to the button.                                                                                  |
+| `style`     | `object` | Inline styles on the button.                                                                                  |
+
+Its children, when it has any, replace the arrow.

package/starter/02-components/07-skill.mdx

@@ -274,3 +274,19 @@ is full from the start — the value stays readable, which is what matters.
 A level outside 0–100 stops the build, as does a gauge without a name, a level
 that is not a number, or an unknown `shape`. A silent or overflowing bar goes
 unnoticed on review.
+
+## Properties
+
+| Property    | Type            | Effect                                                                         |
+| ----------- | --------------- | ------------------------------------------------------------------------------ |
+| `name`      | text or element | What is measured.                                                              |
+| `level`     | `number`        | The level, as a percentage.                                                    |
+| `showValue` | `boolean`       | Shows the percentage. On by default; off, the gauge still announces its value. |
+| `shape`     | `string`        | `bar`, the default, or `circle`.                                               |
+| `icon`      | element         | Shown before the name — a `LogoIcon` fits there.                               |
+| `color`     | `string`        | Colour of the fill: any CSS colour, the accent by default.                     |
+| `label`     | `string`        | Name for screen readers, when `name` is not text.                              |
+| `className` | `string`        | Classes added to the gauge.                                                    |
+| `style`     | `object`        | Inline styles on the gauge.                                                    |
+
+Its children stand as a comment under the gauge.

package/starter/02-components/08-logo-icon.mdx

@@ -171,3 +171,13 @@ A component loads no JavaScript, and this one is not going to introduce any.
 
 A kind of admonition takes its mark through this same component — see
 [Admonition](./admonition/).
+
+## Properties
+
+| Property    | Type     | Effect                                                                                  |
+| ----------- | -------- | --------------------------------------------------------------------------------------- |
+| `src`       | `string` | An SVG of the project, or `prefix:name` from an installed icon collection.              |
+| `label`     | `string` | What the icon means. Without it, the icon is decorative and hidden from screen readers. |
+| `size`      | `string` | Any CSS length.                                                                         |
+| `className` | `string` | Classes added to the icon.                                                              |
+| `style`     | `object` | Inline styles on the icon.                                                              |

package/starter/02-components/09-for-theme.mdx

@@ -46,3 +46,9 @@ without a word.
 
 Which theme a project runs is one field of its configuration, and the whole
 of what it changes is in [Themes](../guide/themes/).
+
+## Properties
+
+| Property    | Type     | Effect                                                           |
+| ----------- | -------- | ---------------------------------------------------------------- |
+| `framework` | `string` | `tailwind` or `custom`: the content shows only under that theme. |

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

@@ -74,3 +74,12 @@ themes, so this needs no variant:
 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.
+
+## Properties
+
+| Property    | Type     | Effect                                                                                                |
+| ----------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `of`        | `string` | `all`, the default; `series` for the sub-folders alone; `pages` for the pages beside the index alone. |
+| `from`      | `string` | Slug of another folder to list, instead of the one holding the page.                                  |
+| `className` | `string` | Classes added to the grid.                                                                            |
+| `style`     | `object` | Inline styles on the grid.                                                                            |

package/starter/02-components/11-menu.mdx

@@ -127,3 +127,25 @@ A `MenuLink` or a `MenuGroup` written outside a `Menu` stops the build, and so
 does an entry without a target or a group without a title. Each of these would
 otherwise render something that looks like a menu and leads nowhere — the kind
 of fault a review does not catch.
+
+## Properties
+
+`Menu`:
+
+| Property | Type     | Effect                                                                                                      |
+| -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `label`  | `string` | Name for screen readers, and label of the button it folds into. By default, the page's own word for a menu. |
+
+`MenuLink`:
+
+| Property | Type     | Effect                                            |
+| -------- | -------- | ------------------------------------------------- |
+| `href`   | `string` | Where it leads, resolved like any link. Required. |
+
+`MenuGroup`:
+
+| Property | Type     | Effect                          |
+| -------- | -------- | ------------------------------- |
+| `title`  | `string` | Heading of the group. Required. |
+
+All three take `className` and `style`.

package/starter/02-components/12-admonition.mdx

@@ -152,3 +152,12 @@ Its orphan branch keeps what was built, and the history keeps the sources.
 Like every component here, it is rendered at the build. It is an `aside`
 announced as a note, with its icon hidden from screen readers — the title
 beside it already says the kind, and saying it twice helps nobody.
+
+## Properties
+
+| Property    | Type     | Effect                                                                                                     |
+| ----------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `type`      | `string` | The kind: `note`, the default, `info`, `tip`, `attention`, `alert`, `danger`, or one the project declares. |
+| `title`     | `string` | Replaces the label of the kind, for this block alone.                                                      |
+| `className` | `string` | Classes added to the block.                                                                                |
+| `style`     | `object` | Inline styles on the block.                                                                                |

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

@@ -76,6 +76,7 @@ can change.
 | `sitemap`          | `true`              | `sitemap.xml` of the published versions, once `siteUrl` is set                                     |
 | `feed`             | `false`             | RSS feed of the dated pages. Needs `siteUrl`                                                       |
 | `search`           | `true`              | Search field in the header, and a search page built with the site                                  |
+| `llms`             | `false`             | `llms.txt` at the root of the site, and a Markdown copy of each page                               |
 
 ## Images
 
@@ -137,6 +138,38 @@ 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.
 
+## `llms`
+
+```js
+llms: true,
+```
+
+A program that reads documentation on someone's behalf — an assistant
+answering a question, a tool gathering the pages of a project — does better
+with the text than with the markup around it. `llms: true` gives it two ways
+in:
+
+- **`llms.txt`**, at the root of the site: the project name, the description
+  of the home page, then one link per page of the current version, with its
+  description. Each language of the version has its own section. The file
+  follows the llms.txt proposal, at the address programs look for it.
+- **A Markdown copy of each page**, beside its HTML: `/guide/install/` has its
+  copy at `/guide/install/index.html.md`, and every page names its copy in its
+  head, with `<link rel="alternate" type="text/markdown">`. The copy is the
+  source of the page as you wrote it, headed by its title and description.
+
+What a component draws at build time is not in the copy — a grid of cards,
+the file a snippet reads: it says what was written, not what was rendered.
+
+It needs no `siteUrl`: the links start from the root of the domain until the
+site has an address, and are absolute once it has one. Like the sitemap,
+`llms.txt` is written by the build of the whole site; `build <version>` alone
+writes the copies of that version only.
+
+It is off by default. It doubles the files of a version, and whether programs
+should read your pages is yours to decide. It is a proposal, not a standard:
+reading it is up to each program.
+
 ## `copyCode`
 
 `copyCode: true` puts a button on every block of code, which copies it.

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

@@ -571,6 +571,12 @@ humanised from their slug by `StructuredDataBuilder`.
 
 **Returns** `FoldedNode[]`
 
+### `MARKDOWN_COPY`
+
+`MARKDOWN_COPY`
+
+File a page's Markdown copy is written to, beside its HTML.
+
 ### `buildFeed`
 
 `buildFeed(pages, site)`
@@ -588,6 +594,25 @@ every page again at every build.
 
 **Returns** `string`
 
+### `buildLlms`
+
+`buildLlms(pages, site)`
+
+Builds `llms.txt`: the index of a documentation, for a reader that is a
+program.
+
+Follows the proposal as it stands: a title, a one-line summary, then a list
+of links, each to the Markdown copy of a page — the address of the page with
+`index.html.md` appended, since the pages are folders. A program reads that
+copy as the author wrote it, instead of prying the text out of the markup.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `pages` | `PublishedPage[]` | Pages of the version the site serves first. |
+| `site` | `{ projectName: string, summary?: string, base?: string }` | `base` makes each link absolute when the site has a public address, and root-relative otherwise. |
+
+**Returns** `string`
+
 ### `buildRobots`
 
 `buildRobots(sitemapUrl)`
@@ -616,6 +641,30 @@ that carries neither is listed without one rather than with a made-up date.
 
 **Returns** `string`
 
+### `markdownCopy`
+
+`markdownCopy(frontmatter, content, [resolve])`
+
+The Markdown copy of a page: its source, as the author wrote it.
+
+The title is added when the page does not open on one, since a program
+handed the copy alone has no frontmatter to read it from. What a component
+draws at build time is not in the copy — a snippet's file, a grid of cards:
+the copy says what was written, not what was rendered.
+
+The links are the exception. The build resolves them from the folder of the
+source file, and a version-root one from the version: read from where the
+copy is served, as written, they would lead nowhere. `resolve` gives each the
+address the HTML page carries.
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `frontmatter` | `{ title?: string, description?: string }` |  |
+| `content` | `string` | Source of the page, frontmatter removed. |
+| `[resolve]` | `(target: string) => string \| null` | Address of a target on the site, or `null` to keep it as written. |
+
+**Returns** `string`
+
 ### `buildAuthorTable`
 
 `buildAuthorTable(description, options)`

package/starter/05-whats-new.md

@@ -85,6 +85,16 @@ until the `ui` field gives it its own.
 
 [Languages](./guide/languages/) · [The init options](./reference/cli/)
 
+### Pages a program can read
+
+`llms: true` writes `llms.txt` at the root of the site — the project, then a
+link to every page of the current version — and a Markdown copy beside each
+page, `index.html.md`, that its head names. An assistant asked about your
+project reads the text you wrote rather than prying it out of the HTML. Off by
+default, and it needs no `siteUrl`.
+
+[The field](./reference/configuration/)
+
 ## For a 0.4 project
 
 Nothing to change: a 0.4 configuration builds as it is, and a site already in