@pterodoc/core 0.2.0

package/src/model/types.ts

@@ -0,0 +1,167 @@
+/**
+ * The site model: what the rest of pterodoc knows about a Docusaurus site.
+ *
+ * Every field here is derived from Docusaurus's own loaded state rather than
+ * re-read from disk, so ordering, permalinks, versions and locales are the
+ * ones the site itself would render.
+ */
+
+import type { MarkdownFormat } from '../render';
+
+/** A sidebar entry that points at a document. */
+export interface SidebarDocItem {
+  type: 'doc' | 'ref';
+  id: string;
+  label?: string | undefined;
+}
+
+/** A sidebar entry that points at a URL. */
+export interface SidebarLinkItem {
+  type: 'link';
+  href: string;
+  label: string;
+}
+
+/** A sidebar entry that is raw markup. */
+export interface SidebarHtmlItem {
+  type: 'html';
+  value: string;
+}
+
+/** What a category's own page is, when it has one. */
+export type SidebarCategoryLink =
+  | { type: 'doc'; id: string }
+  | { type: 'generated-index'; slug: string; permalink: string; title?: string; description?: string };
+
+/** A sidebar entry that groups other entries. */
+export interface SidebarCategoryItem {
+  type: 'category';
+  label: string;
+  items: SidebarItem[];
+  link?: SidebarCategoryLink | undefined;
+}
+
+/** Any resolved sidebar entry. Autogenerated entries are already expanded. */
+export type SidebarItem = SidebarDocItem | SidebarLinkItem | SidebarHtmlItem | SidebarCategoryItem;
+
+/** Where a neighbouring page sits. */
+export interface DocNeighbour {
+  title: string;
+  permalink: string;
+}
+
+/** One document. */
+export interface Doc {
+  /** Docusaurus's document id, unique within a version. */
+  id: string;
+  /** Name of the version this document belongs to. */
+  versionName: string;
+  /** Title, from front matter or the first heading. */
+  title: string;
+  /** Front matter description; may be empty. */
+  description: string;
+  /** Source path as Docusaurus records it, e.g. `@site/docs/intro.md`. */
+  sourceAliased: string;
+  /** Absolute path of the source file. */
+  sourceAbsolutePath: string;
+  /** Source path relative to the site directory, for messages. */
+  sourceRelativePath: string;
+  /** Directory of the source below the version's content path; `.` at the root. */
+  sourceDirName: string;
+  /** URL below the version, without the base URL. */
+  slug: string;
+  /** Full URL path, including base URL and version path. */
+  permalink: string;
+  /** Position in the published tree, relative to the version root; '' is the root. */
+  treePath: string;
+  /** Docusaurus excludes drafts from production builds. */
+  draft: boolean;
+  /** Unlisted documents are reachable but hidden from navigation. */
+  unlisted: boolean;
+  /** The document's front matter, as parsed by Docusaurus. */
+  frontMatter: Record<string, unknown>;
+  /** Sidebar this document belongs to, when it belongs to one. */
+  sidebarName?: string | undefined;
+  /** Position within an autogenerated slice. */
+  sidebarPosition?: number | undefined;
+  /** The previous page in sidebar order. */
+  previous?: DocNeighbour | undefined;
+  /** The next page in sidebar order. */
+  next?: DocNeighbour | undefined;
+  /** Tags, kept for a future taxonomy mapping. */
+  tags: { label: string; permalink: string }[];
+  /** Which flavour the body is written in. */
+  format: MarkdownFormat;
+}
+
+/** One version of one docs instance. */
+export interface DocsVersion {
+  /** Version name, e.g. `current` or `1.0.0`. */
+  name: string;
+  /** Human label, e.g. `Next` or `1.0.0`. */
+  label: string;
+  /** True for the version served at the docs root. */
+  isLast: boolean;
+  /** URL path prefix for this version, including the base URL. */
+  pathPrefix: string;
+  /** Absolute path of this version's content directory. */
+  contentPath: string;
+  /** Absolute path of the localised content directory, preferred for assets. */
+  contentPathLocalized: string;
+  /** Docusaurus's own judgement that this version is unmaintained or unreleased. */
+  banner: 'unmaintained' | 'unreleased' | null;
+  /** Whether Docusaurus asks search engines to ignore this version. */
+  noIndex: boolean;
+  /** Resolved sidebars, keyed by sidebar id. */
+  sidebars: Record<string, SidebarItem[]>;
+  /** Published documents, drafts already removed. */
+  docs: Doc[];
+  /** How many documents were dropped for being drafts. */
+  draftCount: number;
+}
+
+/** One instance of the docs plugin. */
+export interface DocsInstance {
+  /** Plugin instance id; `default` when the site names none. */
+  id: string;
+  /** Route base path this instance serves under. */
+  routeBasePath: string;
+  /** Content directory name, relative to the site. */
+  contentDirName: string;
+  /** Directive names this site treats as admonitions. */
+  admonitionKeywords: string[];
+  /** Whether the site renders breadcrumbs. */
+  breadcrumbs: boolean;
+  /** Versions, in the order Docusaurus loaded them. */
+  versions: DocsVersion[];
+}
+
+/** Everything pterodoc knows about a site, for one locale. */
+export interface SiteModel {
+  /** Absolute path of the Docusaurus site directory. */
+  siteDir: string;
+  /** Site URL, without a path. */
+  url: string;
+  /** Base URL path, with leading and trailing slashes. */
+  baseUrl: string;
+  /** The site's trailing-slash policy; undefined means Docusaurus decides per URL. */
+  trailingSlash: boolean | undefined;
+  /** Locale this model was loaded for. */
+  locale: string;
+  /** The site's default locale. */
+  defaultLocale: string;
+  /** Every locale the site declares. */
+  locales: string[];
+  /** Markdown flavour the site defaults to. */
+  markdownFormat: 'md' | 'mdx' | 'detect';
+  /** Whether heading anchors keep their case. */
+  maintainCase: boolean;
+  /** The site's title, used when the docs root has no document of its own. */
+  siteTitle: string;
+  /** Absolute paths of the static directories, for resolving assets. */
+  staticDirs: string[];
+  /** Version of Docusaurus that produced this model. */
+  docusaurusVersion: string;
+  /** Docs plugin instances. */
+  instances: DocsInstance[];
+}

