@writedocs/generator 0.10.0 → 0.10.1

package/astro.config.mjs

@@ -37,6 +37,7 @@ import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.j
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import { mcpDevServer } from './src/lib/mcp-dev-integration.js';
+import { configReload } from './src/lib/config-reload-integration.js';
 import { canonicalPath } from './src/lib/canonical-path.js';
 import { folderAddresses } from './src/lib/folder-redirects.js';
 import { report } from './src/lib/cli-report.js';
@@ -324,6 +325,8 @@ export default defineConfig({
     // /mcp in `writedocs dev`, as the build's dist/_worker.js serves it -
     // see src/lib/mcp-dev-integration.js.
     mcpDevServer({ version: JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version }),
+    // writedocs dev: an edit to writedocs.json reloads the open tab.
+    configReload({ configPath: path.join(contentDir, 'writedocs.json') }),
   ],
   output: 'static',
   // Dual Shiki themes for fenced code blocks (```) in MDX content, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/dev.js

@@ -8,6 +8,7 @@ import { reportApiPages } from './api-pages-output.js';
 import { runningPreview, writeLock, removeLock } from './dev-lock.js';
 import { showUpdateNotice } from './update-check.js';
 import { shouldOpenBrowser, openBrowser } from './open-browser.js';
+import { watchPageList } from './page-list-watch.js';
 
 // The same problem tends to arrive more than once in a row - Vite and
 // Astro each log a failed page, and a page compiles for more than one
@@ -39,9 +40,13 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
   reportApiPages(api);
   api.warnings.forEach((message) => log.warn(message));
 
-  const starting = step('Starting local preview');
+  let starting = step('Starting local preview');
   let ready = false;
   let browserOpened = false;
+  // Restarting after pages were added or removed (see the watcher below):
+  // when that restart began, and the port to come back on.
+  let restartStarted = null;
+  let currentPort = port;
 
   const lastShown = new Map();
   const once = (key, print) => {
@@ -82,11 +87,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
 
   let fatal = null;
   const rawTail = [];
-  const { child, exited } = runAstro('dev', {
-    packageRoot,
-    contentDir,
-    port,
-    onEvent(event) {
+  const onEvent = (event) => {
       if (verbose) {
         const line = verboseLine(event);
         if (line !== null) log.line(color.dim(line));
@@ -94,11 +95,24 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
       switch (event.type) {
         case 'ready': {
           ready = true;
-          starting.succeed(`Preview ready ${color.dim(`in ${duration(Date.now() - started)}`)}`);
           const [local] = event.urls?.local ?? [];
           writeLock(packageRoot, { contentDir, url: local ?? null });
           const wanted = Number(port ?? 4321);
           const actual = local ? Number(new URL(local).port) : wanted;
+          currentPort = actual;
+          // Pages changed while it was starting: restart now that it's up.
+          if (restartPending) {
+            const change = restartPending;
+            restartPending = false;
+            setTimeout(() => restartForPages(change), 0);
+          }
+          // Back after a restart: one line - the open tab reloads by itself.
+          if (restartStarted !== null) {
+            starting.succeed(`Preview updated ${color.dim(`in ${duration(Date.now() - restartStarted)}`)}`);
+            restartStarted = null;
+            return;
+          }
+          starting.succeed(`Preview ready ${color.dim(`in ${duration(Date.now() - started)}`)}`);
           log.line();
           log.line(`  ${color.bold('Local:')}  ${color.cyan(local ?? `http://localhost:${wanted}/`)}`);
           if (actual !== wanted) log.line(color.dim(`          Port ${wanted} was in use, so the preview is on ${actual}.`));
@@ -129,6 +143,14 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
           if (rawTail.length > 40) rawTail.shift();
           return;
         case 'astro-log': {
+          // A page file just deleted: Astro's list of page modules
+          // (.astro/content-modules.mjs) still points at it for a moment -
+          // "Failed to load url ... Does the file exist?" - until the restart
+          // the page-list watcher starts brings in a fresh list. Noise, not a
+          // problem in the site. Every other error still shows, and a
+          // preview that can't start still reports through 'fatal'.
+          if (event.level === 'error' && /content-modules\.mjs/.test(event.message) && /Does the file exist/.test(event.message)) return;
+          if (restartStarted !== null && event.level === 'error') return;
           if (event.level === 'error') {
             showError(describeError(stripAnsi(event.message), contentDir, { root: packageRoot }));
             return;
@@ -145,7 +167,36 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
           return;
         }
       }
-    },
+  };
+
+  // Pages added or removed while the preview runs: its page list is read
+  // when it starts, so it restarts - on the same port; the open tab
+  // reconnects and reloads by itself. Edits to pages and to writedocs.json
+  // don't need this (lib/config-reload-integration.js).
+  let child = null;
+  let restarting = false;
+  let restartPending = false;
+  const restartForPages = ({ added, removed }) => {
+    const what = [
+      ...added.slice(0, 3).map((file) => `${file} added`),
+      ...removed.slice(0, 3).map((file) => `${file} removed`),
+    ];
+    const more = added.length + removed.length - what.length;
+    log.info(`${what.join(', ')}${more > 0 ? ` and ${more} more` : ''} - restarting the preview so the page list is current.`);
+    restarting = true;
+    ready = false;
+    restartStarted = Date.now();
+    starting = step('Restarting the preview');
+    child?.kill();
+  };
+  const pageWatch = watchPageList(contentDir, (change) => {
+    if (stopping || restarting) return;
+    // Still starting: restart once it's up, not halfway.
+    if (!ready) {
+      restartPending = change;
+      return;
+    }
+    restartForPages(change);
   });
 
   // Ctrl+C: stop the server quietly. (The child gets the same signal from
@@ -155,12 +206,23 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false, o
   const stop = () => {
     if (stopping) process.exit(130);
     stopping = true;
-    child.kill();
+    pageWatch.close();
+    child?.kill();
   };
   process.on('SIGINT', stop);
   process.on('SIGTERM', stop);
 
-  const code = await exited;
+  let code;
+  for (;;) {
+    fatal = null;
+    rawTail.length = 0;
+    const run = runAstro('dev', { packageRoot, contentDir, port: currentPort, onEvent });
+    child = run.child;
+    code = await run.exited;
+    if (stopping || !restarting) break;
+    restarting = false;
+  }
+  pageWatch.close();
   if (stopping) {
     if (ready) log.line(color.dim('Preview stopped.'));
     return;

package/src/cli/page-list-watch.js

@@ -0,0 +1,66 @@
+// `writedocs dev`: noticing pages added or removed. The preview's list of page
+// files is read once, when it starts (content.config.ts hands findAllPages()'s
+// list to Astro) - an edit to a page shows up at once, but a new page stays
+// "not found" and a deleted one keeps being served. So this watches the
+// content folder, and when the list findAllPages() gives changes, calls
+// `onChange` - cli/dev.js restarts the preview then.
+//
+// It compares the list itself, not file events: a Markdown file that isn't
+// a page (no frontmatter, not in the navigation), an edit to a page, or a
+// save that writes a file twice doesn't restart anything.
+import fs from 'node:fs';
+import { findAllPages, EXCLUDED_TOP_LEVEL_DIRS } from '../lib/pages.js';
+
+/** Wait this long after the last file event before checking - a rename, a
+ *  copy of several files or an editor's save arrive as a burst of events. */
+export const SETTLE_MS = 400;
+
+/** Whether a changed file can change the page list: a .md/.mdx file, or
+ *  writedocs.json (it lists pages that have no frontmatter), outside the
+ *  folders findAllPages() never looks in. */
+export function mayChangePages(relative) {
+  if (!relative) return true;
+  const parts = String(relative).split(/[\\/]/);
+  if (EXCLUDED_TOP_LEVEL_DIRS.has(parts[0]) || parts.some((part) => part.startsWith('.'))) return false;
+  const name = parts[parts.length - 1];
+  return /\.mdx?$/i.test(name) || name === 'writedocs.json';
+}
+
+/** Starts watching; returns `{ close }`. `onChange({ added, removed })` gets
+ *  the page files (relative paths) that came and went. */
+export function watchPageList(contentDir, onChange, { settleMs = SETTLE_MS } = {}) {
+  let current = new Set(findAllPages(contentDir));
+  let timer = null;
+  const check = () => {
+    let next;
+    try {
+      next = new Set(findAllPages(contentDir));
+    } catch {
+      return; // mid-save, or a folder being moved - the next event checks again
+    }
+    const added = [...next].filter((file) => !current.has(file));
+    const removed = [...current].filter((file) => !next.has(file));
+    if (!added.length && !removed.length) return;
+    current = next;
+    onChange({ added, removed });
+  };
+  let watcher;
+  try {
+    watcher = fs.watch(contentDir, { recursive: true }, (_event, filename) => {
+      if (!mayChangePages(filename)) return;
+      clearTimeout(timer);
+      timer = setTimeout(check, settleMs);
+    });
+    watcher.on('error', () => {});
+  } catch {
+    // A file system without recursive watching: pages added while `dev`
+    // runs need a restart, as before.
+    return { close() {} };
+  }
+  return {
+    close() {
+      clearTimeout(timer);
+      watcher.close();
+    },
+  };
+}

package/src/lib/config-reload-integration.js

@@ -0,0 +1,32 @@
+// `writedocs dev`: an edit to writedocs.json reloads the open tab. The server
+// already renders with the new file on the next request (lib/config.ts reads
+// it each time), but nothing told the browser - the tab kept the old
+// navigation until reloaded by hand. writedocs.json sits in the content
+// folder, outside what Vite watches, so it's added to the watcher here, and
+// a change sends Vite's full-reload.
+//
+// Pages added or removed need more than a reload - see cli/page-list-watch.js.
+import path from 'node:path';
+
+/** Wait this long after the last change before reloading - an editor's save
+ *  can arrive as more than one write. */
+export const RELOAD_DELAY_MS = 150;
+
+export function configReload({ configPath }) {
+  return {
+    name: 'writedocs-config-reload',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        const target = path.resolve(configPath);
+        const same = (file) => path.resolve(file).toLowerCase() === target.toLowerCase();
+        server.watcher.add(target);
+        let timer = null;
+        server.watcher.on('change', (file) => {
+          if (!same(file)) return;
+          clearTimeout(timer);
+          timer = setTimeout(() => server.ws.send({ type: 'full-reload', path: '*' }), RELOAD_DELAY_MS);
+        });
+      },
+    },
+  };
+}