docpensieve 0.3.0 → 0.4.0-beta.2

package/package.json

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

package/src/commands/init.js

@@ -284,6 +284,10 @@ function renderConfig({ name, theme, siteUrl, version }) {
     "  // on a narrow screen. For instance [{ label: 'Blog', href: '/blog/' }].",
     '  headerLinks: [],',
     '',
+    '  // Categories of the menu fold, opened on the branch of the page being',
+    '  // read. Useful once the documentation is long.',
+    '  foldedSidebar: false,',
+    '',
     '  // 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 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.
+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.
 
 ## Checking
 

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

@@ -0,0 +1,27 @@
+---
+title: Migrate from latest to beta
+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.3 — builds with the 0.4 beta as it is:
+every new field is optional.
+
+## Update
+
+```bash
+npm install docpensieve@beta
+```
+
+Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
+`npm install docpensieve@latest`.
+
+## What changes on its own
+
+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.
+
+One thing changes on its own: on a narrow screen, the menu of the documentation
+now folds above the content instead of standing open. Nothing to configure.

package/starter/01-guide/08-navigation.mdx

@@ -0,0 +1,126 @@
+---
+title: Navigation
+description: The menu of the documentation, the links of the header, and what becomes of both on a phone.
+tags: [guide, navigation]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Navigation
+
+A reader finds a page in one of two ways: the menu of the documentation, on the
+left, or the header, at the top. They answer different questions — _where am I
+in this documentation_ and _where else can I go_ — and a site may use one, the
+other, or both.
+
+Neither loads a script. Everything here folds and unfolds with native elements.
+
+## The menu of the documentation
+
+It follows the file tree, or the file you describe — that is
+[Writing the menu by hand](./writing-pages/). What changes here is how much of
+it shows at once.
+
+### Folding the categories
+
+```js
+// docpensieve.config.mjs
+foldedSidebar: true,
+```
+
+Every category becomes a fold. **The branch holding the page being read is
+open, the others closed**, so a menu of a hundred entries stops asking the
+reader to scroll past what does not concern them.
+
+<Columns>
+  <Column span={6}>
+    <Card style={{ height: '100%' }}>
+      <CardHeader>Unfolded — the default</CardHeader>
+      <CardBody>
+        Everything is visible at once. Right for a documentation of a few dozen pages, where
+        scrolling the menu costs nothing.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card style={{ height: '100%', borderColor: 'var(--dp-accent)' }}>
+      <CardHeader>Folded</CardHeader>
+      <CardBody>
+        Only the branch being read is open. Right once the menu is long enough that its end is out
+        of sight.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+A category that is also a page gains that page as its first entry. The handle
+of a fold cannot be a link as well — a click would mean two things, and the
+page would become unreachable.
+
+## The header
+
+`headerLinks` puts links beside the version switcher.
+
+```js
+headerLinks: [{ label: 'Blog', href: '/blog/' }],
+```
+
+A target starts from the root of a 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.
+
+### A section that lives in one version
+
+A link may name the version it leads to:
+
+```js
+{ label: 'Examples', href: '/examples/', version: 'latest' },
+```
+
+Every version then leads there, which is what keeps a section written in one
+version reachable from all of them. This site does exactly that for its
+examples.
+
+### A panel of links
+
+An entry carrying `columns` opens a panel instead of leading anywhere:
+
+```js
+{
+  label: 'Product',
+  columns: [
+    {
+      title: 'Guide',
+      items: [
+        { label: 'Installation', href: '/guide/installation/' },
+        { label: 'First site', href: '/guide/first-site/' },
+      ],
+    },
+    { items: [{ label: 'Repository', href: 'https://github.com/me/my-project' }] },
+  ],
+}
+```
+
+A column may go without a title. An entry cannot carry both `href` and
+`columns`: it either leads somewhere or opens a panel.
+
+The panel is declared here, **not derived from the menu of the documentation**.
+The two are therefore free to show different things — or a site without a
+sidebar can navigate from the header alone.
+
+## On a phone
+
+Nothing is left to overflow off the screen.
+
+| What                                   | Below 48rem                          | Below 56rem                                     |
+| -------------------------------------- | ------------------------------------ | ----------------------------------------------- |
+| Version switcher, links, panel, search | Behind the menu button of the header | —                                               |
+| Menu of the documentation              | —                                    | Folded above the content, behind its own button |
+
+The panel of links unfolds inside the header menu rather than over it, and the
+documentation menu starts closed: open, it would fill the first screen before a
+word is read.
+
+Both buttons are native elements. With JavaScript turned off, they still open.

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

@@ -60,6 +60,7 @@ can change.
 | `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                                   |
+| `foldedSidebar`    | `false`             | Categories of the menu fold, opened where the reader stands                        |
 | `globalComponents` | `true`              | Shipped components available without an import                                     |
 | `scrollToTop`      | `true`              | Back-to-top button on every page                                                   |
 | `jsonld`           | `{ enabled: true }` | Structured data                                                                    |
@@ -220,6 +221,52 @@ 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.
 
+### A panel of links
+
+An entry carrying `columns` opens a panel instead of leading anywhere:
+
+```js
+headerLinks: [
+  {
+    label: 'Product',
+    columns: [
+      {
+        title: 'Guide',
+        items: [
+          { label: 'Install', href: '/guide/installation/' },
+          { label: 'Deploy', href: '/guide/deployment/' },
+        ],
+      },
+      { items: [{ label: 'Repository', href: 'https://github.com/me/my-project' }] },
+    ],
+  },
+],
+```
+
+A column may go without a title. Every link follows the rules above — absolute
+target, optional `version`. An entry cannot carry both `href` and `columns`: it
+either leads somewhere or opens a panel, never both.
+
+The panel is declared here, not derived from the menu of the documentation: the
+two can stand side by side with different links, or the site can go without a
+sidebar and navigate from the header alone.
+
+## `foldedSidebar`
+
+```js
+foldedSidebar: true,
+```
+
+Every category of the menu becomes a fold. The branch holding the page being
+read is open, the others closed: a menu of a hundred pages stops asking the
+reader to scroll past what does not concern them. It folds without a script.
+
+A category that is also a page gains that page as its first entry: the handle
+of a fold cannot be a link as well without a click meaning two things.
+
+Left to `false`, the menu shows whole, as before. On a narrow screen the whole
+menu folds above the content either way, since the column has nowhere to stand.
+
 ## `sidebar`
 
 `'auto'` builds the menu from the file tree: folders become categories, and the

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

@@ -105,6 +105,13 @@ the `dp-*` class below.
 | `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                          |
+| `navGroup`      | `dp-nav-group`            | A folded category of the menu                   |
+| `navSummary`    | `dp-nav-summary`          | The handle of that fold                         |
+| `sidebarMenu`   | `dp-sidebar-menu`         | The documentation menu, on a narrow screen      |
+| `mega`          | `dp-mega`                 | A header entry that opens a panel               |
+| `megaPanel`     | `dp-mega-panel`           | That panel                                      |
+| `megaColumn`    | `dp-mega-column`          | A column of the panel                           |
+| `megaTitle`     | `dp-mega-title`           | The title of a column                           |
 | `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                                      |

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

@@ -443,6 +443,17 @@ humanised from their slug by `StructuredDataBuilder`.
 
 **Returns** `Record<string, string>` — Full folder slug to title.
 
+### `foldSidebar`
+
+`foldSidebar(nodes, [currentUrl])`
+
+| Parameter | Type | |
+| --- | --- | --- |
+| `nodes` | `SidebarNode[]` |  |
+| `[currentUrl]` | `string` | URL of the page being rendered. |
+
+**Returns** `FoldedNode[]`
+
 ### `buildFeed`
 
 `buildFeed(pages, site)`

package/starter/05-whats-new.md

@@ -1,61 +1,38 @@
 ---
-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 **out**. It is what `npx docpensieve init my-site` installs,
-and what the `latest` pages of this site document:
+This version is **in preparation**. Its betas go out under the npm tag `beta`,
+while the version installed by default stays the 0.3, documented in the
+`latest` pages of this site:
 
 ```bash
-npm install docpensieve@latest
+npx docpensieve@beta init my-site
 ```
 
-## What it brings
+## Already there
 
-### Authors at the head of a page
+The 0.4 has just opened. What follows is what it already brings, and the rest of
+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.
+### A menu that folds, and a panel of links in the header
 
-### Series and cards
+`foldedSidebar: true` folds the categories of the menu, open on the branch the
+reader stands in. On a narrow screen the whole menu folds above the content,
+whatever that setting. And a `headerLinks` entry carrying `columns` opens a
+panel of links instead of leading anywhere — declared on its own, so a site can
+navigate from the header alone, or from both. See
+[Navigation](./guide/navigation/) in the guide, and
+[the configuration reference](./reference/configuration/).
 
-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.3 project
 
-### 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 0.2 to 0.3](./guide/migrate-from-0-2/) lists what changes on
+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.

package/starter/01-guide/07-migrate-from-0-2.md

@@ -1,47 +0,0 @@
----
-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 0.2 to 0.3
-
-A project on the 0.2 builds with the 0.3 as it is: every new field is optional.
-
-## Update
-
-```bash
-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
-
-| 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.
-
-`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                                                 |
-| ---------------------------- | ----------------------------------------------------- |
-| `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    |