@docpensieve/core 0.2.0-beta.1 → 0.3.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.2.0-beta.1",
+  "version": "0.3.0-beta.1",
   "description": "DocPensieve engine: loading, MDX compilation, structured data, site generation",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.2.0-beta.1",
+    "@docpensieve/shared": "0.3.0-beta.1",
     "@mdx-js/mdx": "^3.1.1",
     "@shikijs/rehype": "^4.4.3",
     "gray-matter": "^4.0.3",

package/src/config.js

@@ -36,7 +36,7 @@ import {
  * @property {string} baseUrl     Deployment prefix, slashes included.
  * @property {string} outDir      Output folder, relative to the root.
  * @property {Version[]} versions At least one.
- * @property {{ framework: string, darkMode?: string, tokens?: Record<string, string>, css?: string, source?: string }} theme
+ * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
@@ -67,7 +67,8 @@ export const DEFAULT_CONFIG = Object.freeze({
   baseUrl: '/',
   outDir: DEFAULT_OUT_DIR,
   versions: [],
-  theme: { framework: 'tailwind', darkMode: 'class' },
+  // The light / dark switch is on unless the project turns it off (ADR-014).
+  theme: { framework: 'tailwind', darkMode: 'class', toggle: true },
   sidebar: 'auto',
   globalComponents: true,
   scrollToTop: true,
@@ -322,6 +323,12 @@ export function normalizeConfig(userConfig) {
     });
   }
 
+  if (config.theme.toggle !== undefined && typeof config.theme.toggle !== 'boolean') {
+    throw new ConfigError('theme.toggle must be true or false.', {
+      hint: 'true adds a light / dark button to the header, with a few lines of inline script.',
+    });
+  }
+
   if (!THEME_FRAMEWORKS.includes(config.theme.framework)) {
     throw new ConfigError(`Unknown theme framework: "${config.theme.framework}".`, {
       hint: `Accepted values: ${THEME_FRAMEWORKS.join(', ')}.`,

package/src/generator.js

@@ -4,7 +4,7 @@
  * @module @docpensieve/core/generator
  */
 
-import { copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -184,6 +184,19 @@ export class SiteGenerator {
     const rootDir = this.config.rootDir ?? process.cwd();
     const target = path.resolve(rootDir, outDir);
 
+    // A page removed from the sources must not stay online: the version's
+    // folder is emptied before it is written — once it is certain to hold
+    // nothing but what a build wrote there.
+    this.#guardOutput(target);
+    try {
+      await rm(target, { recursive: true, force: true });
+    } catch (cause) {
+      throw new GeneratorError(`Could not empty the output folder "${target}".`, {
+        cause,
+        hint: 'Check that the path is a folder, and that nothing holds it open.',
+      });
+    }
+
     const sourceDir = path.resolve(rootDir, version.folder);
     const docs = await this.loader.load(sourceDir);
 
@@ -255,6 +268,8 @@ export class SiteGenerator {
           ? new URL(images.socialImage, this.config.siteUrl).href
           : '',
       searchUrl,
+      // The light / dark switch: a button, and the few lines of script it needs.
+      schemeToggle: this.config.theme?.toggle !== false,
       cls: classes,
       versions: this.#versionLinks(version.slug),
       // A switcher offering a single choice is not a switcher.
@@ -433,6 +448,40 @@ export class SiteGenerator {
     return buildSidebarFromDescription(description, docs, pageUrl, { source });
   }
 
+  /**
+   * Refuses an output folder the build could not empty without harm: the
+   * project itself, a folder above it, or one that holds a version's pages —
+   * or lies inside them. Checked before anything is deleted.
+   *
+   * @param {string} folder Absolute path.
+   * @throws {GeneratorError}
+   */
+  #guardOutput(folder) {
+    const rootDir = path.resolve(this.config.rootDir ?? process.cwd());
+    /** @param {string} child @param {string} parent */
+    const within = (child, parent) => {
+      const relative = path.relative(parent, child);
+      return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    };
+
+    if (within(rootDir, folder)) {
+      throw new GeneratorError(`The output folder "${folder}" holds the project itself.`, {
+        hint: 'Point outDir to a folder of its own, such as "dist": the build empties the folders it writes there.',
+      });
+    }
+    for (const version of this.config.versions) {
+      const sources = path.resolve(rootDir, version.folder);
+      if (within(sources, folder) || within(folder, sources)) {
+        throw new GeneratorError(
+          `The output folder "${folder}" overlaps the pages of version "${version.slug}".`,
+          {
+            hint: 'Keep outDir apart from the documentation folders: the build empties what it writes.',
+          },
+        );
+      }
+    }
+  }
+
   /**
    * Absolute address of the RSS feed, or `''` when none is written.
    *
@@ -455,6 +504,12 @@ export class SiteGenerator {
    *   Pages of each version, by slug.
    */
   async #writeDiscovery(target, published) {
+    // Written anew every time: a sitemap or a feed turned off since the last
+    // build must not linger at the root of the site.
+    for (const file of ['sitemap.xml', 'robots.txt', 'feed.xml']) {
+      await rm(path.join(target, file), { force: true });
+    }
+
     const { siteUrl, baseUrl } = this.config;
     if (!siteUrl) return;
 
@@ -545,6 +600,23 @@ export class SiteGenerator {
   async buildAll() {
     const rootDir = this.config.rootDir ?? process.cwd();
     const target = path.resolve(rootDir, this.config.outDir);
+    this.#guardOutput(target);
+
+    // The folder of a version no longer declared would stay online, unlisted
+    // but reachable. Everything else in the output folder is left alone.
+    const declared = new Set(this.config.versions.map((version) => version.slug));
+    /** @type {import('node:fs').Dirent[]} */
+    let existing;
+    try {
+      existing = await readdir(path.join(target, 'versions'), { withFileTypes: true });
+    } catch {
+      existing = [];
+    }
+    for (const entry of existing) {
+      if (entry.isDirectory() && !declared.has(entry.name)) {
+        await rm(path.join(target, 'versions', entry.name), { recursive: true, force: true });
+      }
+    }
 
     let pages = 0;
     /** @type {Map<string, import('./discovery.js').PublishedPage[]>} */

package/templates/layout.hbs

@@ -36,6 +36,11 @@
     <link rel="preload" as="{{as}}" href="{{href}}" />
     {{/each}}
     <link rel="stylesheet" href="{{cssHref}}" />
+    {{#if schemeToggle}}
+    {{!-- Before the first paint: the scheme the reader chose, not a flash of the
+    other one. --}}
+    <script>try{var s=localStorage.getItem('dp-scheme'),c=document.documentElement.classList;if(s==='dark'||s==='light'){c.remove('dark','light');c.add(s)}}catch(e){}</script>
+    {{/if}}
     {{!-- Only the search page carries a script: content pages load none. --}}
     {{#each scripts}}
     <script type="module" src="{{this}}"></script>
@@ -45,8 +50,13 @@
   <body>
     <a class="{{{cls.skip}}}" href="#content">Skip to content</a>
 
-    {{!-- Target of the back-to-top link: bring the focus back, not only the view. --}}
-    <header class="{{{cls.header}}}" id="top" tabindex="-1">
+    {{!-- Target of the back-to-top link: it brings the focus back, not only the
+    view. It stays out of the header on purpose — the header is sticky, so it
+    is already in view at any scroll position, and a browser asked to bring it
+    into view scrolled nowhere. --}}
+    <div id="top" tabindex="-1"></div>
+
+    <header class="{{{cls.header}}}">
       {{!-- The logo's alt stays empty: the name that follows already says it. --}}
       <a class="{{{cls.brand}}}" href="{{homeUrl}}">{{#if logoUrl}}<img class="{{{cls.brandLogo}}}" src="{{logoUrl}}" alt="" />{{/if}}{{projectName}}</a>
       {{#if showVersions}}
@@ -67,6 +77,13 @@
         <input type="search" name="q" placeholder="Search" aria-label="Search the documentation" />
       </form>
       {{/if}}
+      {{!-- Hidden until its script runs: without JavaScript, it would do nothing. --}}
+      {{#if schemeToggle}}
+      <button class="{{{cls.schemeToggle}}}" type="button" data-scheme-toggle hidden aria-label="Switch the colour scheme">
+        <svg class="dp-scheme-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg>
+        <svg class="dp-scheme-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4" /><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" /></svg>
+      </button>
+      {{/if}}
     </header>
 
     <div class="{{#if wide}}{{{cls.shellWide}}}{{else}}{{{cls.shell}}}{{/if}}">
@@ -120,5 +137,8 @@
       </svg>
     </a>
     {{/if}}
+    {{#if schemeToggle}}
+    <script>(function(){var b=document.querySelector('[data-scheme-toggle]');if(!b)return;var r=document.documentElement.classList;function dark(){return r.contains('dark')||(!r.contains('light')&&matchMedia('(prefers-color-scheme: dark)').matches)}function label(){b.setAttribute('aria-label',dark()?'Switch to light mode':'Switch to dark mode')}b.hidden=false;label();b.addEventListener('click',function(){var next=dark()?'light':'dark';r.remove('dark','light');r.add(next);try{localStorage.setItem('dp-scheme',next)}catch(e){}label()})})();</script>
+    {{/if}}
   </body>
 </html>

package/types/config.d.ts

@@ -62,6 +62,7 @@ export type DocPensieveConfig = {
     theme: {
         framework: string;
         darkMode?: string;
+        toggle?: boolean;
         tokens?: Record<string, string>;
         css?: string;
         source?: string;
@@ -134,7 +135,7 @@ export type DocPensieveConfig = {
  * @property {string} baseUrl     Deployment prefix, slashes included.
  * @property {string} outDir      Output folder, relative to the root.
  * @property {Version[]} versions At least one.
- * @property {{ framework: string, darkMode?: string, tokens?: Record<string, string>, css?: string, source?: string }} theme
+ * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.