docpensieve 0.1.2 → 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
@@ -32,6 +51,18 @@ The development server reloads the browser after every rebuild, through a
 script injected **at serving time**: the output of `build` stays free of
 JavaScript.
 
+## Updating
+
+```bash
+npm install docpensieve@latest
+```
+
+Run through `npx` alone, it needs nothing: `npx docpensieve` fetches the
+latest version by itself. A project set up with 0.1.0 can rename
+`docpensieve.config.js` to `docpensieve.config.mjs`, which Node reads as a
+module whatever the `package.json` says: the warning printed on every build
+goes away.
+
 ## Documentation
 
 See the [repository](https://github.com/Juniors017/docpensieve#readme).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.1.2",
+  "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.2",
-    "@docpensieve/core": "0.1.2",
-    "@docpensieve/shared": "0.1.2",
-    "@docpensieve/theme": "0.1.2",
+    "@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/';
@@ -127,9 +138,19 @@ async function collect(options) {
     docs: !options.minimal,
   };
 
+  if (options.yes) return fromOptions;
+
   // Without a terminal — script, CI, pipe — the dialogue would never complete:
-  // stick to the options and the defaults.
-  if (options.yes || !process.stdin.isTTY) return fromOptions;
+  // stick to the options and the defaults. But say so: some terminals run
+  // programs without handing them one, and the questions used to vanish
+  // without a word, the defaults going unnoticed.
+  if (!process.stdin.isTTY) {
+    console.log('No interactive terminal: no questions asked, the options and defaults apply.');
+    console.log(
+      'To choose, pass --name, --site-url, --theme, --version-name or --minimal; --yes silences this notice.',
+    );
+    return fromOptions;
+  }
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -215,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'
       ? [
           '',
@@ -423,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);
@@ -438,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}`);
@@ -447,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

@@ -26,7 +26,9 @@ cd my-site
 
 The command creates the folder and writes a configuration, a first
 documentation folder and a home page into it. It asks a few questions; `--yes`
-skips them and accepts the defaults.
+skips them and accepts the defaults. Where it cannot ask — a script, continuous
+integration, or a terminal that gives the programs it runs no interactive
+input — it says so and sticks to the options and the defaults.
 
 It also installs this very documentation, in a **DocPensieve** section at the
 end of the new site's menu. It matches the version you installed, and its
@@ -48,27 +50,55 @@ 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,
 described in [Themes](./themes/).
 
+## Updating
+
+```bash
+npm install docpensieve@latest
+```
+
+Run through `npx` alone, DocPensieve needs nothing: `npx docpensieve` fetches
+the latest version by itself.
+
+A project set up with 0.1.0 has a `docpensieve.config.js`. It still works, but
+Node reads it as a module only when the `package.json` says so, and warns on
+every build otherwise: rename it `docpensieve.config.mjs`.
+
+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.
+
 ## Checking
 
 ```bash

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