docpensieve 0.1.3 → 0.1.5

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

@@ -76,6 +76,7 @@ the `dp-*` class below.
 | `skip`          | `dp-skip`                 | Skip link to the content                        |
 | `header`        | `dp-header`               | Site header                                     |
 | `brand`         | `dp-brand`                | Project name, in the header                     |
+| `brandLogo`     | `dp-brand-logo`           | Logo beside the project name                    |
 | `versions`      | `dp-versions`             | Version switcher                                |
 | `versionsList`  | `dp-versions-list`        | Open list of the switcher                       |
 | `shell`         | `dp-shell`                | Menu / content / table of contents grid         |
@@ -124,7 +125,8 @@ The delivered stylesheet is assembled from four pieces, in this order:
 | a skin or a bridge  | `custom.css`, or `tailwind-bridge.css`             |
 | the components' one | The `dp-*` rules of the shipped components         |
 
-Then comes what the project adds through `theme.css`.
+Then comes what the project adds: `theme.css`, then every `.css` file of its
+`theme/` folder, in name order.
 
 The layout is **never** duplicated in a provider: it lives in `structure.css`,
 which both share. A provider only takes care of the styling.
@@ -144,6 +146,6 @@ The `custom` theme has no utility layer: its stylesheets are in no layer, and
 therefore come before the component rules, which stay in the `components`
 layer.
 
-What `theme.css` adds is in no layer: without a layer, a rule wins over all
-those that have one. That is what lets you write a fix there without worrying
+What `theme.css` and the `theme/` folder add is in no layer: without a layer, a
+rule wins over all those that have one. That is what lets you write a fix there without worrying
 about specificity.

package/starter/examples.css

