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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.4.0-beta.1",
+  "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.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",
+    "@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/07-migrate-to-beta.md

@@ -22,3 +22,6 @@ Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
 
 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

@@ -16,10 +16,20 @@ npx docpensieve@beta init my-site
 
 ## Already there
 
-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.
+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 menu that folds, and a panel of links in the header
+
+`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/).
 
 ## For a 0.3 project