@pterodoc/core 0.2.0

package/src/render/renderers.ts

@@ -0,0 +1,346 @@
+/**
+ * Markdown block nodes to Gutenberg blocks.
+ *
+ * One function per node type, dispatched from `renderBlock`. Everything that
+ * cannot be represented is reported as an issue; nothing is dropped quietly.
+ */
+
+import type {
+  Blockquote,
+  Code,
+  Heading,
+  Image,
+  List,
+  ListItem,
+  Paragraph,
+  PhrasingContent,
+  Root,
+  RootContent,
+  Table,
+} from 'mdast';
+import type { ContainerDirective } from 'mdast-util-directive';
+import { toHast } from 'mdast-util-to-hast';
+import { escapeText, joinBlocks, serializeBlock } from './blocks';
+import { escapeShortcodesInHast, hastToHtml, renderInline } from './inline';
+import { headingIdFor, type Slugger } from './slug';
+import { renderCode } from './code';
+import { renderAdmonition, DEFAULT_ADMONITION_KEYWORDS } from './admonitions';
+import { renderJsxBlock, type JsxElement } from './components';
+import type { Theme } from './theme';
+import type { IssueCollector } from '../util/issues';
+
+/** Everything a block renderer needs that is not the node itself. */
+export interface RenderContext {
+  /** Class names and strings. */
+  theme: Theme;
+  /** The document's heading slugger. */
+  slugger: Slugger;
+  /** Whether Docusaurus keeps heading case when generating anchors. */
+  maintainCase: boolean;
+  /** Directive names that mean "admonition" on this site. */
+  admonitionKeywords: Set<string>;
+  /** Where problems are recorded. */
+  issues: IssueCollector;
+  /** Source file, for issue positions. */
+  file?: string | undefined;
+  /** The markdown the tree was parsed from, for reproducing unhandled nodes. */
+  source: string;
+  /** Media already uploaded, keyed by the URL as written in the source. */
+  media?: Map<string, { id: number; url: string }> | undefined;
+  /** What to do about JSX with no translation. */
+  onUnknownJsx?: 'report' | 'placeholder' | 'error';
+}
+
+/** A context with the defaults a caller usually wants. */
+export function createRenderContext(
+  init: Partial<RenderContext> & Pick<RenderContext, 'theme' | 'slugger' | 'issues'>,
+): RenderContext {
+  return {
+    maintainCase: false,
+    admonitionKeywords: new Set(DEFAULT_ADMONITION_KEYWORDS),
+    source: '',
+    ...init,
+  };
+}
+
+/** True when a list only holds shapes core's list block can carry. */
+function listIsSimple(list: List): boolean {
+  return list.children.every(
+    (item) =>
+      item.type === 'listItem' &&
+      item.children.every(
+        (child, index) => (child.type === 'paragraph' && index === 0) || child.type === 'list',
+      ),
+  );
+}
+
+function renderListItem(item: ListItem, ctx: RenderContext): string {
+  const parts: string[] = [];
+  for (const child of item.children) {
+    if (child.type === 'paragraph') parts.push(renderInline(child.children));
+    else if (child.type === 'list') parts.push(renderList(child, ctx));
+  }
+  const marker = item.checked === true ? '☑ ' : item.checked === false ? '☐ ' : '';
+  return serializeBlock('list-item', undefined, `<li>${marker}${parts.join('')}</li>`);
+}
+
+function renderList(node: List, ctx: RenderContext): string {
+  const tag = node.ordered ? 'ol' : 'ul';
+  const attributes: Record<string, unknown> = {};
+  if (node.ordered) attributes['ordered'] = true;
+  const start = node.ordered && typeof node.start === 'number' && node.start !== 1 ? node.start : null;
+  if (start !== null) attributes['start'] = start;
+
+  const items = node.children.map((item) => renderListItem(item as ListItem, ctx)).join('\n\n');
+  const open = `<${tag}${start !== null ? ` start="${start}"` : ''} class="wp-block-list">`;
+  return serializeBlock('list', attributes, `${open}${items}</${tag}>`);
+}
+
+function renderTable(node: Table): string {
+  const align = node.align ?? [];
+  const cell = (content: { children?: PhrasingContent[] }, index: number, header: boolean): string => {
+    const tag = header ? 'th' : 'td';
+    const alignment = align[index];
+    const attrs = alignment ? ` class="has-text-align-${alignment}" data-align="${alignment}"` : '';
+    return `<${tag}${attrs}>${renderInline(content.children ?? [])}</${tag}>`;
+  };
+
+  const [head, ...body] = node.children;
+  const thead = head
+    ? `<thead><tr>${head.children.map((c, i) => cell(c, i, true)).join('')}</tr></thead>`
+    : '';
+  const tbody = body.length
+    ? `<tbody>${body
+        .map((row) => `<tr>${row.children.map((c, i) => cell(c, i, false)).join('')}</tr>`)
+        .join('')}</tbody>`
+    : '';
+
+  return serializeBlock(
+    'table',
+    { hasFixedLayout: false },
+    `<figure class="wp-block-table"><table>${thead}${tbody}</table></figure>`,
+  );
+}
+
+/** A paragraph holding nothing but one image becomes an image block. */
+function loneImage(node: Paragraph): Image | undefined {
+  const meaningful = node.children.filter(
+    (child) => !(child.type === 'text' && child.value.trim() === ''),
+  );
+  return meaningful.length === 1 && meaningful[0]!.type === 'image'
+    ? (meaningful[0] as Image)
+    : undefined;
+}
+
+function renderImageBlock(node: Image, ctx: RenderContext): string {
+  const uploaded = ctx.media?.get(node.url);
+  const src = uploaded?.url ?? node.url;
+  const attributes: Record<string, unknown> = { sizeSlug: 'large', linkDestination: 'none' };
+  if (uploaded) attributes['id'] = uploaded.id;
+
+  const classes = `wp-block-image size-large`;
+  const imgClass = uploaded ? ` class="wp-image-${uploaded.id}"` : '';
+  const caption = node.title
+    ? `<figcaption class="wp-element-caption">${escapeText(node.title)}</figcaption>`
+    : '';
+
+  return serializeBlock(
+    'image',
+    attributes,
+    `<figure class="${classes}"><img src="${escapeText(src)}" alt="${escapeText(node.alt ?? '')}"${imgClass}/>${caption}</figure>`,
+  );
+}
+
+/**
+ * Render one top-level markdown node.
+ *
+ * @param node The node.
+ * @param ctx Theme, slugger and issue collector.
+ */
+export function renderBlock(node: RootContent, ctx: RenderContext): string {
+  switch (node.type) {
+    case 'paragraph': {
+      const image = loneImage(node as Paragraph);
+      if (image) return renderImageBlock(image, ctx);
+      const html = renderInline((node as Paragraph).children);
+      if (html.trim() === '') return '';
+      return serializeBlock('paragraph', undefined, `<p>${html}</p>`);
+    }
+
+    case 'heading': {
+      const heading = node as Heading;
+      const { id, children } = headingIdFor(heading, ctx.slugger, ctx.maintainCase);
+      const level = heading.depth;
+      const attributes = level === 2 ? undefined : { level };
+      return serializeBlock(
+        'heading',
+        attributes,
+        `<h${level} class="wp-block-heading" id="${id}">${renderInline(children)}</h${level}>`,
+      );
+    }
+
+    case 'list': {
+      const list = node as List;
+      if (listIsSimple(list)) return renderList(list, ctx);
+      ctx.issues.add({
+        code: 'list-not-representable',
+        severity: 'info',
+        message: 'A list item holds blocks the WordPress list block cannot carry; kept as HTML.',
+        file: ctx.file,
+        line: node.position?.start.line,
+      });
+      const hast = toHast(list, { allowDangerousHtml: true });
+      const escaped = hast ? escapeShortcodesInHast([hast as never]) : [];
+      return serializeBlock('html', undefined, hastToHtml(escaped));
+    }
+
+    case 'code':
+      return renderCode(node as Code, ctx.theme, ctx.issues, ctx.file);
+
+    case 'blockquote': {
+      const inner = joinBlocks(
+        (node as Blockquote).children.map((child) => renderBlock(child, ctx)),
+      );
+      return serializeBlock('quote', undefined, `<blockquote class="wp-block-quote">${inner}</blockquote>`);
+    }
+
+    case 'table':
+      return renderTable(node as Table);
+
+    case 'thematicBreak':
+      return serializeBlock(
+        'separator',
+        undefined,
+        '<hr class="wp-block-separator has-alpha-channel-opacity"/>',
+      );
+
+    case 'containerDirective': {
+      const directive = node as ContainerDirective;
+      const name = String(directive.name ?? '').toLowerCase();
+      if (ctx.admonitionKeywords.has(name)) {
+        return renderAdmonition(directive, ctx.theme, (child) => renderBlock(child, ctx));
+      }
+      ctx.issues.add({
+        code: 'directive-unknown',
+        severity: 'warning',
+        message: `":::${directive.name}" is not an admonition on this site; its content was kept without the wrapper.`,
+        file: ctx.file,
+        line: node.position?.start.line,
+      });
+      return joinBlocks((directive.children as RootContent[]).map((child) => renderBlock(child, ctx)));
+    }
+
+    case 'mdxJsxFlowElement': {
+      const element = node as unknown as JsxElement;
+      const rendered = renderJsxBlock(element, {
+        theme: ctx.theme,
+        issues: ctx.issues,
+        source: ctx.source,
+        file: ctx.file,
+        renderChild: (child) => renderBlock(child, ctx),
+      });
+      if (rendered !== undefined) return rendered;
+      ctx.issues.add({
+        code: 'mdx-unknown-component',
+        severity: ctx.onUnknownJsx === 'error' ? 'error' : 'warning',
+        message: `<${element.name ?? 'fragment'}> is a React component, which a page cannot run, so it was left out.`,
+        file: ctx.file,
+        line: node.position?.start.line,
+        column: node.position?.start.column,
+      });
+      return ctx.onUnknownJsx === 'placeholder'
+        ? serializeBlock('html', undefined, `<!-- pterodoc: <${element.name ?? 'fragment'}> omitted -->`)
+        : '';
+    }
+
+    case 'html': {
+      const value = (node as { value: string }).value;
+      // Comments carry no content; Docusaurus hides them too.
+      if (/^\s*<!--[\s\S]*-->\s*$/.test(value)) return '';
+      return serializeBlock('html', undefined, value);
+    }
+
+    case 'image':
+      return renderImageBlock(node as Image, ctx);
+
+    case 'definition':
+    case 'yaml':
+    case 'footnoteDefinition':
+      return '';
+
+    default: {
+      const position = node.position;
+      if (position && ctx.source) {
+        const raw = ctx.source.slice(position.start.offset ?? 0, position.end.offset ?? 0);
+        ctx.issues.add({
+          code: 'node-unhandled',
+          severity: 'warning',
+          message: `A "${node.type}" node has no WordPress equivalent; its source was kept verbatim.`,
+          file: ctx.file,
+          line: position.start.line,
+        });
+        return serializeBlock('paragraph', undefined, `<p>${escapeText(raw)}</p>`);
+      }
+      ctx.issues.add({
+        code: 'node-unhandled',
+        severity: 'warning',
+        message: `A "${node.type}" node has no WordPress equivalent and was skipped.`,
+        file: ctx.file,
+      });
+      return '';
+    }
+  }
+}
+
+/**
+ * Render a document body.
+ *
+ * @param root The parsed document.
+ * @param ctx Theme, slugger and issue collector.
+ * @param options `dedupeTitle` drops a leading H1 that repeats the page title.
+ */
+export function renderBody(
+  root: Root,
+  ctx: RenderContext,
+  options: { dedupeTitle?: boolean } = {},
+): { body: string; firstParagraph: string } {
+  const children = [...root.children];
+
+  if (options.dedupeTitle !== false) {
+    // The theme prints the page title, so a body that opens with the same
+    // heading would show it twice. Skipping anything that renders to nothing
+    // first means a comment or a stripped import cannot hide the heading.
+    const firstVisible = children.findIndex(
+      (child) =>
+        !(child.type === 'html' && /^\s*<!--[\s\S]*-->\s*$/.test(child.value)) &&
+        child.type !== 'yaml' &&
+        child.type !== 'definition',
+    );
+    const candidate = firstVisible === -1 ? undefined : children[firstVisible];
+    if (candidate && candidate.type === 'heading' && candidate.depth === 1) {
+      children.splice(firstVisible, 1);
+    }
+  }
+
+  const firstParagraph = children.find((child) => child.type === 'paragraph');
+  const body = joinBlocks(children.map((child) => renderBlock(child, ctx)));
+  return {
+    body,
+    firstParagraph: firstParagraph ? plainText(firstParagraph as Paragraph) : '',
+  };
+}
+
+/** Plain text of a node, for excerpts. */
+function plainText(node: Paragraph): string {
+  const parts: string[] = [];
+  const walk = (child: { type: string; value?: string; children?: unknown[] }): void => {
+    if (typeof child.value === 'string' && (child.type === 'text' || child.type === 'inlineCode')) {
+      parts.push(child.value);
+    }
+    if (Array.isArray(child.children)) {
+      for (const grandChild of child.children) walk(grandChild as never);
+    }
+  };
+  walk(node as never);
+  return parts.join('');
+}