@@ -0,0 +1,156 @@
+/*
+ * Classes of the documentation's examples, for the custom theme.
+ *
+ * The custom theme loads no utility framework: the classes a page uses are
+ * written by the project. These are the ones DocPensieve's own pages use.
+ * "docpensieve init" installs this file as theme/99-docpensieve.css, next to
+ * the documentation in 99-docpensieve/: delete both together.
+ *
+ * Every colour comes from the --dp-* tokens, or is mixed with them, so that
+ * the examples follow the light and dark palettes.
+ */
+
+/* Sizes */
+
+.narrow {
+  max-inline-size: 24rem;
+}
+
+.full-height {
+  block-size: 100%;
+}
+
+/* Text */
+
+.centered {
+  text-align: center;
+}
+
+.small {
+  font-size: 0.875rem;
+}
+
+.large {
+  font-size: 1.5rem;
+}
+
+.caps {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.italic {
+  font-style: italic;
+}
+
+.muted {
+  color: var(--dp-text-soft);
+}
+
+.accent-text {
+  color: var(--dp-accent);
+}
+
+.figure {
+  font-size: 2.25rem;
+  font-weight: 600;
+  line-height: 1.2;
+  color: var(--dp-accent);
+}
+
+.label {
+  display: block;
+  margin-block: 0.5rem 0.25rem;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+/* Colours, for the text and the gauges alike */
+
+.green {
+  --dp-skill-color: #10b981;
+  color: #10b981;
+}
+
+.amber {
+  --dp-skill-color: #f59e0b;
+  color: #f59e0b;
+}
+
+/* Cards */
+
+.highlight {
+  border-color: var(--dp-accent);
+  background: var(--dp-accent-soft);
+}
+
+.warning {
+  border-color: #f59e0b;
+  background: color-mix(in oklab, #f59e0b 12%, var(--dp-bg));
+}
+
+.warning-title {
+  color: color-mix(in oklab, #d97706 70%, var(--dp-text));
+}
+
+.plain {
+  border: 0;
+  box-shadow: none;
+  background: transparent;
+}
+
+.flush {
+  padding-inline: 0;
+}
+
+/* Layout */
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.row.align-end {
+  align-items: flex-end;
+}
+
+.plain-list {
+  display: grid;
+  gap: 0.5rem;
+  padding-inline-start: 0;
+  list-style: none;
+}
+
+.wide-gap {
+  gap: 2.5rem;
+}
+
+/* Content that flows from one column to the next, as in a newspaper */
+
+.flow {
+  columns: 2;
+  column-gap: 1.5rem;
+}
+
+@media (min-width: 40rem) {
+  .flow {
+    columns: 3;
+  }
+}
+
+.flow > * {
+  break-inside: avoid;
+  margin-block-end: 1.5rem;
+}
+
+/* A back-to-top button placed in the text rather than fixed on the screen */
+
+.inline-button {
+  position: static;
+  display: inline-flex;
+  inline-size: auto;
+  box-shadow: none;
+  padding-inline: 1rem;
+}

package/types/theme.d.ts

@@ -4,14 +4,24 @@
  * @module docpensieve/theme
  */
 import { ThemeEngine } from '@docpensieve/theme';
+/**
+ * Reads the project's own stylesheets: every `.css` file of its `theme/`
+ * folder, in name order. None when the folder does not exist.
+ *
+ * @param {string} [rootDir] Project root.
+ * @returns {string[]} The contents of each file.
+ */
+export declare function projectCss(rootDir?: string): string[];
 /**
  * Mounts the ThemeEngine matching the declared framework.
  *
  * The CLI does this wiring: `core` deliberately ignores the `theme` package
  * and receives the engine by injection (ADR-002).
  *
- * Along the way, the class table is handed to the components: that is what
- * lets them ask for their class instead of hard-coding it (ADR-007).
+ * Along the way, the class table and the framework are handed to the
+ * components: that is what lets them ask for their class instead of
+ * hard-coding it (ADR-007), and lets `ForTheme` keep the variant of the active
+ * theme.
  *
  * @param {Record<string, any>} config Normalised configuration.
  * @param {string} [extraCss] CSS appended after the theme's — the look of the

package/starter/icons/blocks.svg

@@ -1,6 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
-  <rect x="3" y="3" width="7.5" height="7.5" rx="1.5" />
-  <rect x="13.5" y="3" width="7.5" height="7.5" rx="1.5" />
-  <rect x="3" y="13.5" width="7.5" height="7.5" rx="1.5" />
-  <rect x="13.5" y="13.5" width="7.5" height="7.5" rx="1.5" />
-</svg>

package/starter/icons/book.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-  <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20" />
-  <path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" />
-</svg>

package/starter/icons/branch.svg

@@ -1,6 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
-  <circle cx="6" cy="5" r="2.5" />
-  <circle cx="6" cy="19" r="2.5" />
-  <circle cx="18" cy="12" r="2.5" />
-  <path d="M6 7.5v9M8.5 5h5a4 4 0 0 1 4 4v.5" />
-</svg>

package/starter/icons/compass.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
-  <circle cx="12" cy="12" r="9" />
-  <path d="m15.5 8.5-2 5-5 2 2-5z" />
-</svg>

package/starter/icons/lightning.svg

@@ -1,3 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
-  <path d="M13 2 4 14h6l-1 8 9-12h-6z" />
-</svg>

package/starter/icons/list.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
-  <path d="M8 6h13M8 12h13M8 18h13" />
-  <path d="M3.5 6h.01M3.5 12h.01M3.5 18h.01" />
-</svg>

package/starter/icons/shield.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
-  <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
-  <path d="m9 12 2 2 4-4" />
-</svg>

package/starter/icons/star.svg

@@ -1,3 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
-  <path d="m12 2 2.9 6.26 6.85.7-5.1 4.6 1.44 6.72L12 16.9l-6.09 3.38 1.44-6.72-5.1-4.6 6.85-.7z" />
-</svg>

package/starter/index.mdx

@@ -1,244 +0,0 @@
----
-title: DocPensieve
-description: Static documentation site generator — Markdown and MDX in, runtime-free HTML out, one version per branch.
-layout: home
-authors: [Valentin Chevoleau]
-date: 2026-09-09
-tags: [home]
-draft: false
-
-jsonld:
-  type: TechArticle
-  breadcrumbs: false
----
-
-<div className="dp-hero">
-
-# DocPensieve
-
-Your Markdown and MDX files become a static site. No runtime to load, one version per branch, structured data derived from the frontmatter.
-
-<div className="dp-actions">
-
-[Get started](/guide/installation/) [See the components](/components/)
-
-</div>
-
-</div>
-
-<Columns>
-  <Column>
-    <Card className="h-full" href="/guide/">
-      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
-        <LogoIcon src="./icons/compass.svg" size="1.75rem" className="text-indigo-600" />
-        <strong className="block mt-3 mb-1 text-base font-semibold">Guide</strong>
-
-        From installation to deployment, in order.
-      </CardBody>
-    </Card>
-
-  </Column>
-  <Column>
-    <Card className="h-full" href="/components/">
-      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
-        <LogoIcon src="./icons/blocks.svg" size="1.75rem" className="text-indigo-600" />
-        <strong className="block mt-3 mb-1 text-base font-semibold">Components</strong>
-
-        Eight components usable without an import, none of them with JavaScript.
-      </CardBody>
-    </Card>
-
-  </Column>
-  <Column>
-    <Card className="h-full" href="/reference/">
-      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
-        <LogoIcon src="./icons/list.svg" size="1.75rem" className="text-indigo-600" />
-        <strong className="block mt-3 mb-1 text-base font-semibold">Reference</strong>
-
-        Commands, configuration, frontmatter and theme.
-      </CardBody>
-    </Card>
-
-  </Column>
-  <Column>
-    <Card className="h-full" href="/architecture/">
-      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
-        <LogoIcon src="./icons/branch.svg" size="1.75rem" className="text-indigo-600" />
-        <strong className="block mt-3 mb-1 text-base font-semibold">Architecture</strong>
-
-        How a page becomes HTML, and why it works that way.
-      </CardBody>
-    </Card>
-
-  </Column>
-</Columns>
-
-## In three commands
-
-<Columns>
-  <Column span={7}>
-
-```bash
-npx docpensieve init my-site
-cd my-site
-npx docpensieve dev
-```
-
-The first one sets up a configuration and a documentation folder, the last one
-opens a server that rebuilds on every save.
-
-Nothing else to install: the <Tooltip text="Turning the sources into HTML pages ready to serve.">build</Tooltip> runs on your machine, and the produced site only needs a file host.
-
-  </Column>
-  <Column span={5}>
-    <Card className="h-full">
-      <CardHeader>What you get</CardHeader>
-      <CardBody>
-        <Tree>
-          <TreeItem label="dist" open>
-            <TreeItem label="index.html" />
-            <TreeItem label="versions.json" />
-            <TreeItem label="versions" open>
-              <TreeItem label="v1.0">
-                <TreeItem label="index.html" />
-                <TreeItem label="assets" />
-              </TreeItem>
-            </TreeItem>
-          </TreeItem>
-        </Tree>
-      </CardBody>
-    </Card>
-  </Column>
-</Columns>
-
-## What it costs the reader
-
-<div className="flex flex-wrap justify-center gap-6 my-8">
-  <Skill
-    name="JavaScript"
-    level={0}
-    shape="circle"
-    color="#10b981"
-    icon={<LogoIcon src="./icons/lightning.svg" />}
-  />
-  <Skill
-    name="Hydration"
-    level={0}
-    shape="circle"
-    color="#10b981"
-    icon={<LogoIcon src="./icons/lightning.svg" />}
-  />
-  <Skill
-    name="HTML served as is"
-    level={100}
-    shape="circle"
-    color="#6366f1"
-    icon={<LogoIcon src="./icons/shield.svg" />}
-  />
-  <Skill
-    name="One stylesheet per version"
-    level={100}
-    shape="circle"
-    color="#6366f1"
-    icon={<LogoIcon src="./icons/book.svg" />}
-  />
-</div>
-
-Two dials at zero, and that is on purpose: React serves the **build**, not the
-display. What reaches the reader is markup and a stylesheet.
-
-## What sets the tool apart
-
-<Columns>
-  <Column span={6}>
-    <Card className="h-full">
-      <CardHeader>Nothing to load</CardHeader>
-      <CardBody className="text-sm">
-        No hydration, no bundle to download before reading. A page stays readable in ten years,
-        because there is nothing that can stop working.
-      </CardBody>
-    </Card>
-  </Column>
-  <Column span={6}>
-    <Card className="h-full">
-      <CardHeader>One version per branch</CardHeader>
-      <CardBody className="text-sm">
-        Each published version lives on its own orphan branch, with its history. Going back to an
-        old version does not require rebuilding it.
-      </CardBody>
-    </Card>
-  </Column>
-  <Column span={6}>
-    <Card className="h-full">
-      <CardHeader>The frontmatter is enough</CardHeader>
-      <CardBody className="text-sm">
-        Title, description, authors and dates produce the JSON-LD, the breadcrumb and the metadata.
-        Nothing to write twice.
-      </CardBody>
-    </Card>
-  </Column>
-  <Column span={6}>
-    <Card className="h-full">
-      <CardHeader>Nothing fails silently</CardHeader>
-      <CardBody className="text-sm">
-        An unknown value, a missing parent, a dead link: each one stops the build with a message and
-        a hint.
-      </CardBody>
-    </Card>
-  </Column>
-</Columns>
-
-## Quality, in figures
-
-<Columns>
-  <Column span={7}>
-
-These gauges are not decorative: they are the repository's own measurements,
-taken by hand — nothing updates them on its own. <Tooltip text="Share of lines executed by the test suite.">Coverage</Tooltip> and <Tooltip text="TypeScript checks the JSDoc of the source code and of the tests.">typing</Tooltip> are checked on every push.
-
-What is not measured does not improve — and what is not checked every time
-degrades.
-
-  </Column>
-  <Column span={5}>
-    <Skill name="Line coverage" level={97} color="#10b981" icon={<LogoIcon src="./icons/shield.svg" />} />
-    <Skill name="Branch coverage" level={87} color="#f59e0b" icon={<LogoIcon src="./icons/shield.svg" />} />
-    <Skill name="Typing of code and tests" level={100} color="#6366f1" icon={<LogoIcon src="./icons/star.svg" />} />
-  </Column>
-</Columns>
-
-## A page, end to end
-
-<Columns>
-  <Column span={5}>
-
-```mdx
----
-title: Installation
-description: Install the tool.
----
-
-# Installation
-
-Node.js 22 or later.
-
-<Tooltip text="Complete new project">init</Tooltip>
-sets up the configuration.
-```
-
-  </Column>
-  <Column span={7}>
-
-The file is read, its frontmatter detached, its content compiled to HTML.
-Components are rendered **at build time**: `Tooltip` becomes two elements and a
-style rule, without a line of script.
-
-The title feeds the `<title>` tag, the description the metadata, and both
-together the JSON-LD. The file name gives the URL, its folder the place in the
-menu.
-
-None of this needs configuration: [writing a page](/guide/writing-pages/) is
-enough.
-
-  </Column>
-</Columns>