docpensieve 0.1.3 → 0.1.4

package/starter/02-components/02-columns.mdx

@@ -81,6 +81,10 @@ produce nothing visible, and the error would take a long time to find.
 independent settings. The grid subtracts the gaps by itself, so spacing the
 columns distorts no width.
 
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, a `gap-*` utility sets it:
+
 <Columns className="gap-10">
   <Column>
     <Card>
@@ -98,6 +102,37 @@ columns distorts no width.
 <Columns className="gap-10">…</Columns>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own sets it — here `wide-gap`, from
+`theme/99-docpensieve.css`:
+
+<Columns className="wide-gap">
+  <Column>
+    <Card>
+      <CardBody>The gap widens</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card>
+      <CardBody>without touching the widths</CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns className="wide-gap">…</Columns>
+```
+
+```css
+.wide-gap {
+  gap: 2.5rem;
+}
+```
+
+</ForTheme>
+
 ## An aside next to the text
 
 The most useful layout in documentation: the main point wide, the remark
@@ -115,9 +150,15 @@ class table is announced to them.
 
   </Column>
   <Column span={4}>
-    <Card className="h-full border-indigo-400 bg-indigo-50 dark:bg-indigo-950/30">
-      <CardHeader className="text-sm">Remember</CardHeader>
-      <CardBody className="text-sm">
+    <Card
+      style={{
+        height: '100%',
+        borderColor: 'var(--dp-accent)',
+        background: 'var(--dp-accent-soft)',
+      }}
+    >
+      <CardHeader style={{ fontSize: '0.875rem' }}>Remember</CardHeader>
+      <CardBody style={{ fontSize: '0.875rem' }}>
         A component that produces a URL resolves it itself, following the same rules as a
         Markdown link.
       </CardBody>
@@ -159,8 +200,12 @@ versions: [
 ## Letting content flow
 
 For a text or a gallery that _flows_ from one column to the next, the grid is
-not the right tool and no component is needed: the theme's utilities are
-enough, directly in the page.
+not the right tool and no component is needed: CSS multi-column is enough,
+directly in the page.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, its utilities write it:
 
 <div className="columns-2 gap-6 sm:columns-3">
   <Card className="mb-6 break-inside-avoid">
@@ -184,6 +229,54 @@ enough, directly in the page.
 <div className="columns-2 gap-6 sm:columns-3">…</div>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own — here `flow`, from
+`theme/99-docpensieve.css`:
+
+<div className="flow">
+  <Card>
+    <CardBody>One</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Two, a little longer, so that the heights differ.</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Three</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Four</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Five</CardBody>
+  </Card>
+</div>
+
+```mdx
+<div className="flow">…</div>
+```
+
+```css
+.flow {
+  columns: 2;
+  column-gap: 1.5rem;
+}
+
+@media (min-width: 40rem) {
+  .flow {
+    columns: 3;
+  }
+}
+
+.flow > * {
+  break-inside: avoid;
+  margin-block-end: 1.5rem;
+}
+```
+
+</ForTheme>
+
 The difference is there: above, the order is vertical and the browser
 distributes as it likes; with `Columns`, each block stays where you put it.
 

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

@@ -93,7 +93,7 @@ months.
 
 An announcement banner that removes itself:
 
-<Card className="border-indigo-400 bg-indigo-50 dark:bg-indigo-950/30">
+<Card style={{ borderColor: 'var(--dp-accent)', background: 'var(--dp-accent-soft)' }}>
   <CardBody>
     <TimeTimer start="01/01/2020" duration="36500d">
       **Version 1.1 in preparation.** New features are written in this version.

package/starter/02-components/05-tree.mdx

@@ -46,7 +46,7 @@ children** is a collapsible branch, an entry **without children** is a leaf.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Closed by default</CardHeader>
       <CardBody>
         <Tree>
@@ -58,7 +58,7 @@ children** is a collapsible branch, an entry **without children** is a leaf.
     </Card>
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Opened by `open`</CardHeader>
       <CardBody>
         <Tree>
@@ -146,12 +146,42 @@ well.
 
 ## Styling the tree
 
+<ForTheme framework="tailwind">
+
 <Tree className="text-indigo-700 dark:text-indigo-300">
   <TreeItem label="in colour" open>
     <TreeItem label="the children inherit" />
   </TreeItem>
 </Tree>
 
+```mdx
+<Tree className="text-indigo-700 dark:text-indigo-300">…</Tree>
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
+A class of your own colours it — here `accent-text`, from
+`theme/99-docpensieve.css`, which follows the palette in dark mode too:
+
+<Tree className="accent-text">
+  <TreeItem label="in colour" open>
+    <TreeItem label="the children inherit" />
+  </TreeItem>
+</Tree>
+
+```mdx
+<Tree className="accent-text">…</Tree>
+```
+
+```css
+.accent-text {
+  color: var(--dp-accent);
+}
+```
+
+</ForTheme>
+
 ## What it does not announce
 
 The structure is a nested list, not a `role="tree"`. That role promises a

