@pterodoc/core 0.2.0

package/lib/index.js

@@ -0,0 +1,807 @@
+import { C as ConfigError, e as toSlugSegments, V as VERSION, t as titleCase } from './chunks/paths-Bh6UsRI9.js';
+export { E as EXIT, P as PterodocError, T as TargetError, U as USER_AGENT, a as UnsupportedContentError } from './chunks/paths-Bh6UsRI9.js';
+import fs, { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import dotenv from 'dotenv';
+import { DEFAULT_LAYOUT, DEFAULT_STRINGS, createTheme, renderVersionBanner, collectImages, resolveImage, renderDoc, composePage, excerptFor } from './render/index.js';
+import fs$1 from 'node:fs/promises';
+import { I as IssueCollector } from './chunks/issues-DBsPh6ek.js';
+export { c as compareSeverity, f as formatIssue } from './chunks/issues-DBsPh6ek.js';
+import { c as contentHash, m as mimeTypeFor } from './chunks/mime-2SUyOolJ.js';
+import { b as buildPageTree } from './chunks/capture-BhdvHwrN.js';
+export { c as createCaptureReader, a as createMemoryReader, r as readCapture, s as serializeModel, w as writeCapture } from './chunks/capture-BhdvHwrN.js';
+import 'gray-matter';
+import 'unified';
+import 'remark-parse';
+import 'remark-gfm';
+import 'remark-directive';
+import 'remark-frontmatter';
+import 'remark-mdx';
+import 'unist-util-visit';
+import 'mdast-util-to-hast';
+import 'hast-util-to-html';
+import 'github-slugger';
+import 'mdast-util-to-string';
+import 'node:crypto';
+
+/**
+ * The configuration a site writes, and the resolved shape the tool reads.
+ *
+ * Credentials never appear here: the config names the environment variables
+ * that hold them, so a config file is safe to commit.
+ */
+/**
+ * Identity function that types a configuration file.
+ *
+ * @param config The configuration.
+ */
+function defineConfig(config) {
+    return config;
+}
+
+/**
+ * Discovering, merging and validating configuration.
+ *
+ * Precedence is flags, then the environment, then the config file, then the
+ * defaults. Nothing here touches `process.env` or the disk except through the
+ * dependencies it is given, so it is testable without either.
+ */
+/** File names tried, in order, when no config is named. */
+const CONFIG_NAMES = [
+    'pterodoc.config.mjs',
+    'pterodoc.config.js',
+    'pterodoc.config.cjs',
+    'pterodoc.config.ts',
+    'pterodoc.config.json',
+];
+/** Find a configuration file next to the site. */
+function discoverConfigFile(siteDir, deps) {
+    for (const name of CONFIG_NAMES) {
+        const candidate = path.join(siteDir, name);
+        if (deps.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Load a configuration file. */
+async function readConfigFile(file) {
+    if (file.endsWith('.json')) {
+        try {
+            return JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            throw new ConfigError(`${file} is not valid JSON: ${error.message}`);
+        }
+    }
+    try {
+        const module = (await import(pathToFileURL(file).href));
+        const config = module.default ?? module;
+        if (!config || typeof config !== 'object') {
+            throw new Error('the file exports no configuration object');
+        }
+        return config;
+    }
+    catch (error) {
+        const message = error.message;
+        if (file.endsWith('.ts')) {
+            throw new ConfigError(`Could not load ${file}: ${message}\nA TypeScript config needs Node 22 or newer, which reads it directly. On an older Node, use pterodoc.config.mjs.`);
+        }
+        throw new ConfigError(`Could not load ${file}: ${message}`);
+    }
+}
+/** One value, from the flags, the environment, the file, or the default. */
+function pick(...candidates) {
+    for (const candidate of candidates) {
+        if (candidate !== undefined && candidate !== '')
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Names that changed when this tool was extracted.
+ *
+ * The credential and URL variables kept their names, because they are what
+ * every existing setup already sets; only these two were renamed, and using
+ * one still works but says so.
+ */
+const RENAMED = {
+    WP_ROOT_PATH: 'PTERODOC_WP_ROOT',
+    WP_DOCS_BASE: 'PTERODOC_WP_BASE',
+};
+/**
+ * Read an environment value.
+ *
+ * `PTERODOC_`-prefixed names win; the plain names are equally supported except
+ * where one was renamed, which is reported.
+ */
+function fromEnv(env, name, aliases, notices) {
+    const prefixed = env[`PTERODOC_${name}`];
+    if (prefixed)
+        return prefixed;
+    for (const alias of aliases) {
+        const value = env[alias];
+        if (!value)
+            continue;
+        const current = RENAMED[alias];
+        if (current)
+            notices.push(`Using ${alias}; it is now called ${current}.`);
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Resolve everything into the shape the run reads.
+ *
+ * @param input Flags, the file's contents, and the environment.
+ */
+function resolveConfig(input) {
+    const flags = input.flags ?? {};
+    const file = input.file ?? {};
+    const env = input.env ?? {};
+    const notices = [];
+    const site = file.site ?? {};
+    const target = file.target ?? {};
+    const render = file.render ?? {};
+    const media = file.media ?? {};
+    const output = file.output ?? {};
+    const baseDir = input.fileDir ?? process.cwd();
+    const siteDir = path.resolve(baseDir, pick(flags.siteDir, site.dir) ?? '.');
+    const userEnvName = target.auth?.userEnv ?? 'WP_USER';
+    const passwordEnvName = target.auth?.passwordEnv ?? 'WP_APP_PASSWORD';
+    const targetUrl = (pick(fromEnv(env, 'WP_URL', ['WP_URL'], notices), target.url) ?? '').replace(/\/+$/, '');
+    const user = (env[userEnvName] ?? '').trim();
+    const appPassword = (env[passwordEnvName] ?? '').replace(/\s+/g, '');
+    if (targetUrl && !/^https?:\/\//.test(targetUrl)) {
+        throw new ConfigError(`The target URL must start with http:// or https:// (got "${targetUrl}").`);
+    }
+    const missingCredentials = !targetUrl || !user || !appPassword;
+    const offline = flags.offline === true || missingCredentials;
+    if (missingCredentials && flags.offline !== true) {
+        notices.push(`No target URL or credentials (${userEnvName}, ${passwordEnvName}): running offline. Pages are rendered and nothing is sent.`);
+    }
+    const status = (pick(flags.status, fromEnv(env, 'WP_STATUS', ['WP_STATUS'], notices), target.status) ??
+        'publish');
+    if (status !== 'publish' && status !== 'draft' && status !== 'private') {
+        throw new ConfigError(`Status must be publish, draft or private (got "${status}").`);
+    }
+    const rootPath = pick(flags.root, fromEnv(env, 'WP_ROOT', ['WP_ROOT_PATH'], notices), target.root) ?? '/docs';
+    const basePath = flags.base !== undefined
+        ? flags.base
+        : (pick(fromEnv(env, 'WP_BASE', ['WP_DOCS_BASE'], notices), target.base) ?? '');
+    const layout = { ...DEFAULT_LAYOUT, ...file.layout };
+    if (!['', 'wide', 'full'].includes(layout.align)) {
+        throw new ConfigError(`Layout alignment must be "", "wide" or "full" (got "${layout.align}").`);
+    }
+    const locales = flags.allLocales
+        ? 'all'
+        : flags.locale && flags.locale.length > 0
+            ? flags.locale
+            : (site.locales ?? 'default');
+    const versions = flags.allVersions
+        ? 'all'
+        : flags.docsVersion && flags.docsVersion.length > 0
+            ? flags.docsVersion
+            : (site.versions ?? 'last');
+    const outDir = path.resolve(baseDir, pick(flags.out, fromEnv(env, 'OUT', [], notices), output.dir) ?? '.pterodoc');
+    return {
+        siteDir,
+        configFile: input.configFile,
+        docusaurusConfig: pick(flags.docusaurusConfig, site.config),
+        modelFile: flags.model ? path.resolve(baseDir, flags.model) : undefined,
+        instances: flags.instance && flags.instance.length > 0 ? flags.instance : (site.instances ?? 'all'),
+        sidebars: site.sidebars ?? 'all',
+        versions,
+        locales,
+        includeDrafts: site.includeDrafts === true,
+        includeUnlisted: site.includeUnlisted === true,
+        includeOrphans: site.includeOrphans === true,
+        targetType: target.type ?? 'wordpress',
+        targetUrl,
+        user,
+        appPassword,
+        rootSegments: toSlugSegments(rootPath, 'the target root path'),
+        baseSegments: toSlugSegments(basePath, 'the target base'),
+        docsTitle: target.title ?? '',
+        status,
+        template: target.template ?? '',
+        lang: pick(fromEnv(env, 'WP_LANG', ['WP_LANG'], notices), target.lang) ?? '',
+        metaDescriptionKey: target.meta?.description ?? '',
+        methodOverride: fromEnv(env, 'METHOD_OVERRIDE', ['WP_METHOD_OVERRIDE'], notices) === '1' ||
+            target.methodOverride === true,
+        retry: {
+            attempts: target.retry?.attempts ?? 4,
+            baseDelayMs: target.retry?.baseDelayMs ?? 1000,
+            maxDelayMs: target.retry?.maxDelayMs ?? 30_000,
+        },
+        layout,
+        classPrefix: render.classPrefix ?? 'pterodoc',
+        blocks: render.blocks === 'plugin' ? 'plugin' : 'core',
+        dedupeTitle: render.dedupeTitle !== false,
+        unpublishedLinks: render.unpublishedLinks ?? 'site',
+        siteUrl: render.siteUrl ?? '',
+        excerptLength: render.excerptLength ?? 160,
+        strings: { ...DEFAULT_STRINGS, ...render.strings },
+        localeStrings: render.localeStrings ?? {},
+        mdxOnUnknown: file.mdx?.onUnknown ?? 'report',
+        uploadMedia: flags.noMedia === true ? false : media.upload !== false,
+        uploadRemoteMedia: media.uploadRemote === true,
+        mediaOnMissing: media.onMissing ?? 'warning',
+        mediaSlugPrefix: media.slugPrefix ?? 'pterodoc',
+        outDir,
+        writePages: output.pages !== false,
+        only: (flags.only ?? '').replace(/^\/+|\/+$/g, ''),
+        dryRun: flags.dryRun === true || offline,
+        prune: flags.prune === true,
+        offline,
+        strict: flags.strict === true,
+        strictAt: file.strict ?? 'error',
+        notices,
+    };
+}
+/**
+ * Discover, read and resolve the configuration.
+ *
+ * @param flags Parsed command line flags.
+ * @param env The environment to read.
+ * @param deps Injected filesystem access.
+ */
+async function loadConfig(flags = {}, env = process.env, deps = {}) {
+    const existsSync = deps.existsSync ?? ((file) => fs.existsSync(file));
+    const cwd = deps.cwd ?? (() => process.cwd());
+    const startDir = path.resolve(cwd(), flags.siteDir ?? '.');
+    const configFile = flags.config
+        ? path.resolve(cwd(), flags.config)
+        : discoverConfigFile(startDir, { existsSync });
+    if (flags.config && !existsSync(configFile)) {
+        throw new ConfigError(`No configuration file at ${configFile}.`);
+    }
+    const file = configFile ? await readConfigFile(configFile) : {};
+    const fileDir = configFile ? path.dirname(configFile) : startDir;
+    // A named env file is read only when asked for, so a developer's own .env
+    // can never leak into a test or a scripted run.
+    const envFile = flags.envFile ?? env['PTERODOC_ENV_FILE'];
+    const merged = envFile
+        ? { ...dotenv.parse(fs.readFileSync(path.resolve(cwd(), envFile))), ...env }
+        : env;
+    return resolveConfig({ flags, file, fileDir, env: merged, configFile });
+}
+
+/** What a run intends to do, and what it did. */
+/** Count the actions by operation. */
+function summarise(actions) {
+    const summary = {};
+    for (const action of actions)
+        summary[action.op] = (summary[action.op] ?? 0) + 1;
+    return summary;
+}
+
+/**
+ * What a run leaves behind.
+ *
+ * The rendered pages and the plan are how a change is reviewed before it is
+ * published, and how a run that failed part way through is diagnosed.
+ */
+/** Where one page's rendered body is written. */
+function pageFile(outDir, locale, versionName, treePath) {
+    const parts = [outDir, 'pages', locale, versionName];
+    const name = treePath === '' ? 'index.html' : `${treePath}.html`;
+    return path.join(...parts, name);
+}
+/**
+ * Write the rendered pages, the manifest, the media map and the plan.
+ *
+ * Never called from a `finally`: a failure to write the artefacts must not
+ * replace the error that actually stopped the run.
+ */
+async function writeArtifacts(outDir, artifacts, options) {
+    await fs$1.mkdir(outDir, { recursive: true });
+    if (options.writePages) {
+        await fs$1.rm(path.join(outDir, 'pages'), { recursive: true, force: true });
+        for (const { page, locale, versionName } of artifacts.pages) {
+            const file = pageFile(outDir, locale, versionName, page.path);
+            await fs$1.mkdir(path.dirname(file), { recursive: true });
+            await fs$1.writeFile(file, page.content, 'utf8');
+        }
+    }
+    const write = async (name, value) => {
+        await fs$1.writeFile(path.join(outDir, name), `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    };
+    await write('manifest.json', artifacts.manifest);
+    await write('media.json', artifacts.media);
+    await write('plan.json', artifacts.plan);
+}
+
+/**
+ * The reconciler.
+ *
+ * Two phases, because WordPress's navigation block needs a page id before any
+ * body can reference it: first make sure every page exists, then render every
+ * body against the real ids and write only what differs.
+ */
+/** Run the sync. */
+async function runSync(config, deps) {
+    const log = deps.log ?? (() => { });
+    const issues = new IssueCollector();
+    const actions = [];
+    const prepared = [];
+    const mediaRecords = [];
+    let requests = 0;
+    let mediaPending = 0;
+    let docusaurusVersion = null;
+    const locales = await selectLocales(config, deps.reader);
+    for (const locale of locales) {
+        const model = await deps.reader.read(locale);
+        docusaurusVersion ??= model.docusaurusVersion;
+        const theme = createTheme({
+            classPrefix: config.classPrefix,
+            blocks: config.blocks,
+            strings: { ...config.strings, ...config.localeStrings[model.locale] },
+        });
+        const session = deps.target && !deps.renderOnly && !config.offline
+            ? await deps.target.open({ locale: model.locale, dryRun: config.dryRun })
+            : undefined;
+        for (const instance of model.instances) {
+            for (const version of instance.versions) {
+                const result = await syncVersion({
+                    config,
+                    model,
+                    instance: { admonitionKeywords: instance.admonitionKeywords },
+                    version,
+                    theme,
+                    target: deps.target,
+                    session,
+                    issues,
+                    log,
+                });
+                actions.push(...result.actions);
+                prepared.push(...result.prepared);
+                mediaRecords.push(...result.media);
+                mediaPending += result.mediaPending;
+            }
+        }
+        if (session)
+            requests += session.requestCount();
+    }
+    const rootPath = deps.target?.rootPath ?? '/';
+    const plan = {
+        generatedAt: new Date().toISOString(),
+        versions: { pterodoc: VERSION, docusaurus: docusaurusVersion, node: process.version },
+        dryRun: config.dryRun,
+        offline: config.offline,
+        site: config.targetUrl || null,
+        rootPath,
+        locales,
+        versionNames: [...new Set(prepared.map((entry) => entry.versionName))],
+        actions,
+        issues: issues.issues,
+        summary: summarise(actions),
+        requests,
+        mediaPending,
+        artifactError: null,
+    };
+    const artifacts = {
+        pages: prepared.map(({ page, locale, versionName }) => ({ page, locale, versionName })),
+        manifest: prepared.map(({ node, page, locale, versionName }) => ({
+            path: page.path,
+            title: page.title,
+            slug: page.slug,
+            parent: node.parent ? node.parent.path : null,
+            menuOrder: page.menuOrder,
+            locale,
+            versionName,
+            file: page.file ?? null,
+            href: deps.target ? deps.target.hrefFor(page.path, { versionName, locale }) : page.path,
+        })),
+        media: mediaRecords,
+        plan,
+    };
+    try {
+        await writeArtifacts(config.outDir, artifacts, { writePages: config.writePages });
+    }
+    catch (error) {
+        plan.artifactError = error instanceof Error ? error.message : String(error);
+    }
+    return { plan, artifacts };
+}
+/** Which locales to publish. */
+async function selectLocales(config, reader) {
+    if (Array.isArray(config.locales))
+        return config.locales;
+    if (config.locales === 'all')
+        return reader.locales();
+    const model = await reader.read();
+    return [model.defaultLocale ?? model.locale];
+}
+/** Publish one version of one docs instance. */
+async function syncVersion(input) {
+    const { config, model, version, theme, target, session, issues, log } = input;
+    const actions = [];
+    const locale = model.locale;
+    const tree = buildPageTree({
+        version,
+        sidebars: config.sidebars,
+        rootTitle: config.docsTitle,
+        includeUnlisted: config.includeUnlisted,
+        includeOrphans: config.includeOrphans,
+        issues,
+    });
+    const context = { versionName: version.name, locale };
+    const href = (treePath) => target ? target.hrefFor(treePath, context) : `/${treePath}`;
+    // Phase 0 and 1: make sure the pages exist, so their ids are known.
+    const ids = new Map();
+    const created = new Set();
+    let rootParentId = null;
+    if (session) {
+        await session.loadIndex();
+        const root = await session.ensureRootParent();
+        rootParentId = root.id;
+        for (const entry of root.created) {
+            actions.push({ op: 'create-root', path: entry.path, id: entry.id, locale });
+        }
+    }
+    const inScope = (treePath) => !config.only || treePath === config.only || treePath.startsWith(`${config.only}/`);
+    const isNeeded = (treePath) => inScope(treePath) || treePath === '' || config.only.startsWith(`${treePath}/`);
+    const nodes = [tree.root, ...tree.chain];
+    for (const node of nodes) {
+        if (!isNeeded(node.path))
+            continue;
+        const parentId = node.parent ? (ids.get(node.parent.path) ?? null) : rootParentId;
+        if (!session) {
+            ids.set(node.path, null);
+            continue;
+        }
+        const result = await session.ensurePage({
+            path: node.path,
+            slug: node.slug,
+            parentId,
+            title: node.title,
+            menuOrder: node.menuOrder,
+            isRoot: node.path === '',
+        });
+        for (const warning of result.warnings) {
+            issues.add({ code: 'target-warning', severity: 'warning', message: warning, path: node.path });
+        }
+        ids.set(node.path, result.id);
+        if (result.created) {
+            created.add(node.path);
+            actions.push({
+                op: 'create',
+                path: node.path,
+                id: result.id,
+                locale,
+                versionName: version.name,
+                file: node.doc?.sourceRelativePath ?? null,
+            });
+            if (result.id !== null)
+                log(`created ${node.path || '(root)'} (id ${result.id})`);
+        }
+    }
+    // Media: resolve every referenced file, upload what is new, and remember
+    // where each one ended up so the renderer can point at it.
+    const media = new Map();
+    const mediaRecords = [];
+    let mediaPending = 0;
+    if (config.uploadMedia) {
+        const result = await syncMedia({ config, model, version, tree, session, issues });
+        for (const [url, ref] of result.byUrl)
+            media.set(url, ref);
+        mediaRecords.push(...result.records);
+        mediaPending = result.pending;
+        actions.push(...result.actions);
+    }
+    // Phase 2: render against the real ids, and write what differs.
+    const navRootId = ids.get('') ?? null;
+    const prepared = [];
+    const banner = version.banner && !version.isLast
+        ? renderVersionBanner(theme, version.label, version.banner)
+        : undefined;
+    for (const node of nodes) {
+        const page = renderPageFor({
+            node,
+            tree,
+            config,
+            model,
+            theme,
+            href,
+            navRootId,
+            admonitionKeywords: input.instance.admonitionKeywords,
+            media,
+            issues,
+            ...(banner ? { banner } : {}),
+        });
+        prepared.push({ node, page, locale, versionName: version.name });
+        const id = ids.get(node.path);
+        if (!session || id === null || id === undefined)
+            continue;
+        if (!inScope(node.path) && !created.has(node.path))
+            continue;
+        const parentId = node.parent ? (ids.get(node.parent.path) ?? 0) : (rootParentId ?? 0);
+        const remote = await session.fetchPage(id);
+        const changed = session.diffPage(remote, page, parentId ?? 0);
+        if (changed.length === 0) {
+            actions.push({
+                op: 'unchanged',
+                path: node.path,
+                id,
+                locale,
+                versionName: version.name,
+                file: page.file ?? null,
+            });
+            continue;
+        }
+        actions.push({
+            op: 'update',
+            path: node.path,
+            id,
+            changed,
+            locale,
+            versionName: version.name,
+            file: page.file ?? null,
+        });
+        if (config.dryRun)
+            continue;
+        const { warnings } = await session.writePage(id, page, parentId ?? 0);
+        for (const warning of warnings) {
+            issues.add({ code: 'target-warning', severity: 'warning', message: warning, path: node.path });
+        }
+        log(`updated ${node.path || '(root)'} (${changed.join(', ')})`);
+    }
+    // Anything under this version's root that no document accounts for.
+    if (session && navRootId !== null) {
+        if (config.only) {
+            issues.add({
+                code: 'prune-skipped',
+                severity: 'info',
+                message: 'Pruning was skipped because --only limited the run.',
+            });
+        }
+        else {
+            const index = await session.loadIndex();
+            const keep = new Set();
+            for (const id of ids.values())
+                if (typeof id === 'number')
+                    keep.add(id);
+            for (const page of session.computePrune(index, navRootId, keep)) {
+                actions.push({
+                    op: 'prune',
+                    path: page.slug,
+                    id: page.id,
+                    locale,
+                    versionName: version.name,
+                    applied: config.prune && !config.dryRun,
+                });
+                if (config.prune && !config.dryRun) {
+                    await session.removePage(page);
+                    log(`trashed ${page.link}`);
+                }
+            }
+        }
+    }
+    return { actions, prepared, media: mediaRecords, mediaPending };
+}
+/** Render one page, body and all. */
+function renderPageFor(input) {
+    const { node, tree, config, model, theme, issues } = input;
+    const doc = node.doc;
+    let body = '';
+    let links = new Set();
+    let firstParagraph = '';
+    if (doc) {
+        const markdown = readDocument(doc, issues);
+        if (markdown !== undefined) {
+            const rendered = renderDoc({
+                markdown,
+                file: doc.sourceRelativePath,
+                permalink: doc.permalink,
+                format: doc.format,
+                theme,
+                admonitionKeywords: input.admonitionKeywords,
+                maintainCase: model.maintainCase,
+                dedupeTitle: config.dedupeTitle,
+                onUnknownJsx: config.mdxOnUnknown,
+                media: input.media,
+                issues,
+                resolveLink: makeLinkResolver(doc, tree, config, model, input.href),
+            });
+            body = rendered.body;
+            links = rendered.links;
+            firstParagraph = rendered.firstParagraph;
+        }
+    }
+    const content = composePage({
+        node,
+        body,
+        links,
+        href: input.href,
+        lookup: (treePath) => tree.byPath.get(treePath),
+        theme,
+        layout: config.layout,
+        navRootId: input.navRootId,
+        ...(input.banner ? { banner: input.banner } : {}),
+    });
+    const excerpt = excerptFor(doc?.description ?? '', firstParagraph, config.excerptLength);
+    const meta = {};
+    if (config.metaDescriptionKey && excerpt)
+        meta[config.metaDescriptionKey] = excerpt;
+    return {
+        path: node.path,
+        slug: node.slug,
+        title: node.title,
+        content,
+        excerpt,
+        menuOrder: node.menuOrder,
+        meta,
+        file: doc?.sourceRelativePath,
+        versionName: node.versionName,
+    };
+}
+/** Read a document's source, reporting rather than throwing when it is gone. */
+function readDocument(doc, issues) {
+    try {
+        return readFileSync(doc.sourceAbsolutePath, 'utf8');
+    }
+    catch (error) {
+        issues.addFor(doc, {
+            code: 'source-unreadable',
+            severity: 'error',
+            message: `Could not read ${doc.sourceRelativePath}: ${error.message}`,
+        });
+        return undefined;
+    }
+}
+/** Decide where each link in a document should point. */
+function makeLinkResolver(doc, tree, config, model, href) {
+    const siteUrl = (config.siteUrl || model.url).replace(/\/+$/, '');
+    const baseUrl = model.baseUrl.replace(/\/+$/, '');
+    /**
+     * A root-relative markdown link is relative to the site, not to the server.
+     * Docusaurus's router prepends the base URL, so a link written as
+     * `/docs/api/` on a site served from `/project/` really means
+     * `/project/docs/api/`.
+     */
+    const withBaseUrl = (urlPath) => !baseUrl || urlPath === baseUrl || urlPath.startsWith(`${baseUrl}/`)
+        ? urlPath
+        : `${baseUrl}${urlPath}`;
+    return (rawHref) => {
+        if (!rawHref || rawHref.startsWith('#'))
+            return { href: rawHref };
+        if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(rawHref) || rawHref.startsWith('//')) {
+            return { href: rawHref };
+        }
+        const hashIndex = rawHref.indexOf('#');
+        const hash = hashIndex === -1 ? '' : rawHref.slice(hashIndex);
+        const target = hashIndex === -1 ? rawHref : rawHref.slice(0, hashIndex);
+        const node = target.startsWith('/')
+            ? findByUrl(tree, withBaseUrl(target))
+            : findBySourcePath(tree, doc, target);
+        if (node)
+            return { href: `${href(node.path)}${hash}`, path: node.path };
+        if (config.unpublishedLinks === 'drop')
+            return { href: null };
+        // Nothing here publishes it, so point at the documentation site, using the
+        // URL Docusaurus itself would serve.
+        const urlPath = target.startsWith('/')
+            ? withBaseUrl(path.posix.normalize(target))
+            : path.posix.normalize(path.posix.join(doc.permalink, '..', target.replace(/\.mdx?$/, '')));
+        return { href: `${siteUrl}${urlPath}${hash}` };
+    };
+}
+/** A page whose document is served at this URL. */
+function findByUrl(tree, target) {
+    const urlPath = path.posix.normalize(target).replace(/\.mdx?$/, '');
+    return tree.byPermalink.get(urlPath) ?? tree.byPermalink.get(`${urlPath}/`);
+}
+/**
+ * A page whose source file a relative link points at.
+ *
+ * Relative links are resolved against the file, which is how Docusaurus
+ * resolves them. Resolving against the URL instead would break every document
+ * whose front matter gives it a slug of its own.
+ */
+function findBySourcePath(tree, from, target) {
+    const base = path.posix.dirname(from.sourceRelativePath);
+    const resolved = path.posix.normalize(path.posix.join(base, target));
+    const withoutExtension = resolved.replace(/\.mdx?$/, '');
+    const candidates = [
+        resolved,
+        `${withoutExtension}.md`,
+        `${withoutExtension}.mdx`,
+        `${withoutExtension}/index.md`,
+        `${withoutExtension}/index.mdx`,
+        `${withoutExtension}/README.md`,
+    ];
+    for (const candidate of candidates) {
+        const node = tree.bySourcePath.get(candidate);
+        if (node)
+            return node;
+    }
+    return undefined;
+}
+/** Resolve, upload and record every file the documents reference. */
+async function syncMedia(input) {
+    const { config, model, version, tree, session, issues } = input;
+    const byUrl = new Map();
+    const records = [];
+    const actions = [];
+    let pending = 0;
+    const remote = session ? await session.loadMediaIndex() : new Map();
+    const uploadedThisRun = new Map();
+    for (const node of [tree.root, ...tree.chain]) {
+        const doc = node.doc;
+        if (!doc)
+            continue;
+        let markdown;
+        try {
+            markdown = await fs$1.readFile(doc.sourceAbsolutePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const image of collectImages(markdown, doc.format)) {
+            if (byUrl.has(image.url))
+                continue;
+            const resolved = resolveImage(image.url, {
+                sourceAbsolutePath: doc.sourceAbsolutePath,
+                contentPath: version.contentPath,
+                contentPathLocalized: version.contentPathLocalized,
+                staticDirs: model.staticDirs,
+                baseUrl: model.baseUrl,
+                siteDir: model.siteDir,
+            });
+            if (resolved.kind === 'external')
+                continue;
+            if (resolved.kind === 'missing') {
+                if (config.mediaOnMissing !== 'ignore') {
+                    issues.addFor(doc, {
+                        code: 'asset-missing',
+                        severity: config.mediaOnMissing,
+                        message: `The file "${image.url}" was not found, so the reference was left as written.`,
+                    });
+                }
+                continue;
+            }
+            const bytes = await fs$1.readFile(resolved.file);
+            const hash = contentHash(bytes);
+            const known = uploadedThisRun.get(hash) ?? remote.get(hash);
+            if (known) {
+                byUrl.set(image.url, { id: known.id, url: known.url });
+                records.push({ hash, file: resolved.file, url: known.url, uploaded: false });
+                actions.push({ op: 'reuse-media', path: node.path, id: known.id, file: resolved.file });
+                continue;
+            }
+            if (!session || config.dryRun) {
+                pending += 1;
+                records.push({ hash, file: resolved.file, url: null, uploaded: false });
+                actions.push({ op: 'upload-media', path: node.path, id: null, file: resolved.file });
+                continue;
+            }
+            const filename = path.basename(resolved.file);
+            const mime = mimeTypeFor(filename);
+            if (!mime) {
+                issues.addFor(doc, {
+                    code: 'asset-unknown-type',
+                    severity: 'warning',
+                    message: `Not uploading "${image.url}": its file type is not one WordPress accepts.`,
+                });
+                continue;
+            }
+            const uploaded = await session.uploadMedia({
+                bytes,
+                filename,
+                hash,
+                mime,
+                alt: image.alt,
+                title: image.title ?? titleCase(path.parse(filename).name),
+            });
+            uploadedThisRun.set(hash, uploaded);
+            byUrl.set(image.url, { id: uploaded.id, url: uploaded.url });
+            records.push({ hash, file: resolved.file, url: uploaded.url, uploaded: true });
+            actions.push({ op: 'upload-media', path: node.path, id: uploaded.id, file: resolved.file });
+        }
+    }
+    return { byUrl, records, actions, pending };
+}
+
+export { CONFIG_NAMES, ConfigError, DEFAULT_LAYOUT, IssueCollector, VERSION, buildPageTree, composePage, createTheme, defineConfig, discoverConfigFile, loadConfig, renderDoc, resolveConfig, runSync };
+//# sourceMappingURL=index.js.map