package/src/render/admonitions.ts

@@ -0,0 +1,74 @@
+/**
+ * Docusaurus admonitions.
+ *
+ * `:::note` and its siblings are container directives. WordPress has no
+ * equivalent block, so each becomes a group with stable classes a theme can
+ * style, opened by a bold label the way Docusaurus renders one.
+ */
+
+import type { ContainerDirective } from 'mdast-util-directive';
+import type { RootContent } from 'mdast';
+import { toString as mdastToString } from 'mdast-util-to-string';
+import { joinBlocks, serializeBlock } from './blocks';
+import { renderInline } from './inline';
+import type { Theme } from './theme';
+
+/**
+ * The keywords Docusaurus recognises when a site configures none.
+ *
+ * Taken from the docs plugin's own defaults rather than guessed: a site that
+ * writes `:::success` gets an admonition on Docusaurus and must get one here.
+ */
+export const DEFAULT_ADMONITION_KEYWORDS = [
+  'secondary',
+  'info',
+  'success',
+  'danger',
+  'note',
+  'tip',
+  'warning',
+  'important',
+  'caution',
+] as const;
+
+/**
+ * Render an admonition.
+ *
+ * @param node The container directive.
+ * @param theme Class names and strings.
+ * @param renderChild How to render each block inside the admonition.
+ */
+export function renderAdmonition(
+  node: ContainerDirective,
+  theme: Theme,
+  renderChild: (child: RootContent) => string,
+): string {
+  const type = String(node.name ?? '').toLowerCase();
+  const children = [...(node.children as RootContent[])];
+
+  let label = type.charAt(0).toUpperCase() + type.slice(1);
+  const first = children[0] as { data?: { directiveLabel?: boolean } } | undefined;
+  if (first?.data?.directiveLabel) {
+    label = mdastToString(children[0] as never);
+    children.shift();
+  }
+
+  const base = theme.cls('admonition');
+  const className = `${base} ${base}-${type}`;
+  const titleClass = theme.cls('admonition-title');
+
+  const inner = joinBlocks([
+    serializeBlock(
+      'paragraph',
+      { className: titleClass },
+      `<p class="${titleClass}"><strong>${renderInline([{ type: 'text', value: label }])}</strong></p>`,
+    ),
+    ...children.map(renderChild),
+  ]);
+
+  return serializeBlock(
+    'group',
+    { className },
+    `<div class="wp-block-group ${className}">${inner}</div>`,
+  );
+}

