docpensieve 0.3.0-beta.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0",
   "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.2",
-    "@docpensieve/core": "0.3.0-beta.2",
-    "@docpensieve/shared": "0.3.0-beta.2",
-    "@docpensieve/theme": "0.3.0-beta.2",
+    "@docpensieve/components": "0.3.0",
+    "@docpensieve/core": "0.3.0",
+    "@docpensieve/shared": "0.3.0",
+    "@docpensieve/theme": "0.3.0",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/src/commands/init.js

@@ -47,10 +47,19 @@ const EXAMPLES_CSS = 'examples.css';
 
 /**
  * Entries of DocPensieve's documentation that are not installed with the
- * pages: its home page and the icons only that page uses belong to
- * DocPensieve's own site, and the examples' stylesheet has a place of its own.
+ * pages: its home page and the icons only that page uses, the example site
+ * and the author descriptions belong to DocPensieve's own site, and the
+ * examples' stylesheet has a place of its own. Installed, the author file
+ * would even be published as a plain file on every user's site.
  */
-const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons', EXAMPLES_CSS]);
+const NOT_INSTALLED = new Set([
+  'index.md',
+  'index.mdx',
+  'icons',
+  '06-examples',
+  'authors.json',
+  EXAMPLES_CSS,
+]);
 
 /** Starting point of the project's own stylesheet, under the custom theme. */
 const CUSTOM_CSS = fileURLToPath(new URL('../templates/custom.css', import.meta.url));
@@ -271,6 +280,10 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '  // names its frontmatter gives, without the rest.',
     "  authors: '',",
     '',
+    '  // Links of the header, beside the version switcher — behind a menu button',
+    "  // on a narrow screen. For instance [{ label: 'Blog', href: '/blog/' }].",
+    '  headerLinks: [],',
+    '',
     '  // 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.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.
+Coming from the 0.2, [Migrate from 0.2 to 0.3](./migrate-from-0-2/) 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.
 
 ## Checking
 

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

@@ -26,8 +26,9 @@ tags: [guide, installation]
 ```
 
 `title` becomes the `<title>` tag, the menu entry and the breadcrumb.
-`description` feeds the metadata and the JSON-LD. Everything is optional:
-without `title`, the project name stands in.
+`description` feeds the metadata and the JSON-LD. `tags` show at the bottom of
+the page, below the text they describe — one tag may be written without
+brackets. Everything is optional: without `title`, the project name stands in.
 
 The fields are detailed in the [reference](../reference/frontmatter/).
 
@@ -62,7 +63,8 @@ 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.
+text does not jump when they arrive. A version without the file shows the
+names alone: an older version needs no copy of it.
 
 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:
@@ -105,6 +107,23 @@ docs/v1.0/
     └── 01-card.mdx
 ```
 
+## Series of pages
+
+A folder is a **series**: its `index` page introduces it, and the pages beside
+that index are its instalments. Written in that index, one line builds the grid
+of its pages, as clickable cards:
+
+```mdx
+<Cards />
+```
+
+Each card takes the `title` and `description` of its page, its `preview` as an
+image, and its `modified` date. On the index of a folder that holds other
+folders, the cards of those series also count their pages. Nothing is listed
+by hand, so nothing goes stale when a page is added or renamed.
+
+The [Cards](../components/cards/) page details every option.
+
 ## Writing the menu by hand
 
 When the file tree does not give the menu you want, describe it in a JSON file
@@ -126,8 +145,10 @@ sidebar: 'sidebar.json',
 
 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/).
+A page the file leaves out is still published, only off the menu, and a
+version without the file keeps the menu of its folders — an older version
+needs no copy of it. Every kind of entry is in the
+[`sidebar` reference](../reference/configuration/).
 
 ## Internal links
 

package/starter/01-guide/{07-migrate-to-beta.md → 07-migrate-from-0-2.md}

@@ -1,22 +1,21 @@
 ---
-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.
+title: Migrate from 0.2 to 0.3
+description: Move a project from the 0.2 to the 0.3 — what changes on its own, and what to turn on.
 tags: [guide, migration]
 ---
 
-# Migrate from latest to beta
+# Migrate from 0.2 to 0.3
 
-A project on the latest version — the 0.2 — builds with the 0.3 beta as it is:
-every new field is optional.
+A project on the 0.2 builds with the 0.3 as it is: every new field is optional.
 
 ## Update
 
 ```bash
-npm install docpensieve@beta
+npm install docpensieve@latest
 ```
 
-Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
-`npm install docpensieve@latest`.
+Through `npx` alone, `npx docpensieve` fetches the 0.3 by itself. Going back is
+`npm install docpensieve@0.2.0`.
 
 ## What changes on its own
 
@@ -29,6 +28,17 @@ 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.
 
+`tags` follows the same path: read until now only by the page data, it now
+shows at the bottom of every page that carries it.
+
+One constraint is gone, too. A `sidebar` or `authors` file named in the
+configuration no longer has to exist in every version folder: a version
+without it keeps the menu of its folders, or shows the names alone.
+
+On a narrow screen, the header changes for every site: the version switcher and
+the search field move behind a menu button. Nothing to configure — `headerLinks`
+only adds links to that menu.
+
 ## What to turn on
 
 | Field                        | Gives                                                 |

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

