@writedocs/generator 0.4.8 → 0.4.9

package/src/lib/pages.js

@@ -0,0 +1,78 @@
+// Which files in a content directory are pages. Plain JavaScript, not
+// TypeScript, so `writedocs validate` can load it with plain Node (Node
+// refuses to strip types under node_modules - see lib/icons.js's comment);
+// lib/config.ts re-exports findAllPages() for everything inside Astro.
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+// Top-level folders of a content directory that are never scanned for
+// pages - build output, dependencies, and static assets.
+export const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
+
+/** Recursively finds every .md/.mdx file under `contentDir` that has a
+ *  frontmatter block, skipping the handful of build/dependency
+ *  directories a real content directory tends to also contain (see
+ *  EXCLUDED_TOP_LEVEL_DIRS above) - docs/ is scanned exactly like any
+ *  other folder, no special-casing. Returns POSIX-relative paths (from
+ *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as
+ *  a literal `pattern` array - see content.config.ts's `pages`
+ *  collection, and [...slug].astro, which needs the identical list to
+ *  decide whether calling `getCollection('pages')` is worth doing at all
+ *  (see content.config.ts's own comment on why an empty collection still
+ *  needs to exist, just backed by a no-op loader, to avoid Astro's "does
+ *  not exist or is empty" warning). Also reused directly by
+ *  astro.config.mjs's noindex/sitemap scan and by `writedocs validate`, so
+ *  both always see exactly the same file set that actually becomes a page.
+ *  Synchronous and re-run from scratch wherever it's called rather than
+ *  cached and shared across modules - cheap enough in practice (a docs
+ *  site's own file count) not to matter. */
+export function findAllPages(contentDir) {
+  const results = [];
+  function walk(dir, relBase) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
+      let raw;
+      try {
+        raw = fs.readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      let data;
+      try {
+        ({ data } = matter(raw));
+      } catch {
+        // Frontmatter that isn't valid YAML: still a page (it opens a
+        // frontmatter block), so the error surfaces with this file's name -
+        // from `writedocs validate`, or Astro's own loader in the build -
+        // instead of as a bare YAML error thrown from here.
+        if (/^---\r?\n/.test(raw)) results.push(rel);
+        continue;
+      }
+      if (Object.keys(data).length === 0) continue; // no frontmatter at all - not a page
+      results.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  return results;
+}
+
+/** The id writedocs.json's navigation refers to a page by: its path from
+ *  the content directory, without the extension or a trailing `/index`
+ *  (same algorithm as fileIdForEntry() in lib/config.ts). */
+export function fileIdForPath(relativePath) {
+  return relativePath.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+}