package/src/render/blocks.ts

@@ -0,0 +1,79 @@
+/**
+ * Gutenberg block serialisation.
+ *
+ * WordPress stores post content as HTML annotated with block comments, and the
+ * editor re-parses that markup and compares it with what the block's own save
+ * function would produce. Everything here therefore follows core's output
+ * closely: the attribute encoding, the class names and the whitespace.
+ */
+
+/** Attributes a block carries in its opening comment. */
+export type BlockAttributes = Record<string, unknown>;
+
+/**
+ * Encode block attributes the way WordPress encodes them, so the editor sees
+ * markup it would have written itself.
+ */
+export function serializeAttrs(attributes: BlockAttributes): string {
+  return JSON.stringify(attributes)
+    .replace(/--/g, '\\u002d\\u002d')
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\\"/g, '\\u0022');
+}
+
+/**
+ * Wrap inner markup in a block comment pair.
+ *
+ * @param name Block name without the `core/` prefix.
+ * @param attributes Omitted from the output when empty.
+ * @param inner The block's stored markup.
+ */
+export function serializeBlock(
+  name: string,
+  attributes: BlockAttributes | undefined,
+  inner: string,
+): string {
+  const attrs =
+    attributes && Object.keys(attributes).length > 0 ? ` ${serializeAttrs(attributes)}` : '';
+  return `<!-- wp:${name}${attrs} -->\n${inner}\n<!-- /wp:${name} -->`;
+}
+
+/**
+ * A dynamic block: it renders on the server and stores no inner markup.
+ */
+export function serializeVoidBlock(name: string, attributes?: BlockAttributes): string {
+  const attrs =
+    attributes && Object.keys(attributes).length > 0 ? ` ${serializeAttrs(attributes)}` : '';
+  return `<!-- wp:${name}${attrs} /-->`;
+}
+
+/** Join sibling blocks the way WordPress does. */
+export function joinBlocks(blocks: Array<string | undefined | null>): string {
+  return blocks.filter((block): block is string => typeof block === 'string' && block !== '').join('\n\n');
+}
+
+/**
+ * Escape text destined for a `<code>` element.
+ *
+ * `[` becomes an entity because WordPress expands shortcodes inside code as
+ * happily as anywhere else, and documentation is full of bracketed samples.
+ */
+export function escapeCode(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\[/g, '&#91;');
+}
+
+/** Escape text for use in an HTML text node or attribute value. */
+export function escapeText(text: string): string {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\[/g, '&#91;');
+}

package/src/render/code.ts