package/starter/02-components/06-scroll-to-top.mdx

@@ -31,6 +31,8 @@ scrollToTop: false,
 text**, with its own content — a pointer at the end of a chapter, for
 instance.
 
+<ForTheme framework="tailwind">
+
 <div className="flex flex-wrap items-center gap-3">
   <ScrollToTop className="!static !inline-flex !w-auto !shadow-none px-4" label="Top of page">
     Top
@@ -59,6 +61,44 @@ All three carry `!static`: that is what takes them out of the corner of the
 screen to set them in the text. **Without this class, they would stack** on
 top of the shell's button, all in the same place.
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<div className="row">
+  <ScrollToTop className="inline-button" label="Top of page">
+    Top
+  </ScrollToTop>
+  <ScrollToTop className="inline-button" label="Back to the summit">
+    ↑ Summit
+  </ScrollToTop>
+  <ScrollToTop className="inline-button accent-text" label="Start reading again">
+    Start again
+  </ScrollToTop>
+</div>
+
+```mdx
+<ScrollToTop className="inline-button" label="Top of page">
+  Top
+</ScrollToTop>
+```
+
+```css
+.inline-button {
+  position: static;
+  display: inline-flex;
+  inline-size: auto;
+  box-shadow: none;
+  padding-inline: 1rem;
+}
+```
+
+All three carry `inline-button`, from `theme/99-docpensieve.css`: its
+`position: static` takes them out of the corner of the screen to set them in
+the text. **Without this class, they would stack** on top of the shell's
+button, all in the same place.
+
+</ForTheme>
+
 The accessible name stays set by `label`: without it, the link would announce
 itself by its appearance alone.
 

package/starter/02-components/07-skill.mdx

@@ -31,7 +31,7 @@ Content passed as a child becomes a comment under the bar.
 `shape="circle"` draws a dial rather than a bar. Useful when the gauges are
 few and you want them to stand out.
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill name="Accessibility" level={85} shape="circle" />
   <Skill name="Performance" level={92} shape="circle" />
   <Skill name="Coverage" level={64} shape="circle" />
@@ -53,7 +53,9 @@ the entry animation only has to start from zero.
 
 It is set through `--dp-skill-size`, on the gauge or on what surrounds it.
 
-<div className="flex flex-wrap items-end" style={{ '--dp-skill-size': '4rem' }}>
+<div
+  style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'flex-end', '--dp-skill-size': '4rem' }}
+>
   <Skill name="Smaller" level={70} shape="circle" />
   <Skill name="Also smaller" level={45} shape="circle" />
 </div>
@@ -72,7 +74,7 @@ It is set through `--dp-skill-size`, on the gauge or on what surrounds it.
 
 ### Without the figure
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill name="Silent" level={55} shape="circle" showValue={false} />
 </div>
 
@@ -96,7 +98,7 @@ seeing them match helps read a column of gauges at a glance.
 
 ### As a circle too
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill
     name="Speed"
     level={92}
@@ -161,7 +163,7 @@ Several gauges in columns, each in its card.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Quality</CardHeader>
       <CardBody>
         <Skill name="Tests" level={88} />
@@ -171,7 +173,7 @@ Several gauges in columns, each in its card.
     </Card>
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Delivery</CardHeader>
       <CardBody>
         <Skill name="Continuous integration" level={100} />
@@ -186,20 +188,50 @@ Several gauges in columns, each in its card.
 
 ## Styling the gauge
 
+<ForTheme framework="tailwind">
+
 The component classes live below the utilities: a `className` set at use wins.
 
 <Skill className="max-w-sm" name="Reduced width" level={55} />
 
-<div className="[&_.dp-skill-fill]:bg-emerald-500">
-  <Skill name="Green fill" level={78} />
-</div>
+The gauge takes its colour from `--dp-skill-color`, which an arbitrary
+property sets:
+
+<Skill className="[--dp-skill-color:#10b981]" name="Green fill" level={78} />
 
 ```mdx
-<div className="[&_.dp-skill-fill]:bg-emerald-500">
-  <Skill name="Green fill" level={78} />
-</div>
+<Skill className="[--dp-skill-color:#10b981]" name="Green fill" level={78} />
 ```
 
