docpensieve 0.1.0 → 0.1.1

package/README.md

@@ -22,8 +22,11 @@ npx docpensieve check         # reads the produced site back: links, markup
 npx docpensieve serve         # serves the output folder
 ```
 
-`init` asks for the project name, its URL and the CSS framework. In a script
-or in CI, `--yes --theme tailwind` skips the dialogue.
+`init` asks for the project name, its URL and the CSS framework, and installs
+DocPensieve's documentation in a section of the new site's menu, matching the
+installed version — `--minimal` leaves it out. The configuration file it writes
+lists every option, each with a comment. In a script or in CI,
+`--yes --theme tailwind` skips the dialogue.
 
 The development server reloads the browser after every rebuild, through a
 script injected **at serving time**: the output of `build` stays free of

package/bin/docpensieve.js

@@ -33,6 +33,7 @@ program
   .option('--version-name <version>', 'first version, e.g. 1.0')
   .option('-y, --yes', 'accept the defaults without a dialogue')
   .option('-f, --force', 'overwrite an existing configuration')
+  .option('--minimal', "leave DocPensieve's documentation out of the new site")
   .action(async (dir, options) => {
     await init(dir, { ...options, version: options.versionName });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
   "files": [
     "bin",
     "src",
+    "starter",
     "types"
   ],
   "dependencies": {
@@ -54,6 +55,7 @@
   },
   "types": "./types/index.d.ts",
   "scripts": {
-    "prepack": "tsc -b tsconfig.build.json"
+    "prepack": "tsc -b tsconfig.build.json && node scripts/starter.mjs",
+    "postpack": "node scripts/starter.mjs --clean"
   }
 }

package/src/commands/dev.js

@@ -80,7 +80,7 @@ export async function dev(options = {}) {
   console.log(`served at ${url}`);
 
   const watched = [
-    path.resolve(cwd, CONFIG_FILENAME),
+    config.configFile ?? path.resolve(cwd, CONFIG_FILENAME),
     ...config.versions.map((version) => path.resolve(cwd, version.folder)),
   ];
   const watcher = chokidar.watch(watched, { ignoreInitial: true });

package/src/commands/init.js

@@ -4,12 +4,19 @@
  * @module docpensieve/commands/init
  */
 
-import { existsSync } from 'node:fs';
+import { cpSync, existsSync, readdirSync, rmSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
 
-import { CONFIG_FILENAME, DocPensieveError, THEME_FRAMEWORKS } from '@docpensieve/shared';
+import {
+  CONFIG_FILENAME,
+  CONFIG_FILENAMES,
+  DocPensieveError,
+  THEME_FRAMEWORKS,
+} from '@docpensieve/shared';
 
 /**
  * Description shown next to each framework.
@@ -23,6 +30,23 @@ const FRAMEWORK_LABELS = {
 /** Answers used when there is no dialogue. */
 const DEFAULTS = { name: 'My documentation', siteUrl: '', theme: 'tailwind', version: '1.0' };
 
+/**
+ * Folder of the installed DocPensieve documentation, inside the version folder.
+ *
+ * The prefix puts it last in the menu, after the project's own pages, and
+ * vanishes from the URL: the section is served under `/docpensieve/`.
+ */
+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.
+ */
+const NOT_INSTALLED = new Set(['index.md', 'index.mdx', 'icons']);
+
+/** Where the generated configuration sends readers for every field. */
+const DOCUMENTATION_URL = 'https://juniors017.github.io/docpensieve/';
+
 /**
  * Asks a question, with a default value shown between brackets.
  *
@@ -66,11 +90,33 @@ async function askFramework(rl) {
   }
 }
 
+/**
+ * Asks whether to install DocPensieve's documentation in the new site.
+ *
+ * @param {import('node:readline/promises').Interface} rl
+ * @returns {Promise<boolean>}
+ */
+async function askDocumentation(rl) {
+  for (;;) {
+    const answer = (await rl.question("Install DocPensieve's documentation in the site? [Y/n]: "))
+      .trim()
+      .toLowerCase();
+    if (answer === '' || answer === 'y' || answer === 'yes') return true;
+    if (answer === 'n' || answer === 'no') return false;
+    console.log('Answer not understood. Expected: y or n.');
+  }
+}
+
 /**
  * Gathers the answers, through a dialogue or from the options.
  *
- * @param {{ name?: string, theme?: string, siteUrl?: string, version?: string, yes?: boolean }} options
- * @returns {Promise<{ name: string, theme: string, siteUrl: string, version: string }>}
+ * @param {{
+ *   name?: string, theme?: string, siteUrl?: string, version?: string,
+ *   yes?: boolean, minimal?: boolean,
+ * }} options
+ * @returns {Promise<{
+ *   name: string, theme: string, siteUrl: string, version: string, docs: boolean,
+ * }>}
  */
 async function collect(options) {
   const fromOptions = {
@@ -78,6 +124,7 @@ async function collect(options) {
     siteUrl: options.siteUrl ?? DEFAULTS.siteUrl,
     theme: options.theme ?? DEFAULTS.theme,
     version: options.version ?? DEFAULTS.version,
+    docs: !options.minimal,
   };
 
   // Without a terminal — script, CI, pipe — the dialogue would never complete:
@@ -90,7 +137,8 @@ async function collect(options) {
     const siteUrl = await ask(rl, 'Public URL of the site (optional)', fromOptions.siteUrl);
     const version = await ask(rl, 'First version', fromOptions.version);
     const theme = options.theme ?? (await askFramework(rl));
-    return { name, siteUrl, version, theme };
+    const docs = options.minimal ? false : await askDocumentation(rl);
+    return { name, siteUrl, version, theme, docs };
   } finally {
     rl.close();
   }
@@ -108,8 +156,14 @@ async function collect(options) {
 const quote = (value) => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 
 /**
+ * Renders `docpensieve.config.mjs`.
+ *
+ * Every field the configuration accepts appears in it — set to its default,
+ * or commented out with an example — so that the first file a user opens also
+ * tells them everything they can change.
+ *
  * @param {{ name: string, theme: string, siteUrl: string, version: string }} answers
- * @returns {string} Contents of `docpensieve.config.js`.
+ * @returns {string} Contents of `docpensieve.config.mjs`.
  */
 function renderConfig({ name, theme, siteUrl, version }) {
   const slug = versionSlug(version);
@@ -121,45 +175,74 @@ function renderConfig({ name, theme, siteUrl, version }) {
   const lines = [
     "/** @type {import('@docpensieve/core').DocPensieveConfig} */",
     'export default {',
+    '  // Name shown in the header, in the page titles and in the structured data.',
     `  projectName: ${quote(name)},`,
-  ];
-
-  if (siteUrl) {
-    lines.push(
-      `  siteUrl: ${quote(siteUrl)},`,
-      '  // baseUrl is derived from the path of siteUrl. Set it to force it.',
-    );
-  }
-
-  lines.push(
     '',
-    '  // One entry per version. The compiled output then goes to an orphan',
-    '  // branch with the same slug.',
+    '  // Public address of the site. It feeds the canonical links and the',
+    '  // structured data, and its path gives the deployment prefix.',
+    siteUrl ? `  siteUrl: ${quote(siteUrl)},` : "  // siteUrl: 'https://example.com/my-project',",
+    "  // baseUrl: '/my-project/', // only to depart from the path of siteUrl",
+    '',
+    '  // Language of the pages, in <html lang>. The labels of the page shell',
+    '  // stay in English.',
+    "  lang: 'en',",
+    '',
+    '  // One entry per version, each one a folder of Markdown and MDX pages.',
+    '  //   current     the version the site root leads to — at most one',
+    '  //   prerelease  in preparation: a banner on every page, kept out of search',
+    '  //   archived    no longer maintained: a banner, still indexed',
     '  versions: [',
-    `    {`,
-    `      slug: ${quote(slug)},`,
-    `      name: ${quote(version)},`,
+    '    {',
+    `      slug: ${quote(slug)}, // URL segment, and name of the version's branch`,
+    `      name: ${quote(version)}, // label in the version switcher`,
     `      folder: ${quote(`docs/${slug}`)},`,
-    `      current: true,`,
-    `    },`,
+    '      current: true,',
+    '    },',
     '  ],',
     '',
+    '  // Output folder of "docpensieve build".',
     "  outDir: 'dist',",
     '',
     '  theme: {',
+    "    // 'tailwind' compiles the utilities your pages use; 'custom' is a plain",
+    '    // stylesheet with no dependency.',
     `    framework: ${quote(theme)},`,
     "    darkMode: 'class',",
-    "    // Override the palette: tokens: { '--dp-accent': '#008060' },",
+    '',
+    '    // Design tokens to override, for instance the accent colour:',
+    "    // tokens: { '--dp-accent': '#008060', '--dp-radius': '0.75rem' },",
+    '',
+    '    // CSS appended to the stylesheet, outside any layer: it wins over the',
+    '    // default rules.',
+    "    // css: '.dp-article h2 { letter-spacing: -0.01em; }',",
+    ...(theme === 'tailwind'
+      ? [
+          '',
+          '    // Entry stylesheet handed to Tailwind, to add a @theme block for',
+          '    // instance.',
+          `    // source: '@import "tailwindcss";',`,
+        ]
+      : []),
     '  },',
     '',
-    "  // 'auto': the sidebar follows the file tree and the 01-, 02- prefixes.",
+    "  // 'auto': the menu follows the folders and the 01-, 02- prefixes.",
     "  sidebar: 'auto',",
     '',
+    '  // The shipped components — Card, Columns, Tooltip… — usable in any .mdx',
+    '  // page without an import. false removes them, to use your own names.',
     '  globalComponents: true,',
+    '',
+    '  // Back-to-top button on every page.',
+    '  scrollToTop: true,',
+    '',
+    '  // Structured data (JSON-LD) generated from the frontmatter of each page.',
     '  jsonld: { enabled: true },',
     '};',
     '',
-  );
+    '// Every field is described in the reference of the DocPensieve documentation:',
+    `// the DocPensieve section of your site, or ${DOCUMENTATION_URL}`,
+    '',
+  ];
 
   return lines.join('\n');
 }