@@ -0,0 +1,112 @@
+/**
+ * Code blocks.
+ *
+ * Docusaurus carries extra instructions in the fence's metastring — a title,
+ * highlighted line ranges, line numbers. WordPress core's code block has
+ * nowhere to put them, so the title becomes a visible caption, line numbers
+ * become a class a theme can act on, and anything left over is reported rather
+ * than dropped in silence.
+ */
+
+import type { Code } from 'mdast';
+import { escapeCode, joinBlocks, serializeBlock } from './blocks';
+import type { Theme } from './theme';
+import type { IssueCollector } from '../util/issues';
+
+/** What a fence's metastring asked for. */
+export interface CodeMeta {
+  /** Title shown above the block. */
+  title?: string;
+  /** True when the fence asked for line numbers. */
+  showLineNumbers: boolean;
+  /** Highlighted line ranges, exactly as written. */
+  highlight?: string;
+}
+
+/**
+ * Read a fence's metastring.
+ *
+ * @param meta The text after the language on the opening fence.
+ */
+export function parseCodeMeta(meta: string | null | undefined): CodeMeta {
+  const source = meta ?? '';
+  const title = /(?:^|\s)title=(?:"([^"]*)"|'([^']*)'|([^\s]+))/.exec(source);
+  const highlight = /\{([\d,\s-]+)\}/.exec(source);
+  return {
+    ...(title ? { title: title[1] ?? title[2] ?? title[3] ?? '' } : {}),
+    showLineNumbers: /(?:^|\s)showLineNumbers(?:\s|=|$)/.test(source),
+    ...(highlight ? { highlight: highlight[1]!.trim() } : {}),
+  };
+}
+
+/**
+ * Render a fenced code block.
+ *
+ * @param node The code node.
+ * @param theme Class names and strings.
+ * @param issues Where unrepresentable instructions are reported.
+ * @param file Source file, for the issue's position.
+ */
+export function renderCode(
+  node: Code,
+  theme: Theme,
+  issues?: IssueCollector,
+  file?: string,
+): string {
+  const lang = (node.lang ?? '').toLowerCase();
+  const meta = parseCodeMeta(node.meta);
+
+  if (lang === 'mermaid') {
+    // Entities are decoded again when mermaid reads the element's text, so
+    // escaping keeps `A[Start]` away from the shortcode parser without
+    // changing the diagram.
+    return serializeBlock('html', undefined, `<pre class="mermaid">${escapeCode(node.value)}</pre>`);
+  }
+
+  const classes: string[] = [];
+  if (lang) classes.push(`language-${lang}`);
+  if (meta.showLineNumbers) classes.push(theme.cls('line-numbers'));
+
+  const className = classes.join(' ');
+  const preClasses = className ? `wp-block-code ${className}` : 'wp-block-code';
+
+  // Highlighted lines have no core equivalent, so with core blocks alone they
+  // can only be reported. The plugin can render them, and reads the range from
+  // the block comment — never from the markup, which stays exactly what core's
+  // own save function would have written.
+  const carried = theme.blocks === 'plugin' && meta.highlight !== undefined;
+
+  const attributes: Record<string, unknown> = {};
+  if (className) attributes['className'] = className;
+  if (carried) attributes['pterodocHighlight'] = meta.highlight;
+
+  const code = serializeBlock(
+    'code',
+    Object.keys(attributes).length > 0 ? attributes : undefined,
+    `<pre class="${preClasses}"><code>${escapeCode(node.value)}</code></pre>`,
+  );
+
+  if (meta.highlight && !carried) {
+    issues?.add({
+      code: 'code-highlight-dropped',
+      severity: 'info',
+      message: `Highlighted lines {${meta.highlight}} have no WordPress equivalent and were not carried over. Install the pterodoc WordPress plugin and set render.blocks to 'plugin' to keep them.`,
+      file,
+      line: node.position?.start.line,
+    });
+  }
+
+  if (!meta.title) return code;
+
+  const caption = serializeBlock(
+    'paragraph',
+    { className: theme.cls('code-title') },
+    `<p class="${theme.cls('code-title')}">${escapeCode(meta.title)}</p>`,
+  );
+  const groupClass = theme.cls('code-group');
+  return serializeBlock(
+    'group',
+    { className: groupClass },
+    `<div class="wp-block-group ${groupClass}">${joinBlocks([caption, code])}</div>`,
+  );
+}

package/src/render/components.ts