+A selector written in a class, such as `[&_.dp-skill-fill]:…`, would not do:
+its `&` reaches the HTML as `&amp;`, and the stylesheet — compiled from the
+rendered pages — never receives the rule.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+The component classes live in the `components` layer, those of the theme
+folder in none: a class of yours set at use wins. The gauge takes its colour
+from `--dp-skill-color`, which a class can set — here `narrow` and `green`,
+from `theme/99-docpensieve.css`:
+
+<Skill className="narrow" name="Reduced width" level={55} />
+
+<Skill className="green" name="Green fill" level={78} />
+
+```mdx
+<Skill className="green" name="Green fill" level={78} />
+```
+
+```css
+.green {
+  --dp-skill-color: #10b981;
+  color: #10b981;
+}
+```
+
+</ForTheme>
+
 ## The fill
 
 It animates as it enters the viewport, through `animation-timeline: view()`,

package/starter/02-components/08-logo-icon.mdx

@@ -27,6 +27,8 @@ folder. Nothing can leave it: a page does not read the rest of the machine.
 
 Placed in a text, the icon takes its size and colour.
 
+<ForTheme framework="tailwind">
+
 <div className="text-indigo-600 text-2xl">
   <LogoIcon src="./icons/star.svg" /> at the size and colour of the text
 </div>
@@ -35,38 +37,64 @@ Placed in a text, the icon takes its size and colour.
   <LogoIcon src="./icons/star.svg" /> and here, smaller and greyer
 </div>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<div className="accent-text large">
+  <LogoIcon src="./icons/star.svg" /> at the size and colour of the text
+</div>
+
+<div className="small muted">
+  <LogoIcon src="./icons/star.svg" /> and here, smaller and greyer
+</div>
+
+</ForTheme>
+
 ## Sizes
 
 `size` accepts any CSS length.
 
-<div className="flex items-end gap-4 text-emerald-600">
+<div style={{ display: 'flex', alignItems: 'flex-end', gap: '1rem', color: '#10b981' }}>
   <LogoIcon src="./icons/shield.svg" size="1rem" />
   <LogoIcon src="./icons/shield.svg" size="2rem" />
   <LogoIcon src="./icons/shield.svg" size="3rem" />
   <LogoIcon src="./icons/shield.svg" size="4rem" />
 </div>
 
+<ForTheme framework="tailwind">
+
+```mdx
+<LogoIcon src="./icons/shield.svg" size="3rem" style={{ color: '#10b981' }} />
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
 ```mdx
-<LogoIcon src="./icons/shield.svg" size="3rem" className="text-emerald-600" />
+<LogoIcon src="./icons/shield.svg" size="3rem" className="green" />
 ```
 
+`green` comes from `theme/99-docpensieve.css`, and sets `color`.
+
+</ForTheme>
+
 The colour only follows if the file relies on `currentColor` rather than on a
 fixed colour.
 
 ## In a list
 
-<ul className="list-none pl-0 space-y-2">
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/lightning.svg" size="1.1rem" className="text-amber-500" /> No script to
+<ul style={{ listStyle: 'none', paddingInlineStart: 0, display: 'grid', gap: '0.5rem' }}>
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/lightning.svg" size="1.1rem" style={{ color: '#f59e0b' }} /> No script to
     load
   </li>
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/shield.svg" size="1.1rem" className="text-emerald-600" /> Links are read
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/shield.svg" size="1.1rem" style={{ color: '#10b981' }} /> Links are read
     back before publishing
   </li>
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/book.svg" size="1.1rem" className="text-indigo-600" /> One version per
-    branch
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/book.svg" size="1.1rem" style={{ color: 'var(--dp-accent)' }} /> One
+    version per branch
   </li>
 </ul>
 
@@ -74,10 +102,10 @@ fixed colour.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardBody>
-        <LogoIcon src="./icons/lightning.svg" size="1.6rem" className="text-amber-500" />
-        <strong className="block mt-2 mb-1 text-base font-semibold">Fast</strong>
+        <LogoIcon src="./icons/lightning.svg" size="1.6rem" style={{ color: '#f59e0b' }} />
+        <strong style={{ display: 'block', margin: '0.5rem 0 0.25rem', fontSize: '1rem' }}>Fast</strong>
 
         No hydration, no bundle to download before reading.
       </CardBody>
@@ -85,10 +113,10 @@ fixed colour.
 
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardBody>
-        <LogoIcon src="./icons/shield.svg" size="1.6rem" className="text-emerald-600" />
-        <strong className="block mt-2 mb-1 text-base font-semibold">Verified</strong>
+        <LogoIcon src="./icons/shield.svg" size="1.6rem" style={{ color: '#10b981' }} />
+        <strong style={{ display: 'block', margin: '0.5rem 0 0.25rem', fontSize: '1rem' }}>Verified</strong>
 
         Dead links and invalid markup stop the publication.
       </CardBody>

package/starter/02-components/09-for-theme.mdx

@@ -0,0 +1,45 @@
+---
+title: ForTheme
+description: Content kept for one theme only.
+---
+
+# ForTheme
+
+Keeps its content for the sites whose theme matches. The choice is made at
+build time: the other variant does not even reach the HTML.
+
+```mdx
+<ForTheme framework="tailwind">
+
+With Tailwind, a utility: `className="max-w-sm"`.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of the `theme/` folder: `className="narrow"`.
+
+</ForTheme>
+```
+
+It is how the pages of this documentation show each example in the terms of
+your theme. Changing `theme.framework` in the configuration changes what they
+show, without editing them.
+
+## On this site
+
+<ForTheme framework="tailwind">
+
+This site is built with the **Tailwind** theme.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+This site is built with the **custom** theme.
+
+</ForTheme>
+
+## What it refuses
+
+A `framework` other than `tailwind` or `custom` stops the build, with the
+accepted values: a typo would otherwise hide the content under every theme,
+without a word.

package/starter/02-components/{index.md → index.mdx}

@@ -8,7 +8,12 @@ description: The components available in every page, without an import.
 These components can be used in any `.mdx` page **without an import**.
 
 They provide the **structure** — wrappers, separators, spacing. The look is set
-with `className`, in utilities of the active theme:
+with `className`.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, a `className` holds utilities, compiled from the ones
+your pages use:
 
 ```mdx
 <Card className="max-w-sm">