package/src/render/slug.ts

@@ -0,0 +1,63 @@
+/**
+ * Heading identifiers.
+ *
+ * The anchors have to match the ones Docusaurus generated, or every in-page
+ * link that survived the move would break. That is why `github-slugger` is
+ * pinned to the major Docusaurus itself depends on.
+ */
+
+import GithubSlugger from 'github-slugger';
+import { toString as mdastToString } from 'mdast-util-to-string';
+import type { Heading, PhrasingContent, Text } from 'mdast';
+
+/** A slugger scoped to one document, so repeated headings get `-1`, `-2` suffixes. */
+export type Slugger = InstanceType<typeof GithubSlugger>;
+
+/** Start a fresh slugger for a document. */
+export function createSlugger(): Slugger {
+  return new GithubSlugger();
+}
+
+/** A heading's identifier and the content that remains once the id syntax is removed. */
+export interface HeadingId {
+  /** The anchor for this heading. */
+  id: string;
+  /** The heading's children with any explicit `{#id}` stripped. */
+  children: PhrasingContent[];
+  /** Plain text of the heading, for a table of contents or a title. */
+  text: string;
+}
+
+/**
+ * Work out a heading's identifier.
+ *
+ * Docusaurus lets an explicit `{#id}` override the generated slug. Both paths
+ * feed the same slugger so that a later duplicate is still disambiguated.
+ *
+ * @param heading The heading node.
+ * @param slugger The document's slugger.
+ * @param maintainCase Whether Docusaurus is configured to keep heading case.
+ */
+export function headingIdFor(heading: Heading, slugger: Slugger, maintainCase = false): HeadingId {
+  const children = heading.children.map((child) => ({ ...child })) as PhrasingContent[];
+  const last = children[children.length - 1];
+  let explicit = '';
+
+  if (last && last.type === 'text') {
+    const text = last as Text;
+    const match = /\s*\{#([^}]+)\}\s*$/.exec(text.value);
+    if (match) {
+      explicit = match[1]!.trim();
+      text.value = text.value.slice(0, match.index).replace(/\s+$/, '');
+      if (text.value === '') children.pop();
+    }
+  }
+
+  const text = mdastToString({ type: 'root', children } as never);
+  if (explicit) {
+    // Register it so a later generated slug cannot collide with it.
+    slugger.slug(explicit, true);
+    return { id: explicit, children, text };
+  }
+  return { id: slugger.slug(text, maintainCase), children, text };
+}

package/src/render/theme.ts

@@ -0,0 +1,92 @@
+/**
+ * Every class name and every human-readable string the renderer emits.
+ *
+ * Kept in one place so a site can restyle the output without patching the
+ * renderer, and so a non-English site can translate it.
+ */
+
+/** Human-readable strings, with `{placeholders}` substituted at use. */
+export interface Strings {
+  /** Heading above a generated list of child pages. */
+  indexHeading: string;
+  /** Separator between breadcrumb entries. */
+  breadcrumbSeparator: string;
+  /** Link to the previous page; `{title}` is the page's title. */
+  previous: string;
+  /** Link to the next page; `{title}` is the page's title. */
+  next: string;
+  /** Fallback title for the documentation root. */
+  documentation: string;
+  /** Summary for a section page; `{count}` is the number of children. */
+  pageCount: string;
+  /** Singular form of `pageCount`. */
+  pageCountOne: string;
+  /** Banner on a version that is not the current one; `{label}` is the version label. */
+  versionBanner: string;
+  /** Placeholder left where content could not be represented; `{what}` names it. */
+  unsupportedNotice: string;
+}
+
+/** The strings used when a site configures none. */
+export const DEFAULT_STRINGS: Strings = {
+  indexHeading: 'In this section',
+  breadcrumbSeparator: ' › ',
+  previous: '← {title}',
+  next: '{title} →',
+  documentation: 'Documentation',
+  pageCount: '{count} pages',
+  pageCountOne: '1 page',
+  versionBanner: 'This is documentation for {label}.',
+  unsupportedNotice: 'Content omitted: {what}',
+};
+
+/**
+ * Which block vocabulary to emit.
+ *
+ * `core` is core blocks and nothing else, which is what a site with no plugin
+ * installed can display. `plugin` additionally carries instructions the
+ * WordPress plugin understands, in block-comment attributes only — never in the
+ * saved markup, so the two are the same content to WordPress either way.
+ */
+export type BlockVocabulary = 'core' | 'plugin';
+
+/** Class names and strings, resolved for one run. */
+export interface Theme {
+  /** Prefix on every generated class name. */
+  readonly classPrefix: string;
+  /** Whether the WordPress plugin is expected to be there. */
+  readonly blocks: BlockVocabulary;
+  /** The resolved strings. */
+  readonly strings: Strings;
+  /** A prefixed class name: `cls('docs-nav')` with prefix `x` gives `x-docs-nav`. */
+  cls(name: string): string;
+  /** A string with `{placeholders}` filled in. */
+  text(key: keyof Strings, values?: Record<string, string | number>): string;
+}
+
+/**
+ * Build a theme.
+ *
+ * @param options Class prefix and any string overrides.
+ */
+export function createTheme(options: {
+  classPrefix?: string;
+  strings?: Partial<Strings>;
+  blocks?: BlockVocabulary;
+} = {}): Theme {
+  const classPrefix = options.classPrefix ?? 'pterodoc';
+  const strings: Strings = { ...DEFAULT_STRINGS, ...options.strings };
+  return {
+    classPrefix,
+    blocks: options.blocks ?? 'core',
+    strings,
+    cls(name: string): string {
+      return `${classPrefix}-${name}`;
+    },
+    text(key, values = {}): string {
+      return strings[key].replace(/\{(\w+)\}/g, (match, name: string) =>
+        name in values ? String(values[name]) : match,
+      );
+    },
+  };
+}

package/src/sync/artifacts.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { RenderedPage } from '../target/target';
+import type { Plan } from './plan';
+
+/** A page, with where it came from and where it is going. */
+export interface ManifestEntry {
+  path: string;
+  title: string;
+  slug: string;
+  parent: string | null;
+  menuOrder: number;
+  locale: string;
+  versionName: string;
+  file: string | null;
+  href: string;
+}
+
+/** Everything written to the output directory. */
+export interface Artifacts {
+  pages: { page: RenderedPage; locale: string; versionName: string }[];
+  manifest: ManifestEntry[];
+  media: { hash: string; file: string; url: string | null; uploaded: boolean }[];
+  plan: Plan;
+}
+
+/** Where one page's rendered body is written. */
+function pageFile(outDir: string, locale: string, versionName: string, treePath: string): string {
+  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.
+ */
+export async function writeArtifacts(
+  outDir: string,
+  artifacts: Artifacts,
+  options: { writePages: boolean },
+): Promise<void> {
+  await fs.mkdir(outDir, { recursive: true });
+
+  if (options.writePages) {
+    await fs.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.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, page.content, 'utf8');
+    }
+  }
+
+  const write = async (name: string, value: unknown): Promise<void> => {
+    await fs.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);
+}

