docpensieve 0.1.3 → 0.1.4

package/README.md

@@ -6,16 +6,35 @@ Part of [DocPensieve](https://github.com/Juniors017/docpensieve), a static docum
 Markdown and MDX in, static HTML out, one version per orphan branch, JSON-LD
 structured data from the frontmatter.
 
-## Installation
+## Getting started
+
+Nothing to install first: `npx` fetches the package.
+
+```bash
+npx docpensieve init my-site  # asks a few questions, then sets up the project
+cd my-site
+npx docpensieve dev           # builds, serves, watches and reloads
+```
+
+## Installing it in a project
+
+To pin the version a project uses — what continuous integration needs:
 
 ```bash
+npm init -y                   # only when the folder has no package.json yet
 npm install docpensieve
+npx docpensieve init .
 ```
 
-## Usage
+`npm install` only installs: it creates no site and asks nothing — `init`
+does. And npm installs in the nearest folder that has a `package.json`, going
+up from the current one: in a folder without one, the package lands in a parent
+folder and nothing appears where you are. Hence `npm init -y` first.
+
+## Commands
 
 ```bash
-npx docpensieve init          # sets up a project and picks the theme
+npx docpensieve init [dir]    # sets up a project and picks the theme
 npx docpensieve dev           # builds, serves, watches and reloads
 npx docpensieve build [ver]   # builds every version, or a single one
 npx docpensieve check         # reads the produced site back: links, markup

package/package.json

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

package/src/commands/dev.js

@@ -4,11 +4,12 @@
  * @module docpensieve/commands/dev
  */
 
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { componentsCss, createRegistry, setSiteContext } from '@docpensieve/components';
 import { SiteGenerator, loadConfig } from '@docpensieve/core';
-import { CONFIG_FILENAME, DocPensieveError } from '@docpensieve/shared';
+import { CONFIG_FILENAME, DocPensieveError, THEME_FOLDER } from '@docpensieve/shared';
 import chokidar from 'chokidar';
 
 import { RELOAD_PATH, createStaticServer, listen } from '../server.js';
@@ -20,6 +21,9 @@ const DEFAULT_PORT = 3000;
 /** Delay for grouping file events, in milliseconds. */
 const DEBOUNCE = 120;
 
+/** How often a missing theme folder is looked for, in ms. */
+const THEME_POLL = 1000;
+
 /**
  * Reload script injected on the fly, never written to disk.
  *
@@ -79,9 +83,12 @@ export async function dev(options = {}) {
   const url = `http://localhost:${port}${config.baseUrl}`;
   console.log(`served at ${url}`);
 
+  // The project's own stylesheets, re-read by every rebuild.
+  const themeFolder = path.resolve(cwd, THEME_FOLDER);
   const watched = [
     config.configFile ?? path.resolve(cwd, CONFIG_FILENAME),
     ...config.versions.map((version) => path.resolve(cwd, version.folder)),
+    ...(existsSync(themeFolder) ? [themeFolder] : []),
   ];
   const watcher = chokidar.watch(watched, { ignoreInitial: true });
 
@@ -92,7 +99,8 @@ export async function dev(options = {}) {
 
   /** @type {NodeJS.Timeout | undefined} */
   let pending;
-  watcher.on('all', (_event, changed) => {
+  /** @param {string} changed */
+  const schedule = (changed) => {
     // An editor emits several events per save: group them.
     clearTimeout(pending);
     pending = setTimeout(async () => {
@@ -111,7 +119,22 @@ export async function dev(options = {}) {
         }
       }
     }, DEBOUNCE);
-  });
+  };
+  watcher.on('all', (_event, changed) => schedule(changed));
+
+  // Handed a path that does not exist, chokidar loses the events of all the
+  // others. A missing theme folder is therefore looked for every second, and
+  // watched from the moment it appears — its creation itself triggers no
+  // event, hence the rebuild asked for here.
+  const lookForTheme = existsSync(themeFolder)
+    ? undefined
+    : setInterval(() => {
+        if (!existsSync(themeFolder)) return;
+        clearInterval(lookForTheme);
+        watcher.add(themeFolder);
+        schedule(themeFolder);
+      }, THEME_POLL);
+  lookForTheme?.unref();
 
   console.log('watching — Ctrl+C to stop');
 
@@ -122,6 +145,7 @@ export async function dev(options = {}) {
     url,
     close: async () => {
       clearTimeout(pending);
+      clearInterval(lookForTheme);
       await watcher.close();
       // Without this, close() waits for keep-alive connections to expire —
       // the reload stream keeps one open permanently.

package/src/commands/init.js

@@ -15,6 +15,7 @@ import {
   CONFIG_FILENAME,
   CONFIG_FILENAMES,
   DocPensieveError,
+  THEME_FOLDER,
   THEME_FRAMEWORKS,
 } from '@docpensieve/shared';
 
@@ -24,7 +25,7 @@ import {
  */
 const FRAMEWORK_LABELS = {
   tailwind: 'Tailwind CSS — ships with the tool, nothing to install',
-  custom: 'custom theme, light stylesheet, no utilities',
+  custom: 'custom theme, light stylesheet, your own classes in theme/',
 };
 
 /** Answers used when there is no dialogue. */
@@ -39,10 +40,20 @@ const DEFAULTS = { name: 'My documentation', siteUrl: '', theme: 'tailwind', ver
 const DOCS_FOLDER = '99-docpensieve';
 
 /**
- * Entries of DocPensieve's documentation that are not installed: its home page
- * and the icons only that page uses belong to DocPensieve's own site.
+ * Stylesheet of the documentation's examples, shipped next to its pages.
+ * Under the custom theme, it goes to the theme folder, not among the pages.
  */
-const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons']);
+const EXAMPLES_CSS = 'examples.css';
+
+/**
+ * Entries of DocPensieve's documentation that are not installed with the
+ * pages: its home page and the icons only that page uses belong to
+ * DocPensieve's own site, and the examples' stylesheet has a place of its own.
+ */
+const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons', EXAMPLES_CSS]);
+
+/** Starting point of the project's own stylesheet, under the custom theme. */
+const CUSTOM_CSS = fileURLToPath(new URL('../templates/custom.css', import.meta.url));
 
 /** Where the generated configuration sends readers for every field. */
 const DOCUMENTATION_URL = 'https://juniors017.github.io/docpensieve/';
@@ -225,6 +236,9 @@ function renderConfig({ name, theme, siteUrl, version }) {
     '    // CSS appended to the stylesheet, outside any layer: it wins over the',
     '    // default rules.',
     "    // css: '.dp-article h2 { letter-spacing: -0.01em; }',",
+    '',
+    '    // Longer rules go in the theme/ folder: every .css file in it is',
+    '    // appended after the theme, and "docpensieve dev" picks up changes.',
     ...(theme === 'tailwind'
       ? [
           '',
@@ -433,6 +447,17 @@ export async function init(dir = '.', options = {}) {
       hint: 'Reinstall docpensieve, or run init with --minimal to go without it.',
     });
   }
+  // Under the custom theme, its examples also need their stylesheet: without
+  // it, every one of them would render unstyled, and nothing would say why.
+  if (
+    documentation &&
+    answers.theme === 'custom' &&
+    !existsSync(path.join(documentation, EXAMPLES_CSS))
+  ) {
+    throw new DocPensieveError("The stylesheet of the documentation's examples is missing.", {
+      hint: 'Reinstall docpensieve, or run init with --minimal to go without the documentation.',
+    });
+  }
 
   const slug = versionSlug(answers.version);
   const docsDir = path.join(target, 'docs', slug);
@@ -448,6 +473,8 @@ export async function init(dir = '.', options = {}) {
   if (documentation) {
     await installDocumentation(documentation, path.join(docsDir, DOCS_FOLDER), slug);
   }
+  const stylesheets =
+    answers.theme === 'custom' ? await writeStylesheets(target, documentation) : [];
   await ignoreOutput(target);
 
   console.log(`\nProject initialised in ${target}`);
@@ -457,12 +484,41 @@ export async function init(dir = '.', options = {}) {
   if (documentation) {
     console.log(`  docs/${slug}/${DOCS_FOLDER}/  DocPensieve's documentation, to delete when done`);
   }
+  for (const line of stylesheets) console.log(`  ${line}`);
   console.log(`\nTheme: ${answers.theme} — ${FRAMEWORK_LABELS[answers.theme]}`);
   console.log('\nNext:  npx docpensieve dev');
 
   return { dir: target, theme: answers.theme, docs: answers.docs };
 }
 
+/**
+ * Gives the custom theme its stylesheets, in the project's theme folder.
+ *
+ * The custom theme loads no utility framework: the classes a page uses are
+ * defined by the project. `custom.css` is where they go — never overwritten,
+ * even with `--force`, since it holds the project's own rules. The installed
+ * documentation brings the classes of its examples in a file of its own, to
+ * delete along with it.
+ *
+ * @param {string} target Project folder.
+ * @param {string | null} documentation Source of the installed documentation.
+ * @returns {Promise<string[]>} One line per file, for the summary.
+ */
+async function writeStylesheets(target, documentation) {
+  const folder = path.join(target, THEME_FOLDER);
+  await mkdir(folder, { recursive: true });
+
+  const own = path.join(folder, 'custom.css');
+  if (!existsSync(own)) cpSync(CUSTOM_CSS, own);
+  const lines = [`${THEME_FOLDER}/custom.css  your own styles`];
+
+  if (documentation) {
+    cpSync(path.join(documentation, EXAMPLES_CSS), path.join(folder, `${DOCS_FOLDER}.css`));
+    lines.push(`${THEME_FOLDER}/${DOCS_FOLDER}.css  classes of its examples, to delete with it`);
+  }
+  return lines;
+}
+
 /**
  * Adds the output folder to .gitignore, without overwriting what is there.
  *

package/src/templates/custom.css

@@ -0,0 +1,20 @@
+/*
+ * Your own styles.
+ *
+ * Every .css file of this theme/ folder is appended to the site's stylesheet,
+ * after the theme's, in name order, and "docpensieve dev" picks up every
+ * change. The rules sit outside any layer: they win over the default look of
+ * the components.
+ *
+ * The custom theme loads no utility framework: a className written in a page
+ * names a class defined here. Write the colours on the --dp-* tokens
+ * (--dp-accent, --dp-accent-soft, --dp-bg, --dp-text, --dp-text-soft,
+ * --dp-border…) so that they follow the light and dark palettes.
+ *
+ * For instance, for <Card className="accent-card">:
+ *
+ *   .accent-card {
+ *     border-color: var(--dp-accent);
+ *     background: var(--dp-accent-soft);
+ *   }
+ */

package/src/theme.js

@@ -4,18 +4,39 @@
  * @module docpensieve/theme
  */
 
-import { setThemeClasses } from '@docpensieve/components';
-import { ConfigError, THEME_FRAMEWORKS } from '@docpensieve/shared';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { setThemeClasses, setThemeFramework } from '@docpensieve/components';
+import { ConfigError, THEME_FOLDER, THEME_FRAMEWORKS } from '@docpensieve/shared';
 import { CustomProvider, TailwindProvider, 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 function projectCss(rootDir) {
+  const folder = rootDir ? path.join(rootDir, THEME_FOLDER) : '';
+  if (!folder || !existsSync(folder)) return [];
+  return readdirSync(folder)
+    .filter((name) => name.toLowerCase().endsWith('.css'))
+    .sort()
+    .map((name) => readFileSync(path.join(folder, name), 'utf8').trim());
+}
+
 /**
  * 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
@@ -27,16 +48,18 @@ export function createTheme(config, extraCss = '') {
   const theme = config.theme ?? {};
   const framework = theme.framework ?? 'tailwind';
 
-  // Components first, project CSS second: the latter must be able to correct
-  // them.
+  // Components first, project CSS after: the latter must be able to correct
+  // them. The theme folder comes last — the project's final word, and the
+  // only place the custom theme finds the classes a page uses.
   const options = {
     tokens: theme.tokens,
-    css: [extraCss, theme.css].filter(Boolean).join('\n\n'),
+    css: [extraCss, theme.css, ...projectCss(config.rootDir)].filter(Boolean).join('\n\n'),
   };
 
   /** @param {ThemeEngine} engine */
   const mount = (engine) => {
     setThemeClasses(engine.classes);
+    setThemeFramework(framework);
     return engine;
   };
 

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

@@ -50,22 +50,33 @@ npx docpensieve init my-site --yes --name "My documentation"
 | `-f, --force`              | Overwrites an existing configuration                    |
 | `--minimal`                | Leaves DocPensieve's documentation out of the site      |
 
-## In an existing project
+## Installing it in a project
+
+Through `npx` alone, the version used is the latest. To pin the one a project
+uses — what continuous integration needs — install it in the project:
 
 ```bash
+npm init -y              # only when the folder has no package.json yet
 npm install docpensieve
-npx docpensieve init . --force
+npx docpensieve init .
 ```
 
-`init` on an occupied folder refuses to overwrite an existing configuration:
-you have to ask for it with `--force`. The refusal is deliberate — a
+`npm install` only installs: it creates no site and asks nothing — `init` does.
+It also installs in the nearest folder that has a `package.json`, going up from
+the current one: in a folder without one, the package lands in a parent folder
+and nothing appears where you are. Hence `npm init -y` first. `npx docpensieve`
+then runs the installed copy.
+
+`init` refuses to overwrite an existing configuration: you have to ask for it
+with `--force`. The refusal is deliberate — a
 configuration overwritten by mistake is only noticed at the next deployment.
 
 ## Choosing the theme
 
 `tailwind` is the default and installs Tailwind as a dependency. `custom` does
 without it entirely: the site is then styled by a stylesheet written in the
-package, with no styling dependency.
+package, with no styling dependency. Your own classes then go in the `theme/`
+folder, which `init` starts with `theme/custom.css`.
 
 Both are equivalent in use — the templates are the same, only the styling
 changes. The choice is not final: it fits in one field of the configuration,

package/starter/01-guide/03-writing-pages.md

@@ -126,8 +126,8 @@ Three ways to guard against it:
 
 - prefer `<div>` to `<p>` as a wrapper — a paragraph is valid inside it;
 - write short content on the same line as its tags;
-- for repeated cases, put a class in `theme.css` rather than a long string of
-  utilities, so that the line stays short.
+- for repeated cases, put a class in the `theme/` folder rather than a long
+  string of utilities, so that the line stays short.
 
 `docpensieve check` reports these nestings on the produced site.
 

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

@@ -100,9 +100,11 @@ Without this layer, a component rule written after a utility would beat it at
 equal specificity, and the author's `className` would be ignored without a
 word.
 
-The `custom` theme has no utilities: a `className` there designates your own
-classes. Declare them in `theme.css` — outside any layer, they come before the
-component rules.
+The `custom` theme has no utilities: a `className` there names classes of your
+own. Write them in the `theme/` folder, at the root of the project: every `.css`
+file in it is appended to the stylesheet, outside any layer, so they come
+before the component rules. Under this theme, `init` starts the folder with
+`theme/custom.css`.
 
 ## The stylesheet is compiled last
 

package/starter/02-components/01-card.mdx

@@ -7,19 +7,22 @@ description: Structured card, with header, body, footer and image.
 
 ## The simplest
 
-<Card className="max-w-sm">
+<Card style={{ maxWidth: '24rem' }}>
   <CardBody>A card reduced to its body.</CardBody>
 </Card>
 
 ```mdx
-<Card className="max-w-sm">
+<Card>
   <CardBody>A card reduced to its body.</CardBody>
 </Card>
 ```
 
+The examples of this page narrow some cards through `style`, which every theme
+understands; the look proper comes further down.
+
 ## With its three parts
 
-<Card className="max-w-sm">
+<Card style={{ maxWidth: '24rem' }}>
   <CardHeader>Header</CardHeader>
   <CardBody>
     The body of the card. It takes the remaining space when several cards sit side by side.
@@ -62,7 +65,12 @@ meaning deserves a written `alt`.
 
 ## A grid of cards
 
-It is the most common use. `h-full` aligns the heights whatever the content.
+It is the most common use. Stretching each card to the height of its column
+aligns them whatever the content.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, the `h-full` utility does it:
 
 <Columns>
   <Column>
@@ -97,9 +105,56 @@ It is the most common use. `h-full` aligns the heights whatever the content.
 </Columns>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own does it — here `full-height`, from
+`theme/99-docpensieve.css`:
+
+<Columns>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>Stateless</CardHeader>
+      <CardBody>
+        Components are rendered at build time. None of them keeps state or listens to events.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>Dependency-free</CardHeader>
+      <CardBody>The delivered HTML loads nothing.</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>No surprises</CardHeader>
+      <CardBody>
+        What cannot be rendered stops the build rather than disappearing silently.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns>
+  <Column>
+    <Card className="full-height">…</Card>
+  </Column>
+</Columns>
+```
+
+```css
+.full-height {
+  block-size: 100%;
+}
+```
+
+</ForTheme>
+
 ## Elevation
 
-<Card className="max-w-sm" elevated>
+<Card style={{ maxWidth: '24rem' }} elevated>
   <CardBody>This card carries a shadow.</CardBody>
 </Card>
 
@@ -109,7 +164,7 @@ It is the most common use. `h-full` aligns the heights whatever the content.
 
 ## Fully clickable
 
-<Card className="max-w-sm" href="./columns/">
+<Card style={{ maxWidth: '24rem' }} href="./columns/">
   <CardHeader>Go to the columns</CardHeader>
   <CardBody>The whole card is a link, not just the title.</CardBody>
 </Card>
@@ -126,6 +181,8 @@ root — the same rules as for a Markdown link.
 Nothing specific to the component: a card, a little typography, and the footer
 carrying the caption.
 
+<ForTheme framework="tailwind">
+
 <Columns>
   <Column span={4}>
     <Card className="h-full text-center">
@@ -139,7 +196,7 @@ carrying the caption.
   <Column span={4}>
     <Card className="h-full text-center">
       <CardBody>
-        <div className="text-4xl font-semibold text-indigo-600">8</div>
+        <div className="text-4xl font-semibold text-indigo-600">9</div>
         <div className="text-sm">components</div>
       </CardBody>
       <CardFooter>usable without an import</CardFooter>
@@ -156,8 +213,45 @@ carrying the caption.
   </Column>
 </Columns>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<Columns>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">0</div>
+        <div className="small">bytes of JavaScript</div>
+      </CardBody>
+      <CardFooter>on every delivered page</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">9</div>
+        <div className="small">components</div>
+      </CardBody>
+      <CardFooter>usable without an import</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">1</div>
+        <div className="small">stylesheet</div>
+      </CardBody>
+      <CardFooter>per version</CardFooter>
+    </Card>
+  </Column>
+</Columns>
+
+</ForTheme>
+
 ## A warning card
 
+<ForTheme framework="tailwind">
+
 <Card className="border-amber-400 bg-amber-50 dark:bg-amber-950/30">
   <CardHeader className="text-amber-800 dark:text-amber-200">To check before publishing</CardHeader>
   <CardBody className="text-sm">
@@ -166,8 +260,23 @@ carrying the caption.
   </CardBody>
 </Card>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<Card className="warning">
+  <CardHeader className="warning-title">To check before publishing</CardHeader>
+  <CardBody className="small">
+    A generated site can compile without error and contain dead links.
+    <code>docpensieve check</code> reads the output back.
+  </CardBody>
+</Card>
+
+</ForTheme>
+
 ## The look through className
 
+<ForTheme framework="tailwind">
+
 The component offers no typography prop: the theme's utilities take care of
 it, and win over the default style.
 
@@ -193,3 +302,42 @@ The component rules live in the `components` layer, below the utilities: a
 <Card className="max-w-sm border-0 shadow-none bg-transparent">
   <CardBody className="px-0">No border, no background, no inner padding.</CardBody>
 </Card>
+
+</ForTheme>
+<ForTheme framework="custom">
+
+The component offers no typography prop: the look comes from classes of your
+own, written in the `theme/` folder — here those of `theme/99-docpensieve.css`.
+
+<Card className="narrow highlight">
+  <CardHeader className="centered caps accent-text">Centred, in capitals</CardHeader>
+  <CardBody className="small italic">Small, italic body.</CardBody>
+</Card>
+
+```mdx
+<Card className="highlight">
+  <CardHeader className="centered caps accent-text">Centred, in capitals</CardHeader>
+  <CardBody className="small italic">Small, italic body.</CardBody>
+</Card>
+```
+
+```css
+.highlight {
+  border-color: var(--dp-accent);
+  background: var(--dp-accent-soft);
+}
+
+.caps {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+The component rules live in the `components` layer, those of the theme folder
+in none: a class of yours always wins, even to undo the default style.
+
+<Card className="narrow plain">
+  <CardBody className="flush">No border, no background, no inner padding.</CardBody>
+</Card>
+
+</ForTheme>