@@ -19,6 +24,43 @@ with `className`, in utilities of the active theme:
 The component classes live in the `components` layer, below the utilities: a
 `className` set at use always wins.
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a `className` names classes of your own: there are no
+utilities. Every `.css` file of the `theme/` folder, at the root of the
+project, is appended to the stylesheet, and `docpensieve dev` picks up every
+change.
+
+```mdx
+<Card className="narrow">
+  <CardHeader className="centered">Title</CardHeader>
+</Card>
+```
+
+```css
+/* theme/custom.css */
+.narrow {
+  max-inline-size: 24rem;
+}
+
+.centered {
+  text-align: center;
+}
+```
+
+The component classes live in the `components` layer, those of the theme
+folder in none: a class of yours always wins.
+
+The examples of these pages use the classes of `theme/99-docpensieve.css`,
+which `init` wrote next to this documentation: delete both together.
+
+</ForTheme>
+
+Every example is shown in the terms of the site's theme, through
+[ForTheme](./for-theme/): changing `theme.framework` in the configuration
+changes the examples too.
+
 ## Available
 
 - [Card](./card/) — card, with header, body, footer and image
@@ -29,6 +71,7 @@ The component classes live in the `components` layer, below the utilities: a
 - [ScrollToTop](./scroll-to-top/) — back to the top of the page
 - [Skill](./skill/) — level gauge
 - [LogoIcon](./logo-icon/) — SVG icon inlined in the page
+- [ForTheme](./for-theme/) — content kept for one theme only
 
 ## Without JavaScript
 

package/starter/03-reference/01-cli.md

@@ -45,6 +45,11 @@ in the new site, in `docs/<version>/99-docpensieve/`: a **DocPensieve** section
 at the end of the menu, matching the installed version. Delete that folder when
 you no longer need it.
 
+Under the `custom` theme, the command also writes `theme/custom.css`, where the
+project's own classes go, and — with the documentation —
+`theme/99-docpensieve.css`, the classes of its examples, to delete along with
+it. An existing `theme/custom.css` is never overwritten, even with `--force`.
+
 ## `build`
 
 Generates the site.

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

@@ -103,6 +103,11 @@ theme: {
 
 The available tokens are listed in [Themes](../guide/themes/).
 
+Longer rules go in the `theme/` folder, at the root of the project: every
+`.css` file in it is appended after `css`, in name order, and
+`docpensieve dev` picks up every change. Under the `custom` theme, `init`
+starts it with `theme/custom.css`.
+
 ## `baseUrl`, and why you rarely write it
 
 A `siteUrl` with a sub-path already gives it: `https://example.com/my-project`

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

@@ -124,7 +124,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 +145,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.