@@ -0,0 +1,230 @@
+/**
+ * The MDX component table.
+ *
+ * Docusaurus ships a small set of components that documentation actually uses.
+ * Each one here has a WordPress block that carries the same meaning; anything
+ * else is reported by the lowering pass rather than guessed at.
+ */
+
+import type { RootContent } from 'mdast';
+import { escapeText, joinBlocks, serializeBlock } from './blocks';
+import { escapeCode } from './blocks';
+import type { Theme } from './theme';
+import type { IssueCollector } from '../util/issues';
+import { HTML_ELEMENTS } from './mdx';
+
+/** A JSX element as mdast holds it. */
+export interface JsxElement {
+  type: string;
+  name?: string | null;
+  attributes?: {
+    type: string;
+    name?: string;
+    value?: unknown;
+  }[];
+  children?: RootContent[];
+  position?: { start: { line: number; column: number; offset?: number }; end: { offset?: number } };
+}
+
+/** Read a string attribute, ignoring expression values we cannot evaluate. */
+export function attribute(element: JsxElement, name: string): string | undefined {
+  for (const attr of element.attributes ?? []) {
+    if (attr.type !== 'mdxJsxAttribute' || attr.name !== name) continue;
+    if (typeof attr.value === 'string') return attr.value;
+    const value = attr.value as { type?: string; value?: string } | null;
+    if (value && typeof value.value === 'string') return value.value;
+    return undefined;
+  }
+  return undefined;
+}
+
+/** What a component renderer is given. */
+export interface ComponentContext {
+  theme: Theme;
+  issues: IssueCollector;
+  source: string;
+  file?: string | undefined;
+  /** Render an ordinary markdown node. */
+  renderChild: (node: RootContent) => string;
+}
+
+/** A details block, which is what a collapsible section becomes. */
+function detailsBlock(summary: string, inner: string): string {
+  return serializeBlock(
+    'details',
+    undefined,
+    `<details class="wp-block-details"><summary>${escapeText(summary)}</summary>${inner}</details>`,
+  );
+}
+
+/** Render `<TabItem>` as one collapsible section. */
+function renderTabItem(element: JsxElement, ctx: ComponentContext): string {
+  const label = attribute(element, 'label') ?? attribute(element, 'value') ?? 'Tab';
+  const inner = joinBlocks((element.children ?? []).map(ctx.renderChild));
+  return detailsBlock(label, inner);
+}
+
+/**
+ * Render `<Tabs>`.
+ *
+ * Tabs need JavaScript that a published page does not have, so each tab
+ * becomes a collapsible section instead. All of the content survives, and it
+ * stays readable without any script at all.
+ */
+function renderTabs(element: JsxElement, ctx: ComponentContext): string {
+  const items = (element.children ?? []).filter(
+    (child) => (child as JsxElement).name === 'TabItem',
+  ) as JsxElement[];
+
+  const rendered = items.map((item) => renderTabItem(item, ctx));
+  const className = ctx.theme.cls('tabs');
+  return serializeBlock(
+    'group',
+    { className },
+    `<div class="wp-block-group ${className}">${joinBlocks(rendered)}</div>`,
+  );
+}
+
+/** Render `<Details>` or a raw `<details>` element. */
+function renderDetails(element: JsxElement, ctx: ComponentContext): string {
+  const children = [...(element.children ?? [])];
+  let summary = attribute(element, 'summary') ?? '';
+
+  const summaryIndex = children.findIndex((child) => (child as JsxElement).name === 'summary');
+  if (summaryIndex !== -1) {
+    const node = children[summaryIndex] as JsxElement;
+    summary = plainText(node, ctx.source);
+    children.splice(summaryIndex, 1);
+  }
+
+  return detailsBlock(summary || 'Details', joinBlocks(children.map(ctx.renderChild)));
+}
+
+/** Render `<CodeBlock language="ts" title="x">`. */
+function renderCodeBlock(element: JsxElement, ctx: ComponentContext): string {
+  const language = attribute(element, 'language') ?? '';
+  const title = attribute(element, 'title');
+  // The children parse as ordinary markdown, so the code arrives as text
+  // inside paragraphs rather than as one raw string.
+  const value = textContent(element.children ?? []);
+
+  const classes = language ? `wp-block-code language-${language}` : 'wp-block-code';
+  const code = serializeBlock(
+    'code',
+    language ? { className: `language-${language}` } : undefined,
+    `<pre class="${classes}"><code>${escapeCode(value)}</code></pre>`,
+  );
+  if (!title) return code;
+
+  const groupClass = ctx.theme.cls('code-group');
+  const titleClass = ctx.theme.cls('code-title');
+  return serializeBlock(
+    'group',
+    { className: groupClass },
+    `<div class="wp-block-group ${groupClass}">${joinBlocks([
+      serializeBlock('paragraph', { className: titleClass }, `<p class="${titleClass}">${escapeText(title)}</p>`),
+      code,
+    ])}</div>`,
+  );
+}
+
+/** Render `<Admonition type="tip" title="…">`. */
+function renderAdmonitionElement(element: JsxElement, ctx: ComponentContext): string {
+  const type = (attribute(element, 'type') ?? 'note').toLowerCase();
+  const label = attribute(element, 'title') ?? type.charAt(0).toUpperCase() + type.slice(1);
+  const base = ctx.theme.cls('admonition');
+  const className = `${base} ${base}-${type}`;
+  const titleClass = ctx.theme.cls('admonition-title');
+
+  const inner = joinBlocks([
+    serializeBlock(
+      'paragraph',
+      { className: titleClass },
+      `<p class="${titleClass}"><strong>${escapeText(label)}</strong></p>`,
+    ),
+    ...(element.children ?? []).map(ctx.renderChild),
+  ]);
+  return serializeBlock(
+    'group',
+    { className },
+    `<div class="wp-block-group ${className}">${inner}</div>`,
+  );
+}
+
+/**
+ * The text a run of nodes carries.
+ *
+ * Block-level children are separated by a blank line, which is what keeps the
+ * lines of a code block apart once MDX has parsed them into paragraphs.
+ */
+function textContent(nodes: RootContent[]): string {
+  const blocks: string[] = [];
+  for (const node of nodes) {
+    const parts: string[] = [];
+    const walk = (child: { type?: string; value?: string; children?: unknown[] }): void => {
+      if (typeof child.value === 'string' && child.type !== 'html') parts.push(child.value);
+      for (const grandChild of (child.children ?? []) as never[]) walk(grandChild);
+    };
+    walk(node as never);
+    const text = parts.join('');
+    if (text !== '') blocks.push(text);
+  }
+  return blocks.join('\n\n');
+}
+
+/** The text inside an element, for a summary. */
+function plainText(element: JsxElement, source: string): string {
+  const parts: string[] = [];
+  const walk = (node: { type?: string; value?: string; children?: unknown[] }): void => {
+    if (typeof node.value === 'string' && node.type === 'text') parts.push(node.value);
+    for (const child of (node.children ?? []) as never[]) walk(child);
+  };
+  walk(element as never);
+  const text = parts.join('').trim();
+  if (text) return text;
+  const start = element.position?.start.offset;
+  const end = element.position?.end.offset;
+  return start !== undefined && end !== undefined
+    ? source.slice(start, end).replace(/<[^>]*>/g, '').trim()
+    : '';
+}
+
+/**
+ * Render a block-level JSX element.
+ *
+ * @returns The block markup, or undefined when nothing here can render it.
+ */
+export function renderJsxBlock(element: JsxElement, ctx: ComponentContext): string | undefined {
+  const name = element.name ?? '';
+
+  switch (name) {
+    case 'Tabs':
+      return renderTabs(element, ctx);
+    case 'TabItem':
+      return renderTabItem(element, ctx);
+    case 'Details':
+    case 'details':
+      return renderDetails(element, ctx);
+    case 'CodeBlock':
+      return renderCodeBlock(element, ctx);
+    case 'Admonition':
+      return renderAdmonitionElement(element, ctx);
+    default:
+      break;
+  }
+
+  if (name === '') {
+    // A fragment contributes nothing of its own.
+    return joinBlocks((element.children ?? []).map(ctx.renderChild));
+  }
+
+  if (HTML_ELEMENTS.has(name)) {
+    const start = element.position?.start.offset;
+    const end = element.position?.end.offset;
+    if (start !== undefined && end !== undefined) {
+      return serializeBlock('html', undefined, ctx.source.slice(start, end));
+    }
+  }
+
+  return undefined;
+}

package/src/render/excerpt.ts

@@ -0,0 +1,16 @@
+/** Summaries used for excerpts, SEO descriptions and index listings. */
+
+/**
+ * Shorten text to at most `max` characters, breaking on a word.
+ *
+ * @param text The full text.
+ * @param max Longest result, before the ellipsis.
+ */
+export function excerptFrom(text: string, max = 160): string {
+  const clean = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (clean.length <= max) return clean;
+  const cut = clean.slice(0, max);
+  const lastSpace = cut.lastIndexOf(' ');
+  const kept = lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut;
+  return `${kept.replace(/[\s,;:.]+$/, '')}…`;
+}