@pterodoc/docusaurus 0.2.0

package/LICENCE.md

@@ -0,0 +1,10 @@
+Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) Onyx <hello@onyx.ac> (https://onyx.ac)
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. You are free to share and adapt this work, including
+commercially, provided you give appropriate attribution and distribute any
+derivative works under the same license.
+
+Full legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,10 @@
+# @pterodoc/docusaurus
+
+Reads a [pterodoc](https://github.com/onyx-ac/pterodoc) site model out of Docusaurus,
+through Docusaurus's own site loader — so resolved sidebars, versions, locales,
+permalinks and draft flags all come from the same code that builds your site.
+
+You probably want the [`pterodoc`](https://www.npmjs.com/package/pterodoc) package
+instead.
+
+Licensed CC-BY-SA-4.0.

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Everything that knows Docusaurus exists.
+ *
+ * The model vocabulary it produces belongs to `src/model`; it is re-exported
+ * here so a caller that thinks in Docusaurus terms has one import.
+ */
+export type { Doc, DocNeighbour, DocsInstance, DocsVersion, SidebarCategoryItem, SidebarCategoryLink, SidebarDocItem, SidebarHtmlItem, SidebarItem, SidebarLinkItem, SiteModel, } from '@pterodoc/core/model';
+export { buildPageTree } from '@pterodoc/core/model';
+export type { BuildPageTreeInput, PageKind, PageNode, PageTree } from '@pterodoc/core/model';
+export { createCaptureReader, readCapture, writeCapture, serializeModel } from '@pterodoc/core/model';
+export type { CapturedModel } from '@pterodoc/core/model';
+export { createMemoryReader } from '@pterodoc/core/model';
+export type { SourceReader } from '@pterodoc/core/model';
+export { loadModel, toSiteModel } from './model';
+export type { LoadModelOptions } from './model';
+export { loadDocusaurusServer, SUPPORTED_RANGE } from './server';
+export type { DocusaurusServer, LoadedSite, LoadSiteParams } from './server';
+export { createDocusaurusReader, readerFromLoadedSite } from './reader';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,GAAG,EACH,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,EACf,SAAS,GACV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtG,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/lib/index.js

@@ -0,0 +1,276 @@
+import { createMemoryReader } from '@pterodoc/core/model';
+export { buildPageTree, createCaptureReader, createMemoryReader, readCapture, serializeModel, writeCapture } from '@pterodoc/core/model';
+import path from 'node:path';
+import { DEFAULT_ADMONITION_KEYWORDS, detectFormat } from '@pterodoc/core/render';
+import { ConfigError, resolveAliasedPath, relativeToPrefix, toPosix } from '@pterodoc/core/util';
+import { createRequire } from 'node:module';
+
+/**
+ * Loading Docusaurus's own site loader.
+ *
+ * `loadSite` runs every plugin's content lifecycle and hands back the resolved
+ * site, which is the whole reason this tool does not re-derive sidebars,
+ * versions or permalinks. It lives at a path Docusaurus does not advertise, so
+ * the import is guarded and fails with something a reader can act on.
+ */
+/** Docusaurus versions this tool has been checked against. */
+const SUPPORTED_RANGE = { min: 3, maxExclusive: 4 };
+/** Paths tried, in order, when looking for the site loader. */
+const CANDIDATES = ['lib/server/site.js', 'server.js', 'lib/server/index.js'];
+/**
+ * Find and load Docusaurus's site loader, resolving it from the site rather
+ * than from pterodoc so a hoisted or a nested install both work.
+ *
+ * @param siteDir Absolute path of the Docusaurus site directory.
+ * @param warn Called with a message when the version is outside the tested range.
+ */
+function loadDocusaurusServer(siteDir, warn = () => { }) {
+    const requireFromSite = createRequire(path.join(siteDir, 'noop.js'));
+    let corePackagePath;
+    try {
+        corePackagePath = requireFromSite.resolve('@docusaurus/core/package.json');
+    }
+    catch {
+        throw new ConfigError(`Could not find @docusaurus/core from ${siteDir}. pterodoc reads a Docusaurus site using Docusaurus itself, so it has to run inside the site's own project. Use --site-dir to point at it, or --model to render from a captured model instead.`);
+    }
+    const corePackage = requireFromSite(corePackagePath);
+    const version = corePackage.version ?? '0.0.0';
+    const major = Number.parseInt(version.split('.')[0] ?? '0', 10);
+    if (major < SUPPORTED_RANGE.min || major >= SUPPORTED_RANGE.maxExclusive) {
+        warn(`This is Docusaurus ${version}; pterodoc has been checked against ${SUPPORTED_RANGE.min}.x. Continuing, but the site model may not load.`);
+    }
+    const coreDir = path.dirname(corePackagePath);
+    const tried = [];
+    for (const candidate of CANDIDATES) {
+        const candidatePath = path.join(coreDir, candidate);
+        tried.push(candidatePath);
+        try {
+            const loaded = requireFromSite(candidatePath);
+            if (typeof loaded.loadSite === 'function') {
+                return { loadSite: loaded.loadSite, version };
+            }
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    throw new ConfigError(`Docusaurus ${version} is installed but its site loader was not where pterodoc expected it.\n` +
+        `Tried:\n${tried.map((entry) => `  ${entry}`).join('\n')}\n` +
+        'This usually means a Docusaurus release moved it. Capture a model on a working version with `pterodoc capture`, then render from it with `--model`, and please report the version.');
+}
+
+/**
+ * Normalising Docusaurus's loaded state into the site model.
+ *
+ * The mapping is deliberately thin: almost every field is copied, because the
+ * point of loading Docusaurus is to inherit its answers rather than to
+ * second-guess them.
+ */
+/** Name Docusaurus gives the docs plugin. */
+const DOCS_PLUGIN = 'docusaurus-plugin-content-docs';
+/** Read a nested property without pretending to know the whole shape. */
+function get(source, keys, fallback) {
+    let current = source;
+    for (const key of keys) {
+        if (current === null || typeof current !== 'object')
+            return fallback;
+        current = current[key];
+    }
+    return (current ?? fallback);
+}
+/** Docusaurus's admonition option is `true`, or an object that may extend the defaults. */
+function admonitionKeywords(options) {
+    const admonitions = options['admonitions'];
+    if (admonitions === false)
+        return [];
+    if (admonitions === true || admonitions === undefined)
+        return [...DEFAULT_ADMONITION_KEYWORDS];
+    const keywords = get(admonitions, ['keywords'], undefined);
+    const extendDefaults = get(admonitions, ['extendDefaults'], true);
+    if (!keywords)
+        return [...DEFAULT_ADMONITION_KEYWORDS];
+    return extendDefaults ? [...new Set([...DEFAULT_ADMONITION_KEYWORDS, ...keywords])] : [...keywords];
+}
+/** Turn one of Docusaurus's loaded documents into ours. */
+function toDoc(raw, version, siteDir, siteFormat) {
+    const sourceAliased = String(raw['source'] ?? '');
+    const sourceAbsolutePath = resolveAliasedPath(sourceAliased, siteDir);
+    const permalink = String(raw['permalink'] ?? '');
+    const frontMatter = (raw['frontMatter'] ?? {});
+    const declaredFormat = frontMatter['format'];
+    const format = declaredFormat === 'md' || declaredFormat === 'mdx'
+        ? declaredFormat
+        : siteFormat === 'detect'
+            ? detectFormat(sourceAbsolutePath)
+            : siteFormat;
+    return {
+        id: String(raw['id'] ?? ''),
+        versionName: version.name,
+        title: String(raw['title'] ?? ''),
+        description: String(raw['description'] ?? ''),
+        sourceAliased,
+        sourceAbsolutePath,
+        sourceRelativePath: toPosix(path.relative(siteDir, sourceAbsolutePath)),
+        sourceDirName: String(raw['sourceDirName'] ?? '.'),
+        slug: String(raw['slug'] ?? ''),
+        permalink,
+        // The position in the published tree is the permalink with the version's
+        // own prefix removed, so front-matter slugs are honoured for free.
+        treePath: relativeToPrefix(permalink, version.pathPrefix) ?? '',
+        draft: raw['draft'] === true,
+        unlisted: raw['unlisted'] === true,
+        frontMatter,
+        sidebarName: raw['sidebar'] ?? undefined,
+        sidebarPosition: raw['sidebarPosition'] ?? undefined,
+        previous: raw['previous'] ?? undefined,
+        next: raw['next'] ?? undefined,
+        tags: raw['tags'] ?? [],
+        format,
+    };
+}
+/** Turn one of Docusaurus's loaded versions into ours. */
+function toVersion(raw, siteDir, siteFormat, includeDrafts) {
+    const name = String(raw['versionName'] ?? 'current');
+    const pathPrefix = String(raw['path'] ?? '');
+    const contentPath = String(raw['contentPath'] ?? '');
+    const published = raw['docs'] ?? [];
+    const drafts = raw['drafts'] ?? [];
+    const source = includeDrafts ? [...published, ...drafts] : published;
+    return {
+        name,
+        label: String(raw['label'] ?? name),
+        isLast: raw['isLast'] === true,
+        pathPrefix,
+        contentPath,
+        contentPathLocalized: String(raw['contentPathLocalized'] ?? contentPath),
+        banner: raw['banner'] ?? null,
+        noIndex: raw['noIndex'] === true,
+        sidebars: raw['sidebars'] ?? {},
+        docs: source.map((doc) => toDoc(doc, { name, pathPrefix }, siteDir, siteFormat)),
+        draftCount: drafts.length,
+    };
+}
+/** Keep only the versions the caller asked for. */
+function selectVersions(versions, selector) {
+    if (selector === 'all')
+        return versions;
+    if (Array.isArray(selector))
+        return versions.filter((version) => selector.includes(version.name));
+    const last = versions.find((version) => version.isLast);
+    return last ? [last] : versions.slice(0, 1);
+}
+/**
+ * Normalise a loaded Docusaurus site into the model.
+ *
+ * Exposed separately from {@link loadModel} so the plugin, which already has
+ * the loaded state, can reuse it without loading the site again.
+ */
+function toSiteModel(site, options) {
+    const { props } = site;
+    const siteDir = props.siteDir;
+    const siteConfig = props.siteConfig;
+    const siteFormat = get(siteConfig, ['markdown', 'format'], 'mdx');
+    const staticDirectories = get(siteConfig, ['staticDirectories'], ['static']);
+    const instances = props.plugins
+        .filter((plugin) => plugin.name === DOCS_PLUGIN)
+        .map((plugin) => {
+        const loadedVersions = get(plugin.content, ['loadedVersions'], []) ?? [];
+        const versions = loadedVersions.map((version) => toVersion(version, siteDir, siteFormat, options.includeDrafts === true));
+        return {
+            id: String(plugin.options['id'] ?? 'default'),
+            routeBasePath: String(plugin.options['routeBasePath'] ?? 'docs'),
+            contentDirName: String(plugin.options['path'] ?? 'docs'),
+            admonitionKeywords: admonitionKeywords(plugin.options),
+            breadcrumbs: plugin.options['breadcrumbs'] !== false,
+            versions: selectVersions(versions, options.versions),
+        };
+    })
+        .filter((instance) => options.instances === undefined ||
+        options.instances === 'all' ||
+        options.instances.includes(instance.id));
+    return {
+        siteDir,
+        url: String(siteConfig['url'] ?? ''),
+        baseUrl: props.baseUrl,
+        trailingSlash: siteConfig['trailingSlash'],
+        locale: props.i18n.currentLocale,
+        defaultLocale: props.i18n.defaultLocale,
+        locales: props.i18n.locales,
+        markdownFormat: siteFormat,
+        maintainCase: get(siteConfig, ['markdown', 'anchors', 'maintainCase'], false),
+        siteTitle: String(siteConfig['title'] ?? ''),
+        staticDirs: staticDirectories.map((dir) => path.resolve(siteDir, dir)),
+        docusaurusVersion: props.siteMetadata.docusaurusVersion,
+        instances,
+    };
+}
+/**
+ * Load a Docusaurus site and normalise it.
+ *
+ * One call loads one locale, because that is what Docusaurus's own loader
+ * does; publishing several locales means calling this once for each.
+ */
+async function loadModel(options) {
+    const warn = options.warn ?? (() => { });
+    const server = loadDocusaurusServer(options.siteDir, warn);
+    // Docusaurus's own CLI always runs from the site directory, and plugins rely
+    // on it: a typedoc entry point of `../client/src/index.ts`, for instance, is
+    // resolved against the working directory rather than the site. Loading from
+    // anywhere else makes those plugins look in the wrong place.
+    const previousCwd = process.cwd();
+    process.chdir(options.siteDir);
+    // Docusaurus only drops drafts and applies production behaviour when
+    // NODE_ENV says so, and publishing is a production act. Without this a draft
+    // reaches the site, which is precisely what marking it a draft asked to
+    // avoid.
+    const previousNodeEnv = process.env['NODE_ENV'];
+    process.env['NODE_ENV'] = 'production';
+    try {
+        const site = await server.loadSite({
+            siteDir: options.siteDir,
+            locale: options.locale,
+            config: options.configPath,
+        });
+        return toSiteModel(site, options);
+    }
+    finally {
+        process.chdir(previousCwd);
+        if (previousNodeEnv === undefined)
+            delete process.env['NODE_ENV'];
+        else
+            process.env['NODE_ENV'] = previousNodeEnv;
+    }
+}
+
+/**
+ * Reading a model out of a real Docusaurus site.
+ *
+ * The reader interface and the sources that need no Docusaurus live in
+ * `src/model`; this is the one that does.
+ */
+/** Read from a real Docusaurus site, one locale at a time. */
+function createDocusaurusReader(options) {
+    let firstLocale;
+    return {
+        kind: 'docusaurus',
+        async locales() {
+            firstLocale ??= await loadModel(options);
+            return firstLocale.locales;
+        },
+        async read(locale) {
+            if (firstLocale && (locale === undefined || locale === firstLocale.locale)) {
+                return firstLocale;
+            }
+            const model = await loadModel({ ...options, locale });
+            firstLocale ??= model;
+            return model;
+        },
+    };
+}
+/** Build a model from a site the caller has already loaded. */
+function readerFromLoadedSite(site, options) {
+    return createMemoryReader(toSiteModel(site, options));
+}
+
+export { SUPPORTED_RANGE, createDocusaurusReader, loadDocusaurusServer, loadModel, readerFromLoadedSite, toSiteModel };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/server.ts","../src/model.ts","../src/reader.ts"],"sourcesContent":[null,null,null],"names":[],"mappings":"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"}

package/lib/model.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Normalising Docusaurus's loaded state into the site model.
+ *
+ * The mapping is deliberately thin: almost every field is copied, because the
+ * point of loading Docusaurus is to inherit its answers rather than to
+ * second-guess them.
+ */
+import { type LoadedSite } from './server';
+import type { SiteModel } from '@pterodoc/core/model';
+/** What to load, and which parts of it to keep. */
+export interface LoadModelOptions {
+    /** Absolute path of the Docusaurus site directory. */
+    siteDir: string;
+    /** Locale to load; one call loads exactly one locale. */
+    locale?: string | undefined;
+    /** Explicit `docusaurus.config.*` path. */
+    configPath?: string | undefined;
+    /** Docs plugin instance ids to keep, or 'all'. */
+    instances?: string[] | 'all' | undefined;
+    /** Versions to keep: 'last', 'all', or explicit names. */
+    versions?: string[] | 'all' | 'last' | undefined;
+    /** Publish draft documents. Docusaurus normally drops them from a build. */
+    includeDrafts?: boolean | undefined;
+    /** Called with warnings raised while loading. */
+    warn?: ((message: string) => void) | undefined;
+}
+/**
+ * Normalise a loaded Docusaurus site into the model.
+ *
+ * Exposed separately from {@link loadModel} so the plugin, which already has
+ * the loaded state, can reuse it without loading the site again.
+ */
+export declare function toSiteModel(site: LoadedSite, options: LoadModelOptions): SiteModel;
+/**
+ * Load a Docusaurus site and normalise it.
+ *
+ * One call loads one locale, because that is what Docusaurus's own loader
+ * does; publishing several locales means calling this once for each.
+ */
+export declare function loadModel(options: LoadModelOptions): Promise<SiteModel>;
+//# sourceMappingURL=model.d.ts.map

package/lib/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAA+C,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKnG,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,SAAS,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IACjD,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,iDAAiD;IACjD,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAChD;AA4GD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA8ClF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8B7E"}

package/lib/reader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reading a model out of a real Docusaurus site.
+ *
+ * The reader interface and the sources that need no Docusaurus live in
+ * `src/model`; this is the one that does.
+ */
+import { type LoadModelOptions } from './model';
+import type { LoadedSite } from './server';
+import { type SourceReader } from '@pterodoc/core/model';
+/** Read from a real Docusaurus site, one locale at a time. */
+export declare function createDocusaurusReader(options: LoadModelOptions): SourceReader;
+/** Build a model from a site the caller has already loaded. */
+export declare function readerFromLoadedSite(site: LoadedSite, options: LoadModelOptions): SourceReader;
+//# sourceMappingURL=reader.d.ts.map

package/lib/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAsB,KAAK,YAAY,EAAkB,MAAM,sBAAsB,CAAC;AAE7F,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAkB9E;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAE9F"}

package/lib/server.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Loading Docusaurus's own site loader.
+ *
+ * `loadSite` runs every plugin's content lifecycle and hands back the resolved
+ * site, which is the whole reason this tool does not re-derive sidebars,
+ * versions or permalinks. It lives at a path Docusaurus does not advertise, so
+ * the import is guarded and fails with something a reader can act on.
+ */
+/** Docusaurus versions this tool has been checked against. */
+export declare const SUPPORTED_RANGE: {
+    min: number;
+    maxExclusive: number;
+};
+/** What `loadSite` gives back, narrowed to the parts we read. */
+export interface LoadedSite {
+    props: {
+        siteDir: string;
+        siteConfig: Record<string, unknown>;
+        siteConfigPath: string;
+        baseUrl: string;
+        outDir: string;
+        generatedFilesDir: string;
+        i18n: {
+            defaultLocale: string;
+            locales: string[];
+            currentLocale: string;
+            localeConfigs: Record<string, {
+                htmlLang?: string;
+                direction?: string;
+            }>;
+        };
+        siteMetadata: {
+            docusaurusVersion: string;
+        };
+        plugins: Array<{
+            name: string;
+            options: Record<string, unknown>;
+            content: unknown;
+        }>;
+    };
+}
+/** Options `loadSite` accepts. */
+export interface LoadSiteParams {
+    siteDir: string;
+    locale?: string | undefined;
+    config?: string | undefined;
+    outDir?: string | undefined;
+}
+/** The shape of the Docusaurus module we depend on. */
+export interface DocusaurusServer {
+    /** Run the content lifecycle and return the resolved site. */
+    loadSite(params: LoadSiteParams): Promise<LoadedSite>;
+    /** The Docusaurus version that was loaded. */
+    version: string;
+}
+/**
+ * Find and load Docusaurus's site loader, resolving it from the site rather
+ * than from pterodoc so a hoisted or a nested install both work.
+ *
+ * @param siteDir Absolute path of the Docusaurus site directory.
+ * @param warn Called with a message when the version is outside the tested range.
+ */
+export declare function loadDocusaurusServer(siteDir: string, warn?: (message: string) => void): DocusaurusServer;
+//# sourceMappingURL=server.d.ts.map

package/lib/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,8DAA8D;AAC9D,eAAO,MAAM,eAAe;;;CAA8B,CAAC;AAK3D,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,IAAI,EAAE;YACJ,aAAa,EAAE,MAAM,CAAC;YACtB,OAAO,EAAE,MAAM,EAAE,CAAC;YAClB,aAAa,EAAE,MAAM,CAAC;YACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE;gBAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC1E,CAAC;QACF,YAAY,EAAE;YAAE,iBAAiB,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5C,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACjC,OAAO,EAAE,OAAO,CAAC;SAClB,CAAC,CAAC;KACJ,CAAC;CACH;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,GACzC,gBAAgB,CAyClB"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pterodoc/docusaurus",
+  "version": "0.2.0",
+  "description": "Reads a pterodoc site model out of Docusaurus, using Docusaurus's own site loader.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib", "src", "README.md", "LICENCE.md"],
+  "engines": { "node": ">=20.11" },
+  "scripts": {
+    "build": "tsc -b --force && rollup -c",
+    "test": "node ../../scripts/tests.mjs integration"
+  },
+  "dependencies": {
+    "@pterodoc/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": ">=3.6.0 <4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@docusaurus/core": { "optional": true }
+  },
+  "devDependencies": {
+    "@docusaurus/core": "3.10.2",
+    "@docusaurus/preset-classic": "3.10.2",
+    "@docusaurus/types": "3.10.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/onyx-ac/pterodoc.git" },
+  "license": "CC-BY-SA-4.0",
+  "publishConfig": { "access": "public" }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Everything that knows Docusaurus exists.
+ *
+ * The model vocabulary it produces belongs to `src/model`; it is re-exported
+ * here so a caller that thinks in Docusaurus terms has one import.
+ */
+
+export type {
+  Doc,
+  DocNeighbour,
+  DocsInstance,
+  DocsVersion,
+  SidebarCategoryItem,
+  SidebarCategoryLink,
+  SidebarDocItem,
+  SidebarHtmlItem,
+  SidebarItem,
+  SidebarLinkItem,
+  SiteModel,
+} from '@pterodoc/core/model';
+export { buildPageTree } from '@pterodoc/core/model';
+export type { BuildPageTreeInput, PageKind, PageNode, PageTree } from '@pterodoc/core/model';
+export { createCaptureReader, readCapture, writeCapture, serializeModel } from '@pterodoc/core/model';
+export type { CapturedModel } from '@pterodoc/core/model';
+export { createMemoryReader } from '@pterodoc/core/model';
+export type { SourceReader } from '@pterodoc/core/model';
+export { loadModel, toSiteModel } from './model';
+export type { LoadModelOptions } from './model';
+export { loadDocusaurusServer, SUPPORTED_RANGE } from './server';
+export type { DocusaurusServer, LoadedSite, LoadSiteParams } from './server';
+export { createDocusaurusReader, readerFromLoadedSite } from './reader';

package/src/model.ts

@@ -0,0 +1,233 @@
+/**
+ * Normalising Docusaurus's loaded state into the site model.
+ *
+ * The mapping is deliberately thin: almost every field is copied, because the
+ * point of loading Docusaurus is to inherit its answers rather than to
+ * second-guess them.
+ */
+
+import path from 'node:path';
+import { detectFormat, type MarkdownFormat } from '@pterodoc/core/render';
+import { relativeToPrefix, resolveAliasedPath, toPosix } from '@pterodoc/core/util';
+import { DEFAULT_ADMONITION_KEYWORDS } from '@pterodoc/core/render';
+import { loadDocusaurusServer, type LoadedSite } from './server';
+import type { Doc, DocsInstance, DocsVersion, SidebarItem, SiteModel } from '@pterodoc/core/model';
+
+/** Name Docusaurus gives the docs plugin. */
+const DOCS_PLUGIN = 'docusaurus-plugin-content-docs';
+
+/** What to load, and which parts of it to keep. */
+export interface LoadModelOptions {
+  /** Absolute path of the Docusaurus site directory. */
+  siteDir: string;
+  /** Locale to load; one call loads exactly one locale. */
+  locale?: string | undefined;
+  /** Explicit `docusaurus.config.*` path. */
+  configPath?: string | undefined;
+  /** Docs plugin instance ids to keep, or 'all'. */
+  instances?: string[] | 'all' | undefined;
+  /** Versions to keep: 'last', 'all', or explicit names. */
+  versions?: string[] | 'all' | 'last' | undefined;
+  /** Publish draft documents. Docusaurus normally drops them from a build. */
+  includeDrafts?: boolean | undefined;
+  /** Called with warnings raised while loading. */
+  warn?: ((message: string) => void) | undefined;
+}
+
+/** Read a nested property without pretending to know the whole shape. */
+function get<T>(source: unknown, keys: string[], fallback: T): T {
+  let current: unknown = source;
+  for (const key of keys) {
+    if (current === null || typeof current !== 'object') return fallback;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return (current ?? fallback) as T;
+}
+
+/** Docusaurus's admonition option is `true`, or an object that may extend the defaults. */
+function admonitionKeywords(options: Record<string, unknown>): string[] {
+  const admonitions = options['admonitions'];
+  if (admonitions === false) return [];
+  if (admonitions === true || admonitions === undefined) return [...DEFAULT_ADMONITION_KEYWORDS];
+
+  const keywords = get<string[] | undefined>(admonitions, ['keywords'], undefined);
+  const extendDefaults = get<boolean>(admonitions, ['extendDefaults'], true);
+  if (!keywords) return [...DEFAULT_ADMONITION_KEYWORDS];
+  return extendDefaults ? [...new Set([...DEFAULT_ADMONITION_KEYWORDS, ...keywords])] : [...keywords];
+}
+
+/** Turn one of Docusaurus's loaded documents into ours. */
+function toDoc(
+  raw: Record<string, unknown>,
+  version: { name: string; pathPrefix: string },
+  siteDir: string,
+  siteFormat: 'md' | 'mdx' | 'detect',
+): Doc {
+  const sourceAliased = String(raw['source'] ?? '');
+  const sourceAbsolutePath = resolveAliasedPath(sourceAliased, siteDir);
+  const permalink = String(raw['permalink'] ?? '');
+  const frontMatter = (raw['frontMatter'] ?? {}) as Record<string, unknown>;
+
+  const declaredFormat = frontMatter['format'];
+  const format: MarkdownFormat =
+    declaredFormat === 'md' || declaredFormat === 'mdx'
+      ? declaredFormat
+      : siteFormat === 'detect'
+        ? detectFormat(sourceAbsolutePath)
+        : siteFormat;
+
+  return {
+    id: String(raw['id'] ?? ''),
+    versionName: version.name,
+    title: String(raw['title'] ?? ''),
+    description: String(raw['description'] ?? ''),
+    sourceAliased,
+    sourceAbsolutePath,
+    sourceRelativePath: toPosix(path.relative(siteDir, sourceAbsolutePath)),
+    sourceDirName: String(raw['sourceDirName'] ?? '.'),
+    slug: String(raw['slug'] ?? ''),
+    permalink,
+    // The position in the published tree is the permalink with the version's
+    // own prefix removed, so front-matter slugs are honoured for free.
+    treePath: relativeToPrefix(permalink, version.pathPrefix) ?? '',
+    draft: raw['draft'] === true,
+    unlisted: raw['unlisted'] === true,
+    frontMatter,
+    sidebarName: (raw['sidebar'] as string | undefined) ?? undefined,
+    sidebarPosition: (raw['sidebarPosition'] as number | undefined) ?? undefined,
+    previous: (raw['previous'] as Doc['previous']) ?? undefined,
+    next: (raw['next'] as Doc['next']) ?? undefined,
+    tags: (raw['tags'] as Doc['tags']) ?? [],
+    format,
+  };
+}
+
+/** Turn one of Docusaurus's loaded versions into ours. */
+function toVersion(
+  raw: Record<string, unknown>,
+  siteDir: string,
+  siteFormat: 'md' | 'mdx' | 'detect',
+  includeDrafts: boolean,
+): DocsVersion {
+  const name = String(raw['versionName'] ?? 'current');
+  const pathPrefix = String(raw['path'] ?? '');
+  const contentPath = String(raw['contentPath'] ?? '');
+
+  const published = (raw['docs'] as Record<string, unknown>[] | undefined) ?? [];
+  const drafts = (raw['drafts'] as Record<string, unknown>[] | undefined) ?? [];
+  const source = includeDrafts ? [...published, ...drafts] : published;
+
+  return {
+    name,
+    label: String(raw['label'] ?? name),
+    isLast: raw['isLast'] === true,
+    pathPrefix,
+    contentPath,
+    contentPathLocalized: String(raw['contentPathLocalized'] ?? contentPath),
+    banner: (raw['banner'] as DocsVersion['banner']) ?? null,
+    noIndex: raw['noIndex'] === true,
+    sidebars: (raw['sidebars'] as Record<string, SidebarItem[]> | undefined) ?? {},
+    docs: source.map((doc) => toDoc(doc, { name, pathPrefix }, siteDir, siteFormat)),
+    draftCount: drafts.length,
+  };
+}
+
+/** Keep only the versions the caller asked for. */
+function selectVersions(versions: DocsVersion[], selector: LoadModelOptions['versions']): DocsVersion[] {
+  if (selector === 'all') return versions;
+  if (Array.isArray(selector)) return versions.filter((version) => selector.includes(version.name));
+  const last = versions.find((version) => version.isLast);
+  return last ? [last] : versions.slice(0, 1);
+}
+
+/**
+ * Normalise a loaded Docusaurus site into the model.
+ *
+ * Exposed separately from {@link loadModel} so the plugin, which already has
+ * the loaded state, can reuse it without loading the site again.
+ */
+export function toSiteModel(site: LoadedSite, options: LoadModelOptions): SiteModel {
+  const { props } = site;
+  const siteDir = props.siteDir;
+  const siteConfig = props.siteConfig;
+  const siteFormat = get<'md' | 'mdx' | 'detect'>(siteConfig, ['markdown', 'format'], 'mdx');
+  const staticDirectories = get<string[]>(siteConfig, ['staticDirectories'], ['static']);
+
+  const instances: DocsInstance[] = props.plugins
+    .filter((plugin) => plugin.name === DOCS_PLUGIN)
+    .map((plugin) => {
+      const loadedVersions =
+        get<Record<string, unknown>[]>(plugin.content, ['loadedVersions'], []) ?? [];
+      const versions = loadedVersions.map((version) =>
+        toVersion(version, siteDir, siteFormat, options.includeDrafts === true),
+      );
+      return {
+        id: String(plugin.options['id'] ?? 'default'),
+        routeBasePath: String(plugin.options['routeBasePath'] ?? 'docs'),
+        contentDirName: String(plugin.options['path'] ?? 'docs'),
+        admonitionKeywords: admonitionKeywords(plugin.options),
+        breadcrumbs: plugin.options['breadcrumbs'] !== false,
+        versions: selectVersions(versions, options.versions),
+      };
+    })
+    .filter(
+      (instance) =>
+        options.instances === undefined ||
+        options.instances === 'all' ||
+        options.instances.includes(instance.id),
+    );
+
+  return {
+    siteDir,
+    url: String(siteConfig['url'] ?? ''),
+    baseUrl: props.baseUrl,
+    trailingSlash: siteConfig['trailingSlash'] as boolean | undefined,
+    locale: props.i18n.currentLocale,
+    defaultLocale: props.i18n.defaultLocale,
+    locales: props.i18n.locales,
+    markdownFormat: siteFormat,
+    maintainCase: get<boolean>(siteConfig, ['markdown', 'anchors', 'maintainCase'], false),
+    siteTitle: String(siteConfig['title'] ?? ''),
+    staticDirs: staticDirectories.map((dir) => path.resolve(siteDir, dir)),
+    docusaurusVersion: props.siteMetadata.docusaurusVersion,
+    instances,
+  };
+}
+
+/**
+ * Load a Docusaurus site and normalise it.
+ *
+ * One call loads one locale, because that is what Docusaurus's own loader
+ * does; publishing several locales means calling this once for each.
+ */
+export async function loadModel(options: LoadModelOptions): Promise<SiteModel> {
+  const warn = options.warn ?? (() => {});
+  const server = loadDocusaurusServer(options.siteDir, warn);
+
+  // Docusaurus's own CLI always runs from the site directory, and plugins rely
+  // on it: a typedoc entry point of `../client/src/index.ts`, for instance, is
+  // resolved against the working directory rather than the site. Loading from
+  // anywhere else makes those plugins look in the wrong place.
+  const previousCwd = process.cwd();
+  process.chdir(options.siteDir);
+
+  // Docusaurus only drops drafts and applies production behaviour when
+  // NODE_ENV says so, and publishing is a production act. Without this a draft
+  // reaches the site, which is precisely what marking it a draft asked to
+  // avoid.
+  const previousNodeEnv = process.env['NODE_ENV'];
+  process.env['NODE_ENV'] = 'production';
+
+  try {
+    const site = await server.loadSite({
+      siteDir: options.siteDir,
+      locale: options.locale,
+      config: options.configPath,
+    });
+    return toSiteModel(site, options);
+  } finally {
+    process.chdir(previousCwd);
+    if (previousNodeEnv === undefined) delete process.env['NODE_ENV'];
+    else process.env['NODE_ENV'] = previousNodeEnv;
+  }
+}

package/src/reader.ts

@@ -0,0 +1,36 @@
+/**
+ * Reading a model out of a real Docusaurus site.
+ *
+ * The reader interface and the sources that need no Docusaurus live in
+ * `src/model`; this is the one that does.
+ */
+
+import { loadModel, toSiteModel, type LoadModelOptions } from './model';
+import type { LoadedSite } from './server';
+import { createMemoryReader, type SourceReader, type SiteModel } from '@pterodoc/core/model';
+
+/** Read from a real Docusaurus site, one locale at a time. */
+export function createDocusaurusReader(options: LoadModelOptions): SourceReader {
+  let firstLocale: SiteModel | undefined;
+
+  return {
+    kind: 'docusaurus',
+    async locales(): Promise<string[]> {
+      firstLocale ??= await loadModel(options);
+      return firstLocale.locales;
+    },
+    async read(locale?: string): Promise<SiteModel> {
+      if (firstLocale && (locale === undefined || locale === firstLocale.locale)) {
+        return firstLocale;
+      }
+      const model = await loadModel({ ...options, locale });
+      firstLocale ??= model;
+      return model;
+    },
+  };
+}
+
+/** Build a model from a site the caller has already loaded. */
+export function readerFromLoadedSite(site: LoadedSite, options: LoadModelOptions): SourceReader {
+  return createMemoryReader(toSiteModel(site, options));
+}

package/src/server.ts

@@ -0,0 +1,111 @@
+/**
+ * Loading Docusaurus's own site loader.
+ *
+ * `loadSite` runs every plugin's content lifecycle and hands back the resolved
+ * site, which is the whole reason this tool does not re-derive sidebars,
+ * versions or permalinks. It lives at a path Docusaurus does not advertise, so
+ * the import is guarded and fails with something a reader can act on.
+ */
+
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { ConfigError } from '@pterodoc/core/util';
+
+/** Docusaurus versions this tool has been checked against. */
+export const SUPPORTED_RANGE = { min: 3, maxExclusive: 4 };
+
+/** Paths tried, in order, when looking for the site loader. */
+const CANDIDATES = ['lib/server/site.js', 'server.js', 'lib/server/index.js'];
+
+/** What `loadSite` gives back, narrowed to the parts we read. */
+export interface LoadedSite {
+  props: {
+    siteDir: string;
+    siteConfig: Record<string, unknown>;
+    siteConfigPath: string;
+    baseUrl: string;
+    outDir: string;
+    generatedFilesDir: string;
+    i18n: {
+      defaultLocale: string;
+      locales: string[];
+      currentLocale: string;
+      localeConfigs: Record<string, { htmlLang?: string; direction?: string }>;
+    };
+    siteMetadata: { docusaurusVersion: string };
+    plugins: Array<{
+      name: string;
+      options: Record<string, unknown>;
+      content: unknown;
+    }>;
+  };
+}
+
+/** Options `loadSite` accepts. */
+export interface LoadSiteParams {
+  siteDir: string;
+  locale?: string | undefined;
+  config?: string | undefined;
+  outDir?: string | undefined;
+}
+
+/** The shape of the Docusaurus module we depend on. */
+export interface DocusaurusServer {
+  /** Run the content lifecycle and return the resolved site. */
+  loadSite(params: LoadSiteParams): Promise<LoadedSite>;
+  /** The Docusaurus version that was loaded. */
+  version: string;
+}
+
+/**
+ * Find and load Docusaurus's site loader, resolving it from the site rather
+ * than from pterodoc so a hoisted or a nested install both work.
+ *
+ * @param siteDir Absolute path of the Docusaurus site directory.
+ * @param warn Called with a message when the version is outside the tested range.
+ */
+export function loadDocusaurusServer(
+  siteDir: string,
+  warn: (message: string) => void = () => {},
+): DocusaurusServer {
+  const requireFromSite = createRequire(path.join(siteDir, 'noop.js'));
+
+  let corePackagePath: string;
+  try {
+    corePackagePath = requireFromSite.resolve('@docusaurus/core/package.json');
+  } catch {
+    throw new ConfigError(
+      `Could not find @docusaurus/core from ${siteDir}. pterodoc reads a Docusaurus site using Docusaurus itself, so it has to run inside the site's own project. Use --site-dir to point at it, or --model to render from a captured model instead.`,
+    );
+  }
+
+  const corePackage = requireFromSite(corePackagePath) as { version?: string };
+  const version = corePackage.version ?? '0.0.0';
+  const major = Number.parseInt(version.split('.')[0] ?? '0', 10);
+  if (major < SUPPORTED_RANGE.min || major >= SUPPORTED_RANGE.maxExclusive) {
+    warn(
+      `This is Docusaurus ${version}; pterodoc has been checked against ${SUPPORTED_RANGE.min}.x. Continuing, but the site model may not load.`,
+    );
+  }
+
+  const coreDir = path.dirname(corePackagePath);
+  const tried: string[] = [];
+  for (const candidate of CANDIDATES) {
+    const candidatePath = path.join(coreDir, candidate);
+    tried.push(candidatePath);
+    try {
+      const loaded = requireFromSite(candidatePath) as { loadSite?: unknown };
+      if (typeof loaded.loadSite === 'function') {
+        return { loadSite: loaded.loadSite as DocusaurusServer['loadSite'], version };
+      }
+    } catch {
+      // Try the next candidate.
+    }
+  }
+
+  throw new ConfigError(
+    `Docusaurus ${version} is installed but its site loader was not where pterodoc expected it.\n` +
+      `Tried:\n${tried.map((entry) => `  ${entry}`).join('\n')}\n` +
+      'This usually means a Docusaurus release moved it. Capture a model on a working version with `pterodoc capture`, then render from it with `--model`, and please report the version.',
+  );
+}