@@ -58,6 +58,8 @@ can change.
 | `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 |
+| `authors`          | `''`                | A `.json` file describing the authors, in each version folder that has one         |
+| `headerLinks`      | `[]`                | Links of the header, beside the version switcher                                   |
 | `globalComponents` | `true`              | Shipped components available without an import                                     |
 | `scrollToTop`      | `true`              | Back-to-top button on every page                                                   |
 | `jsonld`           | `{ enabled: true }` | Structured data                                                                    |
@@ -187,12 +189,37 @@ 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.
+rest: the file enriches, it does not command. A version without the file shows
+the names alone, so describing the authors of a new version does not force a
+copy into the older ones. A file present but unreadable, or wrongly written,
+stops the build.
 
 The file is not published. The avatars are, their path starting at the version
 folder so that they travel with it.
 
+## `headerLinks`
+
+```js
+headerLinks: [
+  { label: 'Blog', href: '/blog/' },
+  { label: 'Examples', href: '/examples/', version: 'beta' },
+  { label: 'Repository', href: 'https://github.com/me/my-project' },
+],
+```
+
+Links of the header, beside the version switcher. A target starts from the root
+of the version — `/blog/` — or is a full address. A relative target is refused:
+the header is on every page, and `blog/` would mean something else on each.
+
+`version` names the version a link leads to. Without it, each version links to
+its own page; with it, every version leads to that one — which is how a section
+written in one version only stays reachable from all of them. A version nobody
+declared stops the build.
+
+On a narrow screen, the version switcher, the links and the search field move
+behind a menu button. It is a native element that opens without a script, like
+the version switcher itself.
+
 ## `sidebar`
 
 `'auto'` builds the menu from the file tree: folders become categories, and the
@@ -203,8 +230,9 @@ 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:
+each version has its own pages. A version without the file keeps the menu of
+its folders, so a menu written for a new version needs no copy in the older
+ones. The file holds an array of entries, kept in the order written:
 
 ```json
 [

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

@@ -45,7 +45,7 @@ jsonld:
 | `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`                                       |
+| `tags`        | Shown at the bottom of the page, and carried over as JSON-LD `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`                                                  |

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

@@ -101,6 +101,19 @@ the `dp-*` class below.
 | `scrollTopIcon` | `dp-scroll-top-icon`      | Arrow of that button                            |
 | `search`        | `dp-search`               | Search field of the header                      |
 | `schemeToggle`  | `dp-scheme-toggle`        | Light / dark button of the header               |
+| `headerNav`     | `dp-header-nav`           | Versions, links and search, in a row            |
+| `headerLinks`   | `dp-header-links`         | Links of the header                             |
+| `menu`          | `dp-menu`                 | Menu button, on a narrow screen                 |
+| `menuPanel`     | `dp-menu-panel`           | What that button opens                          |
+| `byline`        | `dp-byline`               | Authors and dates at the head of a page         |
+| `bylineAuthors` | `dp-byline-authors`       | List of the authors                             |
+| `bylineAuthor`  | `dp-byline-author`        | One author                                      |
+| `bylineAvatar`  | `dp-byline-avatar`        | Avatar of an author                             |
+| `bylineName`    | `dp-byline-name`          | Name of an author                               |
+| `bylineBio`     | `dp-byline-bio`           | Biography of an author                          |
+| `bylineDates`   | `dp-byline-dates`         | Writing and update dates                        |
+| `tags`          | `dp-tags`                 | Tags at the bottom of a page                    |
+| `tag`           | `dp-tag`                  | One tag                                         |
 
 A slot can carry **variants**, suffixed `--variant`: `column` gives
 `dp-column--span-8`, `skill` gives `dp-skill--circle`.

package/starter/05-whats-new.md

@@ -6,15 +6,14 @@ tags: [release]
 
 # What's new in 0.3
 
-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:
+This version is **out**. It is what `npx docpensieve init my-site` installs,
+and what the `latest` pages of this site document:
 
 ```bash
-npx docpensieve@beta init my-site
+npm install docpensieve@latest
 ```
 
-## Already there
+## What it brings
 
 ### Authors at the head of a page
 
@@ -33,8 +32,30 @@ 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/).
 
+### Tags at the bottom of a page
+
+The `tags` of a page, read until now only by its structured data, show at the
+bottom of the page, below the text they describe. See
+[The frontmatter](./guide/writing-pages/) in the guide.
+
+### Description files, optional per version
+
+A `sidebar` or `authors` file named in the configuration no longer has to
+exist in every version folder. A version without it keeps the menu of its
+folders, or shows the names its pages give: describing the menu or the authors
+of a new version no longer forces a copy into the older ones. A file present
+but unreadable, or wrongly written, still stops the build.
+
+### Header links, and a menu on narrow screens
+
+`headerLinks` adds links to the header, beside the version switcher — each may
+name the version it leads to, so that a section written in one version is
+reachable from all of them. On a narrow screen, the switcher, the links and the
+search field move behind a menu button, which opens without a script. See the
+[`headerLinks` field](./reference/configuration/).
+
 ## For a 0.2 project
 
 Nothing to change: a 0.2 configuration builds as it is.
-[Migrate from latest to beta](./guide/migrate-to-beta/) lists what changes on
+[Migrate from 0.2 to 0.3](./guide/migrate-from-0-2/) lists what changes on
 its own, what to check, and what is worth turning on.