package/src/sync/plan.ts

@@ -0,0 +1,69 @@
+/** What a run intends to do, and what it did. */
+
+import type { Issue } from '../util/issues';
+
+/** One thing a run did, or would do. */
+export interface Action {
+  /** What kind of change this is. */
+  op:
+    | 'create-root'
+    | 'create'
+    | 'update'
+    | 'unchanged'
+    | 'prune'
+    | 'upload-media'
+    | 'reuse-media';
+  /** Full path within the published tree, for every operation. */
+  path: string;
+  /** Target id, once it is known. */
+  id?: number | null;
+  /** Fields that differ, for an update. */
+  changed?: string[];
+  /** Source file, when the action belongs to a document. */
+  file?: string | null;
+  /** Locale this action belongs to. */
+  locale?: string;
+  /** Version this action belongs to. */
+  versionName?: string;
+  /** Whether a removal was actually carried out. */
+  applied?: boolean;
+}
+
+/** The record of a run. */
+export interface Plan {
+  /** When the run started. */
+  generatedAt: string;
+  /** Versions involved, for reproducing a report. */
+  versions: { pterodoc: string; docusaurus: string | null; node: string };
+  /** True when nothing was written. */
+  dryRun: boolean;
+  /** True when nothing was even read from the target. */
+  offline: boolean;
+  /** The target site, when there is one. */
+  site: string | null;
+  /** Where the documentation was published. */
+  rootPath: string;
+  /** Locales published. */
+  locales: string[];
+  /** Versions published. */
+  versionNames: string[];
+  /** Everything the run did, or would do. */
+  actions: Action[];
+  /** Everything worth telling the user. */
+  issues: Issue[];
+  /** How many of each operation. */
+  summary: Record<string, number>;
+  /** How many requests were made. */
+  requests: number;
+  /** How many files still need uploading; non-zero only on a dry run. */
+  mediaPending: number;
+  /** Set when writing the artefacts itself failed. */
+  artifactError: string | null;
+}
+
+/** Count the actions by operation. */
+export function summarise(actions: Action[]): Record<string, number> {
+  const summary: Record<string, number> = {};
+  for (const action of actions) summary[action.op] = (summary[action.op] ?? 0) + 1;
+  return summary;
+}