docpensieve 0.1.5 → 0.2.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.1.5",
+  "version": "0.2.0-beta.1",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.1.5",
-    "@docpensieve/core": "0.1.5",
-    "@docpensieve/shared": "0.1.5",
-    "@docpensieve/theme": "0.1.5",
+    "@docpensieve/components": "0.2.0-beta.1",
+    "@docpensieve/core": "0.2.0-beta.1",
+    "@docpensieve/shared": "0.2.0-beta.1",
+    "@docpensieve/theme": "0.2.0-beta.1",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"
@@ -45,7 +45,7 @@
     "url": "git+https://github.com/Juniors017/docpensieve.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/Juniors017/docpensieve#readme",
+  "homepage": "https://docpensieve.com",
   "bugs": {
     "url": "https://github.com/Juniors017/docpensieve/issues"
   },

package/src/commands/init.js

@@ -56,7 +56,7 @@ const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons', EXAMPLES_CSS]);
 const CUSTOM_CSS = fileURLToPath(new URL('../templates/custom.css', import.meta.url));
 
 /** Where the generated configuration sends readers for every field. */
-const DOCUMENTATION_URL = 'https://juniors017.github.io/docpensieve/';
+const DOCUMENTATION_URL = 'https://docpensieve.com/';
 
 /**
  * Asks a question, with a default value shown between brackets.
@@ -235,6 +235,7 @@ function renderConfig({ name, theme, siteUrl, version }) {
     "    // 'tailwind' compiles the utilities your pages use; 'custom' is a plain",
     '    // stylesheet with no dependency.',
     `    framework: ${quote(theme)},`,
+    "    // 'class' follows the reader's system; 'dark' or 'light' keeps one scheme.",
     "    darkMode: 'class',",
     '',
     '    // Design tokens to override, for instance the accent colour:',
@@ -256,7 +257,9 @@ function renderConfig({ name, theme, siteUrl, version }) {
       : []),
     '  },',
     '',
-    "  // 'auto': the menu follows the folders and the 01-, 02- prefixes.",
+    "  // 'auto': the menu follows the folders and the 01-, 02- prefixes. To write",
+    "  // it by hand, name a JSON file instead — 'sidebar.json' — read from each",
+    '  // version folder.',
     "  sidebar: 'auto',",
     '',
     '  // The shipped components — Card, Columns, Tooltip… — usable in any .mdx',
@@ -268,6 +271,21 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '',
     '  // Structured data (JSON-LD) generated from the frontmatter of each page.',
     '  jsonld: { enabled: true },',
+    '',
+    '  // sitemap.xml of the published versions, for search engines — written',
+    '  // once siteUrl is set. robots.txt joins it when the site is served at',
+    '  // the root of its domain.',
+    // Commented out until siteUrl is known: written explicitly, it asks for a
+    // sitemap that cannot be built yet, and the configuration refuses it.
+    siteUrl ? '  sitemap: true,' : '  // sitemap: true,',
+    '',
+    '  // RSS feed of the pages that carry a date, at the root of the site. It',
+    '  // needs siteUrl.',
+    '  feed: false,',
+    '',
+    '  // 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,',
     '};',
     '',
     '// Every field is described in the reference of the DocPensieve documentation:',

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

@@ -65,6 +65,30 @@ docs/v1.0/
     └── 01-card.mdx
 ```
 
+## Writing the menu by hand
+
+When the file tree does not give the menu you want, describe it in a JSON file
+of the version's folder, and name it in the configuration:
+
+```js
+// docpensieve.config.mjs
+sidebar: 'sidebar.json',
+```
+
+```json
+[
+  "/",
+  { "label": "Start here", "items": ["guide/installation", "guide/first-site"] },
+  { "auto": "components" },
+  { "label": "Repository", "href": "https://github.com/me/my-project" }
+]
+```
+
+A page is named by its path, as in its URL. `{ "auto": "components" }` keeps
+the automatic menu of a folder — the DocPensieve section stays whole that way.
+A page the file leaves out is still published, only off the menu. Every kind
+of entry is in the [`sidebar` reference](../reference/configuration/).
+
 ## Internal links
 
 Two spellings, two meanings:
@@ -92,6 +116,12 @@ An image sits next to the page and is written relatively:
 Files that are not pages are copied as is into the output, at the same
 relative place. The path is rewritten like a link.
 
+The build reads the width and height of each image from its file — PNG, JPEG,
+GIF, WebP or SVG — and writes them on the page: the browser keeps the room
+before the image arrives, instead of shifting the text when it does. Every
+image but the first loads lazily, when the reader nears it; the first, often in
+view, keeps its normal loading.
+
 ## Components
 
 In an `.mdx` page, the shipped components are used **without an import**:

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

@@ -122,3 +122,14 @@ result years later.
 
 The branch model answers this — each compiled version on its own orphan branch,
 with its history. See [Versions](./versions/).
+
+## Search engines and feed readers
+
+With `siteUrl` set, the build writes `sitemap.xml` at the root of the site —
+every published version, a version in preparation excepted. Give its address
+to the search engines you care about; `robots.txt` names it for them when the
+site sits at the root of its domain.
+
+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/).

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

@@ -190,7 +190,7 @@ carrying the caption.
         <div className="text-4xl font-semibold text-indigo-600">0</div>
         <div className="text-sm">bytes of JavaScript</div>
       </CardBody>
-      <CardFooter>on every delivered page</CardFooter>
+      <CardFooter>on every content page</CardFooter>
     </Card>
   </Column>
   <Column span={4}>
@@ -223,7 +223,7 @@ carrying the caption.
         <div className="figure">0</div>
         <div className="small">bytes of JavaScript</div>
       </CardBody>
-      <CardFooter>on every delivered page</CardFooter>
+      <CardFooter>on every content page</CardFooter>
     </Card>
   </Column>
   <Column span={4}>

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

@@ -93,7 +93,7 @@ The shipped components avoid that clipping wherever they can — a `Card` rounds
 the corners of its image one by one rather than clipping its content.
 
 The bubble does not close with the Escape key: listening for it would take a
-script, and the site loads none. It disappears when the pointer or the focus
+script, and content pages load none. It disappears when the pointer or the focus
 leaves the term.
 
 A `Tooltip` without text stops the build: a hover with no effect goes

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

@@ -146,5 +146,5 @@ folder: each one stops the build, naming the expected path. A missing icon
 would otherwise leave an empty box that nobody notices.
 
 The scripts and event handlers present in a file are removed before inlining.
-The produced site loads no JavaScript, and a component is not going to
-introduce any.
+Content pages load no JavaScript, and a component is not going to introduce
+any.

package/starter/02-components/index.mdx

@@ -75,7 +75,8 @@ changes the examples too.
 
 ## Without JavaScript
 
-The produced site loads no script. Whatever needs interaction therefore goes
+Content pages load no script — the search page alone does. Whatever needs
+interaction therefore goes
 through native elements or through CSS: `details` for expanding, a link for
 moving, `animation-timeline` for appearing on scroll.
 

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

@@ -49,22 +49,25 @@ can change.
 
 ## The fields
 
-| Field              | Default             | Effect                                                                      |
-| ------------------ | ------------------- | --------------------------------------------------------------------------- |
-| `projectName`      | `'Documentation'`   | Name shown in the header and in the JSON-LD                                 |
-| `siteUrl`          | `''`                | Public URL. Used for the `canonical` and the JSON-LD                        |
-| `baseUrl`          | `'/'`               | Deployment prefix. Derived from `siteUrl` when omitted                      |
-| `outDir`           | `'dist'`            | Output folder, relative to the root                                         |
-| `versions`         | `[]`                | At least one entry                                                          |
-| `theme`            | see below           | Styling                                                                     |
-| `sidebar`          | `'auto'`            | `'auto'`: the sidebar follows the file tree. The only value written so far  |
-| `globalComponents` | `true`              | Shipped components available without an import                              |
-| `scrollToTop`      | `true`              | Back-to-top button on every page                                            |
-| `jsonld`           | `{ enabled: true }` | Structured data                                                             |
-| `lang`             | `'en'`              | Language of the document, in `<html lang>`. The shell's labels stay English |
-| `logo`             | `''`                | Image beside the project name, in the header                                |
-| `favicon`          | `''`                | Icon of the browser tab: `.ico`, `.png` or `.svg`                           |
-| `socialImage`      | `''`                | Preview of a shared page. Needs `siteUrl`                                   |
+| Field              | Default             | Effect                                                                             |
+| ------------------ | ------------------- | ---------------------------------------------------------------------------------- |
+| `projectName`      | `'Documentation'`   | Name shown in the header and in the JSON-LD                                        |
+| `siteUrl`          | `''`                | Public URL. Used for the `canonical` and the JSON-LD                               |
+| `baseUrl`          | `'/'`               | Deployment prefix. Derived from `siteUrl` when omitted                             |
+| `outDir`           | `'dist'`            | Output folder, relative to the root                                                |
+| `versions`         | `[]`                | At least one entry                                                                 |
+| `theme`            | see below           | Styling                                                                            |
+| `sidebar`          | `'auto'`            | `'auto'`: the menu follows the file tree. Or a `.json` file of each version folder |
+| `globalComponents` | `true`              | Shipped components available without an import                                     |
+| `scrollToTop`      | `true`              | Back-to-top button on every page                                                   |
+| `jsonld`           | `{ enabled: true }` | Structured data                                                                    |
+| `lang`             | `'en'`              | Language of the document, in `<html lang>`. The shell's labels stay English        |
+| `logo`             | `''`                | Image beside the project name, in the header                                       |
+| `favicon`          | `''`                | Icon of the browser tab: `.ico`, `.png` or `.svg`                                  |
+| `socialImage`      | `''`                | Preview of a shared page. Needs `siteUrl`                                          |
+| `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                  |
 
 ## Images
 
@@ -87,6 +90,45 @@ version, under `assets/`, so that a version stays whole on its own branch.
 
 A declared image that does not exist stops the build, naming the field.
 
+## Sitemap and feed
+
+```js
+siteUrl: 'https://example.com',
+sitemap: true, // the default
+feed: true,
+```
+
+Once `siteUrl` is set, the build writes `sitemap.xml` at the root of the site:
+every page of every version, except a version in preparation, whose pages
+carry `noindex`. Each page is dated by its `modified` frontmatter, or failing
+that its `date`. `sitemap: false` turns it off.
+
+`robots.txt` joins it when the site is served at the root of its domain.
+Search engines only read that file there: under a sub-path, it would be
+written for nobody — declare the sitemap to them directly.
+
+`feed: true` writes `feed.xml`, an RSS feed of the pages of the current version
+that carry a `date`, newest first, and every page announces it in its head.
+It is off by default: most documentation pages carry no date.
+
+Both list absolute addresses: asked for without `siteUrl`, they stop the build.
+
+## Search
+
+`search: true`, the default, puts a search field in the header and builds a
+search page in each version, at `/search/`. The build writes the index of the
+version — the plain text of every page — and the search page already lists
+every page with its description.
+
+The field is a plain form that leads to that page: **content pages load no
+script**. The search page alone loads one, of a few kilobytes, which filters
+the list as you type, best matches first, with an excerpt of each. Without
+JavaScript, the page stays the full list of pages.
+
+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.
+
 ## `versions`
 
 ```js
@@ -96,14 +138,16 @@ versions: [
 ],
 ```
 
-| Field        | Role                                                             |
-| ------------ | ---------------------------------------------------------------- |
-| `slug`       | URL and branch identifier                                        |
-| `name`       | Label shown in the switcher                                      |
-| `folder`     | Source folder, relative to the root                              |
-| `current`    | Version served by default. At most one                           |
-| `archived`   | Version kept but no longer maintained. Banner, but stays indexed |
-| `prerelease` | Version in preparation. Banner **and** `noindex`                 |
+| Field        | Role                                                                          |
+| ------------ | ----------------------------------------------------------------------------- |
+| `slug`       | URL and branch identifier                                                     |
+| `name`       | Label shown in the switcher                                                   |
+| `folder`     | Source folder, relative to the root                                           |
+| `current`    | Version served by default. At most one                                        |
+| `archived`   | Version kept but no longer maintained. Banner, but stays indexed              |
+| `prerelease` | Version in preparation. Banner **and** `noindex`                              |
+| `logo`       | This version's logo, instead of the project's — a beta told apart at a glance |
+| `favicon`    | This version's favicon, instead of the project's                              |
 
 ## `theme`
 
@@ -117,13 +161,13 @@ theme: {
 },
 ```
 
-| Field       | Effect                                    |
-| ----------- | ----------------------------------------- |
-| `framework` | `'tailwind'` or `'custom'`                |
-| `darkMode`  | Dark theme strategy                       |
-| `tokens`    | Redefined `--dp-*` tokens                 |
-| `css`       | CSS appended to the produced stylesheet   |
-| `source`    | Stylesheet handed to the utility compiler |
+| Field       | Effect                                                                        |
+| ----------- | ----------------------------------------------------------------------------- |
+| `framework` | `'tailwind'` or `'custom'`                                                    |
+| `darkMode`  | `'class'` follows the reader's system; `'dark'` or `'light'` keeps one scheme |
+| `tokens`    | Redefined `--dp-*` tokens                                                     |
+| `css`       | CSS appended to the produced stylesheet                                       |
+| `source`    | Stylesheet handed to the utility compiler                                     |
 
 The available tokens are listed in [Themes](../guide/themes/).
 
@@ -132,6 +176,42 @@ 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`.
 
+## `sidebar`
+
+`'auto'` builds the menu from the file tree: folders become categories, and the
+`01-`, `02-` prefixes set the order. To write it by hand, name a JSON file:
+
+```js
+sidebar: 'sidebar.json',
+```
+
+It is read from **each version's folder** — `docs/v1.0/sidebar.json` — since
+each version has its own pages. It holds an array of entries, kept in the order
+written:
+
+```json
+[
+  "/",
+  { "label": "Guide", "page": "guide", "items": ["guide/installation", "guide/first-site"] },
+  { "page": "reference/cli", "label": "Commands" },
+  { "auto": "docpensieve" },
+  { "label": "Repository", "href": "https://github.com/me/my-project" }
+]
+```
+
+| Entry                           | What it gives                                                                   |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| `"guide/installation"`          | A page, by its path within the version, as in its URL — `"/"` for the home page |
+| `{ "page", "label" }`           | The same page, with a label of its own                                          |
+| `{ "label", "items", "page"? }` | A category, clickable when it names a page                                      |
+| `{ "label", "href" }`           | A link outside the site                                                         |
+| `{ "auto": "folder" }`          | The automatic menu of a folder: the DocPensieve section keeps its own this way  |
+
+A page left out stays published: it is only absent from the menu. A path that
+names no page, a page listed twice, or an entry of no known kind stops the
+build, naming the file and the paths close to the one written. The file itself
+is not published.
+
 ## `baseUrl`, and why you rarely write it
 
 A `siteUrl` with a sub-path already gives it: `https://example.com/my-project`

package/starter/03-reference/04-theme.md

@@ -25,13 +25,13 @@ theme: {
 },
 ```
 
-| Field       | Default                  | Effect                                                |
-| ----------- | ------------------------ | ----------------------------------------------------- |
-| `framework` | `'tailwind'`             | `'tailwind'` or `'custom'`                            |
-| `darkMode`  | `'class'`                | Dark theme strategy                                   |
-| `tokens`    | —                        | Redefined `--dp-*` tokens, merged with the provider's |
-| `css`       | `''`                     | CSS appended to the produced stylesheet               |
-| `source`    | `@import "tailwindcss";` | Stylesheet handed to the utility compiler             |
+| Field       | Default                  | Effect                                                                                                    |
+| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `framework` | `'tailwind'`             | `'tailwind'` or `'custom'`                                                                                |
+| `darkMode`  | `'class'`                | `'class'`: the reader's system, unless a class on `<html>` decides. `'dark'` or `'light'` sets that class |
+| `tokens`    | —                        | Redefined `--dp-*` tokens, merged with the provider's                                                     |
+| `css`       | `''`                     | CSS appended to the produced stylesheet                                                                   |
+| `source`    | `@import "tailwindcss";` | Stylesheet handed to the utility compiler                                                                 |
 
 `source` only concerns the `tailwind` provider: it is the entry stylesheet it
 compiles. Replacing it lets you add directives — a `@theme` block, for
@@ -98,6 +98,7 @@ the `dp-*` class below.
 | `footer`        | `dp-footer`               | Page footer                                     |
 | `scrollTop`     | `dp-scroll-top`           | Back-to-top button                              |
 | `scrollTopIcon` | `dp-scroll-top-icon`      | Arrow of that button                            |
+| `search`        | `dp-search`               | Search field of the header                      |
 
 A slot can carry **variants**, suffixed `--variant`: `column` gives
 `dp-column--span-8`, `skill` gives `dp-skill--circle`.