@@ -180,9 +263,10 @@ function versionSlug(version) {
 
 /**
  * @param {string} name Project name, for the title of the home page.
+ * @param {boolean} docs Whether DocPensieve's documentation is installed.
  * @returns {string}
  */
-const renderIndex = (name) => `---
+const renderIndex = (name, docs) => `---
 title: Introduction
 description: Documentation of ${name}.
 date: ${new Date().toISOString().slice(0, 10)}
@@ -202,7 +286,17 @@ Pages live in \`docs/\`. The \`01-\` prefix of a file orders the menu
 without appearing in the URL.
 
 See the [installation guide](/guide/installation/).
-`;
+${
+  docs
+    ? `
+## Learning DocPensieve
+
+The [DocPensieve](/docpensieve/) section of the menu is the documentation of the
+tool that builds this site, installed along with it. Delete its folder,
+\`${DOCS_FOLDER}\`, when you no longer need it.
+`
+    : ''
+}`;
 
 /** @returns {string} Sample page, showing ordering and highlighting. */
 const renderGuide = () => `---
@@ -227,23 +321,85 @@ npm run dev
 \`\`\`
 `;
 
+/**
+ * @param {string} slug Version slug, to name the folder to delete.
+ * @returns {string} Entry page of the installed documentation section.
+ */
+const renderDocsIndex = (slug) => `---
+title: DocPensieve
+description: Documentation of the tool this site is built with, installed along with it.
+---
+
+# DocPensieve
+
+This section is the documentation of DocPensieve, the tool this site is built
+with. \`docpensieve init\` installed it, and it matches the version you use.
+
+- [Guide](./guide/) — from installation to deployment, in order.
+- [Components](./components/) — the components usable in any page.
+- [Reference](./reference/) — commands, configuration, frontmatter and theme.
+- [Architecture](./architecture/) — how a page becomes HTML.
+
+When you no longer need it, delete the \`docs/${slug}/${DOCS_FOLDER}\` folder:
+nothing else depends on it.
+`;
+
+/**
+ * Folder holding DocPensieve's documentation, ready to be installed.
+ *
+ * The published package carries it in `starter/`, copied at packing time from
+ * the documentation of its own version. In this repository, outside packing,
+ * the same pages are read straight from `docs/`.
+ *
+ * @returns {string | null} The folder, or `null` when neither exists.
+ */
+function documentationSource() {
+  const packed = fileURLToPath(new URL('../../starter/', import.meta.url));
+  if (existsSync(packed)) return packed;
+
+  const { version } = createRequire(import.meta.url)('../../package.json');
+  const [major, minor] = String(version).split('.');
+  const repository = fileURLToPath(
+    new URL(`../../../../docs/v${major}.${minor}/`, import.meta.url),
+  );
+  return existsSync(repository) ? repository : null;
+}
+
+/**
+ * Copies DocPensieve's documentation into the new project, in its own folder.
+ *
+ * @param {string} source Folder of the documentation to install.
+ * @param {string} target Folder of the section, in the version folder.
+ * @param {string} slug Version slug.
+ */
+async function installDocumentation(source, target, slug) {
+  await mkdir(target, { recursive: true });
+  for (const entry of readdirSync(source)) {
+    if (NOT_INSTALLED.has(entry)) continue;
+    cpSync(path.join(source, entry), path.join(target, entry), { recursive: true });
+  }
+  await writeFile(path.join(target, 'index.md'), renderDocsIndex(slug), 'utf8');
+}
+
 /**
  * Sets up a documentation project.
  *
  * @param {string} [dir] Target folder, created if needed.
  * @param {{
  *   name?: string, theme?: string, siteUrl?: string, version?: string,
- *   yes?: boolean, force?: boolean,
- * }} [options]
- * @returns {Promise<{ dir: string, theme: string }>}
- * @throws {DocPensieveError} Unknown framework, or project already initialised.
+ *   yes?: boolean, force?: boolean, minimal?: boolean,
+ * }} [options] `minimal` leaves DocPensieve's documentation out of the site.
+ * @returns {Promise<{ dir: string, theme: string, docs: boolean }>}
+ * @throws {DocPensieveError} Unknown framework, project already initialised,
+ *   or documentation to install missing.
  */
 export async function init(dir = '.', options = {}) {
   const target = path.resolve(dir);
   const configPath = path.join(target, CONFIG_FILENAME);
+  const existing = CONFIG_FILENAMES.filter((name) => existsSync(path.join(target, name)));
 
-  if (existsSync(configPath) && !options.force) {
-    throw new DocPensieveError(`${CONFIG_FILENAME} already exists in ${target}.`, {
+  if (existing.length > 0 && !options.force) {
+    throw new DocPensieveError(`${existing[0]} already exists in ${target}.`, {
       hint: 'Use --force to overwrite it, or pick another folder.',
     });
   }
@@ -259,23 +415,42 @@ export async function init(dir = '.', options = {}) {
 
   const answers = await collect(options);
 
+  // Located before anything is written: a project left half set up would be
+  // worse than a clear error.
+  const documentation = answers.docs ? documentationSource() : null;
+  if (answers.docs && !documentation) {
+    throw new DocPensieveError('The DocPensieve documentation to install cannot be found.', {
+      hint: 'Reinstall docpensieve, or run init with --minimal to go without it.',
+    });
+  }
+
   const slug = versionSlug(answers.version);
   const docsDir = path.join(target, 'docs', slug);
 
-  await mkdir(path.join(docsDir, 'guide'), { recursive: true });
+  // Overwritten, a project keeps a single configuration file: the one written
+  // here. An older spelling left behind would make the next build refuse both.
+  for (const name of existing) rmSync(path.join(target, name), { force: true });
+
+  await mkdir(path.join(docsDir, '01-guide'), { recursive: true });
   await writeFile(configPath, renderConfig(answers), 'utf8');
-  await writeFile(path.join(docsDir, 'index.md'), renderIndex(answers.name), 'utf8');
-  await writeFile(path.join(docsDir, 'guide', '01-installation.md'), renderGuide(), 'utf8');
+  await writeFile(path.join(docsDir, 'index.md'), renderIndex(answers.name, answers.docs), 'utf8');
+  await writeFile(path.join(docsDir, '01-guide', '01-installation.md'), renderGuide(), 'utf8');
+  if (documentation) {
+    await installDocumentation(documentation, path.join(docsDir, DOCS_FOLDER), slug);
+  }
   await ignoreOutput(target);
 
   console.log(`\nProject initialised in ${target}`);
   console.log(`  ${CONFIG_FILENAME}`);
   console.log(`  docs/${slug}/index.md`);
-  console.log(`  docs/${slug}/guide/01-installation.md`);
+  console.log(`  docs/${slug}/01-guide/01-installation.md`);
+  if (documentation) {
+    console.log(`  docs/${slug}/${DOCS_FOLDER}/  DocPensieve's documentation, to delete when done`);
+  }
   console.log(`\nTheme: ${answers.theme} — ${FRAMEWORK_LABELS[answers.theme]}`);
   console.log('\nNext:  npx docpensieve dev');
 
-  return { dir: target, theme: answers.theme };
+  return { dir: target, theme: answers.theme, docs: answers.docs };
 }
 
 /**

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

@@ -0,0 +1,79 @@
+---
+title: Installation
+description: What you need, and how to set up a documentation project.
+date: 2026-09-09
+tags: [guide, installation]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# Installation
+
+## What you need
+
+**Node.js 22 or later.** It is the only requirement. The generator runs at
+build time, not on the reader's side: nothing else to install on the server
+that will host the site, which only has to serve files.
+
+## Setting up a project
+
+```bash
+npx docpensieve init my-site
+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.
+
+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
+folder, `99-docpensieve`, can be deleted as soon as you no longer need it;
+`--minimal` leaves it out. The configuration file lists every option, each with
+a comment, set to its default or given as an example.
+
+```bash
+npx docpensieve init my-site --yes --name "My documentation"
+```
+
+| Option                     | Effect                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| `-n, --name <name>`        | Project name, shown in the header                       |
+| `-t, --theme <framework>`  | `tailwind` or `custom`                                  |
+| `-u, --site-url <url>`     | Public URL, from which the deployment prefix is derived |
+| `--version-name <version>` | First version, `1.0` for instance                       |
+| `-y, --yes`                | Accepts the defaults without a dialogue                 |
+| `-f, --force`              | Overwrites an existing configuration                    |
+| `--minimal`                | Leaves DocPensieve's documentation out of the site      |
+
+## In an existing project
+
+```bash
+npm install docpensieve
+npx docpensieve init . --force
+```
+
+`init` on an occupied folder 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.
+
+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/).
+
+## Checking
+
+```bash
+npx docpensieve build
+```
+
+If the output folder appears with an `index.html` inside, everything is in
+place. Next: [First site](./first-site/).

package/starter/01-guide/02-first-site.md

@@ -0,0 +1,97 @@
+---
+title: First site
+description: Build, serve, and understand what was produced.
+tags: [guide]
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# First site
+
+## Building
+
+```bash
+npx docpensieve build
+```
+
+Every declared version is built. To build just one, pass its slug:
+
+```bash
+npx docpensieve build v1.0
+```
+
+## Looking at the result
+
+```bash
+npx docpensieve serve
+```
+
+The output folder is served statically on port 4000. It is exactly what a host
+will do: no difference between this server and going live.
+
+## Working
+
+```bash
+npx docpensieve dev
+```
+
+The development server watches the sources and rebuilds on every save. It
+listens on port 3000; `--port` changes that.
+
+The difference with `serve` is this: `dev` rebuilds, `serve` only serves. To
+check what will really be published, chain `build` then `serve`.
+
+## What was produced
+
+```
+dist/
+├── index.html              redirect to the current version
+├── versions.json           the versions and their URLs
+└── versions/
+    └── v1.0/
+        ├── index.html      the home page of the version
+        ├── assets/
+        │   └── docpensieve.css
+        └── guide/
+            └── installation/
+                └── index.html
+```
+
+Three things are worth noticing.
+
+**Each page is a folder with an `index.html`.** That is what gives URLs without
+an extension — `/guide/installation/` rather than `/guide/installation.html` —
+without asking anything of the host.
+
+**A single stylesheet for the whole version.** It is compiled last, once the
+pages are written, because a utility theme needs to know which classes were
+actually used in order to emit only those.
+
+**The `versions.json` at the root** describes the available versions. It is
+what lets versions built long ago stay online without ever rebuilding them.
+
+## Reading the output back
+
+A successful build says nothing of a dead link: nothing in the chain looks at
+them. A command takes care of it:
+
+```bash
+npx docpensieve build
+npx docpensieve check
+```
+
+It walks the produced pages, removes the deployment prefix from every internal
+target and checks that the file exists. It also reports the targets that
+**ignore** that prefix — the file is there, but the link will lead nowhere once
+online.
+
+```
+  index.html
+    /guide/installation/
+    → ignores the deployment prefix "/my-project/"
+```
+
+It is the check to run after any change of `baseUrl`, of folder structure or of
+URL.