docpensieve 0.5.0-beta.4 → 0.5.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.5.0-beta.4",
+  "version": "0.5.0-beta.5",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.5.0-beta.4",
-    "@docpensieve/core": "0.5.0-beta.4",
-    "@docpensieve/shared": "0.5.0-beta.4",
-    "@docpensieve/theme": "0.5.0-beta.4",
+    "@docpensieve/components": "0.5.0-beta.5",
+    "@docpensieve/core": "0.5.0-beta.5",
+    "@docpensieve/shared": "0.5.0-beta.5",
+    "@docpensieve/theme": "0.5.0-beta.5",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/starter/01-guide/05-themes.mdx

@@ -122,8 +122,10 @@ follows the reader's system; `'dark'` or `'light'` keeps one whatever the
 system — the build sets it as a class on `<html>`.
 
 The header also carries a button that switches between light and dark, and
-remembers the reader's choice from page to page — a few hundred bytes of inline
-script, the only one content pages carry. `theme.toggle: false` removes it.
+remembers the reader's choice from page to page — a few hundred bytes of
+script written into the page, the only script that is not a file of the site.
+A Content-Security-Policy allows it by its hash, which the
+[deployment guide](./deployment/) gives. `theme.toggle: false` removes it.
 Without JavaScript, the button does not show.
 
 The dark palette is a set of tokens, the same under both themes. To change it,

package/starter/01-guide/06-deployment.md

@@ -170,3 +170,37 @@ The build keeps it light on its own. The stylesheet is minified — a third to
 half lighter. Every image of a page gets its width and height, read from its
 file, so that the text does not jump when it arrives, and all but the first
 load lazily, when the reader nears them. There is nothing to configure.
+
+## A Content-Security-Policy
+
+A Content-Security-Policy tells the browser what a page may load and run, so
+that a script slipped into it is refused. A host that lets you set response
+headers can send one with the site, and the pages hold up under a strict one —
+one line in the header, split here to be read:
+
+```text
+default-src 'self';
+script-src 'self' 'sha256-9V5TjnZ1QZI4gqywFKZk0OWiHyt6/BX2XWMibvI5UKc=' 'sha256-uoMvfl2Wu3fqzsh38hLYURHzlNXf65BbRUVEBM5sots=';
+style-src 'self'; style-src-attr 'unsafe-inline';
+object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+```
+
+- **The two hashes** are the two scripts written into the page by the light /
+  dark button: one applies the reader's choice before the first paint, the
+  other runs the button. Their words come from the button itself, in the
+  language of the page, so the scripts are the same text on every page of
+  every site: the hashes do not change with your content. They change with the
+  tool — after an update, a refused script names in the browser console the
+  hash it expected. `theme.toggle: false` removes both scripts, and the hashes
+  with them.
+- **Every other script is a file of the site** — the client file of the
+  version, the search script and its index — which `'self'` covers.
+- **`style-src-attr 'unsafe-inline'`** is the one allowance. The code
+  highlighter colours each word with a `style` attribute, and some components
+  size themselves that way. It lets style attributes through, not `<style>`
+  elements, and a style attribute runs no code.
+
+This policy was checked in a browser against the pages of this site: search,
+copy buttons, calendars and the light / dark button all work, and nothing is
+refused. If your pages load anything from another address — an image, a font —
+add that address to the matching directive.

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

@@ -40,6 +40,18 @@ npx docpensieve check
   every other block.
 - **An error keeps its hint.** An error the tool raises while a page compiles
   no longer comes out as a generic syntax complaint.
+- **A setting that did nothing now stops the build.** `copyCode: 'yes'` turned
+  the button off in silence, and a `TimeTimer` with a `start` but no
+  `duration` hid its content; both now name what is wrong. Build once after
+  updating: that is where it shows.
+- **`ScrollToTop`, `Menu` and the light / dark button speak the language of
+  the page** when you give them no label of your own. A project that writes
+  its own words in `ui` gets two more to write: `switchToLight` and
+  `switchToDark`.
+- **A reader stays in their language from one version to another.** The
+  version switcher, the notice of a beta and the links of the header led a
+  French reader to the English pages; they now lead to the French ones
+  wherever they exist.
 
 ## What is worth turning on
 

package/starter/01-guide/10-languages.md

@@ -69,6 +69,23 @@ Nothing already published moves, which is the point: a link shared last year
 still leads where it led. The translation lives **inside** the version, so a
 version is still one folder, one orphan branch, one stylesheet.
 
+## Moving from one version to another
+
+The version switcher, the notice on a beta or an archive, and the links of the
+header lead to another version — in the reader's language when that version
+has the page in it, in the language of the site when it does not. A French
+reader of the beta who follows its notice lands on the French pages of the
+current version; a version never translated opens in the language it was
+written in, rather than on an address that leads nowhere.
+
+The links you write in a page stay in their language by themselves, as long as
+they are written from the page. A link that starts from the root of the
+version — `/guide/install/` — leads to the French page from a French page. A
+relative link climbs from the folder of its file, and the folders of a
+translation mirror those of the site language: write it as the twin page
+writes it. One level too many and it leaves the language, which `check` cannot
+see — the English page it lands on exists.
+
 ## A page nobody translated
 
 It does not exist in that language. It is absent from the menu of that

package/starter/02-components/03-time-timer.mdx

@@ -119,6 +119,11 @@ integration, whose time zone is not yours.
 A misspelt duration stops the build, and so does an invalid date. The message
 names the faulty value and recalls the expected format.
 
+So does a timer that names no period: no `date` at all, a `start` without its
+`duration`, a `duration` beside a `date`, or a `date` and a `start` together.
+Each of these used to show nothing, without a word — a block gone from the
+page, and nothing to say why.
+
 Announcing a release is what this is usually for, and [Versions](../guide/versions/)
 covers the rest of that cycle — the banner a prerelease carries on its own,
 and the day the two tracks swap.

package/starter/05-whats-new.md

@@ -95,6 +95,16 @@ default, and it needs no `siteUrl`.
 
 [The field](./reference/configuration/)
 
+### A strict Content-Security-Policy
+
+The light / dark button no longer writes its words into its script: they come
+from the page, in its language — a French page used to name the button in
+English to a screen reader. Its two scripts are then the same text on every
+page, and a Content-Security-Policy allows them by their hash. The deployment
+guide gives a strict policy, checked in a browser against this site.
+
+[The policy](./guide/deployment/)
+
 ## For a 0.4 project
 
 Nothing to change: a 0.4 configuration builds as it is, and a site already in