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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.3.0-beta.2",
+  "version": "0.4.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.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.4.0-beta.1",
+    "@docpensieve/core": "0.4.0-beta.1",
+    "@docpensieve/shared": "0.4.0-beta.1",
+    "@docpensieve/theme": "0.4.0-beta.1",
     "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,7 +99,7 @@ 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
+Coming from the 0.3, [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.
 

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

@@ -1,12 +1,12 @@
 ---
 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.
+description: Move a project from the latest version, the 0.3, to the 0.4 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:
+A project on the latest version — the 0.3 — builds with the 0.4 beta as it is:
 every new field is optional.
 
 ## Update
@@ -20,18 +20,5 @@ Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
 
 ## 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    |
+Nothing yet: the 0.4 has just opened. Each change is listed here as it lands,
+beside what it asks of a project already built on the 0.3.

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

@@ -1,13 +1,13 @@
 ---
-title: What's new in 0.3
-description: What the 0.3 brings, and what it changes for a 0.2 project.
+title: What's new in 0.4
+description: What the 0.4 brings, and what it changes for a 0.3 project.
 tags: [release]
 ---
 
-# What's new in 0.3
+# What's new in 0.4
 
 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
+while the version installed by default stays the 0.3, documented in the
 `latest` pages of this site:
 
 ```bash
@@ -16,25 +16,13 @@ npx docpensieve@beta init my-site
 
 ## Already there
 
-### Authors at the head of a page
+Nothing yet: the 0.4 has just opened, and its pages are still those of the 0.3.
+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.
 
-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.
+## For a 0.3 project
 
-### 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
-
-Nothing to change: a 0.2 configuration builds as it is.
+Nothing to change: a 0.3 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.