docpensieve 0.4.0 → 0.5.0-beta.1

package/package.json

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

package/starter/01-guide/01-installation.md

@@ -99,8 +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.3, [Migrate from 0.3 to 0.4](./migrate-from-0-3/) says what
-changes on its own and what to check first.
+Coming from the 0.4, [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,41 @@
+---
+title: Migrate from latest to beta
+description: Move a project from the latest version, the 0.4, to the 0.5 beta — what changes on its own, and what to check.
+tags: [guide, migration]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Migrate from latest to beta
+
+A project on the latest version — the 0.4 — builds with the 0.5 beta as it is:
+every field the 0.5 adds is optional.
+
+## Update
+
+```bash
+npm install docpensieve@beta
+```
+
+Through `npx` alone, `npx docpensieve@beta` runs the beta. Going back is
+`npm install docpensieve@latest`.
+
+Read your site back once after the update — it is the cheapest check there is:
+
+```bash
+npx docpensieve build
+npx docpensieve check
+```
+
+## What changes on its own
+
+Nothing yet: the 0.5 has just opened. Each change is listed here as it lands,
+beside what it asks of a project already built on the 0.4.
+
+## What to check afterwards
+
+- **Your own CSS**, if the theme folder styles anything the beta touches.
+- **`npx docpensieve check`**, which reads the built site back and reports dead
+  links and invalid markup.

package/starter/05-whats-new.md

@@ -1,92 +1,30 @@
 ---
-title: What's new in 0.4
-description: What the 0.4 brings, and what it changes for a 0.3 project.
+title: What's new in 0.5
+description: What the 0.5 brings, and what it changes for a 0.4 project.
 tags: [release]
 ---
 
-# What's new in 0.4
+# What's new in 0.5
 
-The 0.4 is out, and installs by default:
+This version is **in preparation**. Its betas go out under the npm tag `beta`,
+while the version installed by default stays the 0.4, documented in the
+`latest` pages of this site:
 
 ```bash
-npx docpensieve init my-site
+npx docpensieve@beta init my-site
 ```
 
-Each feature below links to the guide and to the reference: this page gathers
-them, it is never the only place something is written.
+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.
 
-## What it brings
+## Already there
 
-The 0.4 turns on the navigation. A site of forty pages was asking its reader to
-scroll past what did not concern them; it can now fold its menu, carry its own
-links in the header, and set a passage apart in the middle of a page.
+Nothing yet: the 0.5 has just opened. Each feature is listed here as it
+arrives, beside what it asks of a project already built on the 0.4.
 
-### A menu that folds
+## For a 0.4 project
 
-`foldedSidebar: true` folds the categories of the documentation menu, and opens
-the branch the reader stands in. On a narrow screen the whole menu folds above
-the content, whatever that setting — nothing to configure for that one. See
-[Navigation](./guide/navigation/).
-
-### Links and panels in the header
-
-A `headerLinks` entry adds a link beside the version switcher. An entry
-carrying `columns` opens a **panel** of links instead of leading anywhere, so a
-site can navigate from the header alone, from the menu alone, or from both with
-different links. A `version` field points every version at a single one, which
-is how this site leads to its examples. See
-[Navigation](./guide/navigation/) and
-[the configuration reference](./reference/configuration/).
-
-### A header held, or not
-
-`stickyHeader` decides whether the header holds to the top of the screen or
-scrolls away with the page, giving its height back to the text. It stays held
-by default. See [Navigation](./guide/navigation/).
-
-### A menu of links, anywhere in a page
-
-The `Menu` component places a row of links where a page needs them — a summary
-at the top of a landing page, the chapters of a guide. Entries can be grouped
-under a title, and the row folds behind a button on a narrow screen, without a
-script. See [Menu](./components/menu/).
-
-### Blocks that stand apart
-
-`Admonition` sets a passage apart and says how to read it: `note`, `info`,
-`tip`, `attention`, `alert`, `danger`. A project declares **its own kinds** in
-the `admonitions` field — a label and a tone taken from the theme — so the list
-does not have to grow for a team to have the block it needs. See
-[Admonition](./components/admonition/).
-
-### Icons from a set
-
-`LogoIcon` accepts the name of an icon from a collection, written
-`simple-icons:github`, beside a file of your project. The set is a package your
-project installs and the drawing is placed in the page at the build, like any
-other icon: your reader downloads nothing, and no request leaves their browser.
-An admonition kind takes its mark the same way. See
-[LogoIcon](./components/logo-icon/).
-
-### A site in several languages
-
-A version declares the folder of each translation:
-
-```js
-versions: [
-  { slug: 'latest', name: '1.0', folder: 'docs/v1.0', current: true,
-    translations: { fr: 'docs/v1.0-fr' } },
-],
-```
-
-The language of the site keeps the addresses it has, and a translation is
-served under its code — `/versions/latest/fr/`. The shell follows: English and
-French ship with the tool, and the `ui` field corrects a word or adds a
-language. A page nobody translated is not offered in that language rather than
-served in another. See [Languages](./guide/languages/).
-
-## For a 0.3 project
-
-Nothing to change: a 0.3 configuration builds as it is, every new field being
-optional. [Migrate from 0.3 to 0.4](./guide/migrate-from-0-3/) lists what
-changes on its own, and what is worth turning on.
+Nothing to change: a 0.4 configuration builds as it is.
+[Migrate from latest to beta](./guide/migrate-to-beta/) lists what changes on
+its own, and what is worth turning on.

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

@@ -1,125 +0,0 @@
----
-title: Migrate from 0.3 to 0.4
-description: Move a project from the 0.3 to the 0.4 — what changes on its own, and what to turn on.
-tags: [guide, migration]
----
-
-# Migrate from 0.3 to 0.4
-
-A project on the 0.3 builds with the 0.4 as it is: every field the 0.4 adds is
-optional, and leaving them out keeps the site you have.
-
-## Update
-
-```bash
-npm install docpensieve@latest
-```
-
-Through `npx` alone, `npx docpensieve` already runs it.
-
-Read your site back once after the update — it is the cheapest check there is:
-
-```bash
-npx docpensieve build
-npx docpensieve check
-```
-
-## What changes on its own
-
-**On a narrow screen, the documentation menu now folds above the content**
-instead of standing open between the header and the text. Nothing to
-configure, and nothing to undo: on a wide screen the menu is unchanged.
-
-Nothing else moves. Your pages, your configuration and your theme folder are
-read exactly as before.
-
-## What is worth turning on
-
-Each of these is one line of `docpensieve.config.mjs`. None depends on
-another.
-
-### A menu that folds
-
-Past twenty or so pages, a menu that shows everything asks the reader to scroll
-past what does not concern them:
-
-```js
-foldedSidebar: true,
-```
-
-The categories fold, and the branch of the page being read opens on its own.
-A category that is also a page keeps its page as the first entry — the handle
-of a fold cannot be a link.
-
-### Links in the header
-
-```js
-headerLinks: [
-  { label: 'Blog', href: '/blog/' },
-  { label: 'Repository', href: 'https://example.com/repo' },
-],
-```
-
-A target starts from the root of a version, or is a full address. An entry
-carrying `columns` opens a panel instead of leading anywhere; `href` and
-`columns` together are refused, an entry doing one thing or the other.
-
-See [Navigation](./navigation/) for the panel and for what happens on a phone.
-
-### A header that scrolls away
-
-```js
-stickyHeader: false,
-```
-
-The header gives its height back to the text instead of holding to the top of
-the screen. It stays held by default.
-
-### Blocks that stand apart
-
-Six kinds ship — `note`, `info`, `tip`, `attention`, `alert`, `danger` — and
-need no configuration:
-
-```mdx
-<Admonition type="attention">Read this before upgrading.</Admonition>
-```
-
-Kinds of your own take a label and a tone:
-
-```js
-admonitions: {
-  review: { label: 'To review', tone: 'attention' },
-},
-```
-
-A kind nobody declared stops the build rather than rendering a block with no
-colour and no label. See [Admonition](../components/admonition/).
-
-### Icons from a set
-
-Beside a file of your project, `LogoIcon` accepts the name of an icon from a
-collection:
-
-```bash
-npm install --save-dev @iconify-json/simple-icons
-```
-
-```mdx
-<LogoIcon src="simple-icons:github" label="Repository" />
-```
-
-The set is read at the build and the drawing placed in the page: no request
-leaves your reader's browser. See [LogoIcon](../components/logo-icon/).
-
-## What to check afterwards
-
-- **Your own CSS**, if the theme folder styles the header or the menu: the
-  folded menu adds `details` and `summary` elements where there were only
-  links, and a static header no longer carries `position: sticky`.
-- **A link to a heading**, if you turned the sticky header off: the space kept
-  above an anchor goes away with it, which is the point.
-- **`npx docpensieve check`**, which reads the built site back and reports dead
-  links and invalid markup.
-
-None of this is required. A project that turns none of it on is a 0.3 project
-that happens to be running the 0.4.