@mintlify/scraping 4.0.1161 → 4.0.1163

package/src/sdk/converters/go.ts

@@ -0,0 +1,925 @@
+import fse from 'fs-extra';
+import type { Heading, ImageReference, LinkReference, Paragraph, Root as MdastRoot } from 'mdast';
+import path from 'node:path';
+import { visit } from 'unist-util-visit';
+import { z } from 'zod';
+
+import {
+  isHtmlParagraph,
+  isProseParagraph,
+  parseMarkdown,
+  plainText,
+  rewriteMdastLinks,
+  stringifyMdast,
+} from '../convert.js';
+import {
+  encodeHref,
+  indent,
+  inlineCode,
+  linkedCode,
+  responseField,
+  safeHref,
+  truncate,
+  type LinkedToken,
+} from '../mdx.js';
+import type { SdkNavGroup, SdkPage, SdkPageTarget, SdkReference } from '../types.js';
+
+const SUPPORTED_SCHEMA_VERSION = 1;
+const PACKAGE_PAGE = 'package-overview';
+const MEMBER_HEADING_DEPTH = 3;
+const MIN_COMMENT_HEADING_DEPTH = 4;
+const MAX_TYPE_ATTR = 80;
+const MIN_README_HEADING_DEPTH = 2;
+const GITHUB_MODULE = /^github\.com\/([^/]+)\/([^/]+)((?:\/[^/]+)*?)(?:\/v(?:[2-9]|[1-9]\d+))?$/;
+
+const MAX_TEXT = 1 << 20;
+const MAX_CODE = 1 << 18;
+const identifierSchema = z
+  .string()
+  .max(512)
+  .regex(/^[\p{L}_][\p{L}\p{N}_]*$/u, 'expected a Go identifier');
+const importPathSchema = z
+  .string()
+  .max(512)
+  .regex(/^[\p{L}\p{N}._~-]+(?:\/[\p{L}\p{N}._~-]+)*$/u, 'expected a Go import path');
+const DIR_SEGMENT = /^[\p{L}\p{N}._~-]+$/u;
+const dirSchema = z
+  .string()
+  .max(512)
+  .refine(
+    (dir) =>
+      dir === '.' ||
+      dir.split('/').every((segment) => DIR_SEGMENT.test(segment) && !/^\.+$/.test(segment)),
+    'expected "." or a relative directory of import-path segments, none made only of dots'
+  );
+const textSchema = z.string().max(MAX_TEXT);
+const codeTextSchema = z.string().max(MAX_CODE);
+const refSchema = z.object({
+  pkg: importPathSchema.optional(),
+  name: identifierSchema,
+  private: z.boolean().optional(),
+});
+const codeSchema = z.array(z.object({ t: codeTextSchema, ref: refSchema.optional() }));
+const exampleSchema = z.object({
+  suffix: identifierSchema.optional(),
+  doc: textSchema.optional(),
+  code: codeTextSchema,
+  output: codeTextSchema.optional(),
+});
+const typeParamSchema = z.object({ name: identifierSchema, constraint: codeSchema });
+const paramSchema = z.object({ name: identifierSchema.optional(), type: codeSchema });
+const funcSchema = z.object({
+  name: identifierSchema,
+  recv: codeTextSchema.optional(),
+  decl: codeSchema,
+  doc: textSchema.optional(),
+  deprecated: textSchema.optional(),
+  typeParams: z.array(typeParamSchema).optional(),
+  params: z.array(paramSchema).optional(),
+  results: z.array(paramSchema).optional(),
+  examples: z.array(exampleSchema).optional(),
+});
+const valueSchema = z.object({
+  names: z.array(identifierSchema),
+  decl: codeSchema,
+  doc: textSchema.optional(),
+  deprecated: textSchema.optional(),
+});
+const fieldSchema = z.object({
+  name: identifierSchema,
+  type: codeSchema,
+  doc: textSchema.optional(),
+  deprecated: textSchema.optional(),
+  embedded: z.boolean().optional(),
+  tag: codeTextSchema.optional(),
+});
+const typeSchema = z.object({
+  name: identifierSchema,
+  kind: z.enum(['struct', 'interface', 'defined', 'alias']),
+  decl: codeSchema,
+  doc: textSchema.optional(),
+  deprecated: textSchema.optional(),
+  typeParams: z.array(typeParamSchema).optional(),
+  fields: z.array(fieldSchema).optional(),
+  methods: z.array(funcSchema).optional(),
+  funcs: z.array(funcSchema).optional(),
+  consts: z.array(valueSchema).optional(),
+  vars: z.array(valueSchema).optional(),
+  examples: z.array(exampleSchema).optional(),
+});
+const packageSchema = z.object({
+  importPath: importPathSchema,
+  name: identifierSchema,
+  dir: dirSchema,
+  synopsis: textSchema.optional(),
+  doc: textSchema.optional(),
+  readme: textSchema.optional(),
+  deprecated: textSchema.optional(),
+  consts: z.array(valueSchema).optional(),
+  vars: z.array(valueSchema).optional(),
+  funcs: z.array(funcSchema).optional(),
+  types: z.array(typeSchema).optional(),
+  examples: z.array(exampleSchema).optional(),
+});
+const goArtifactSchema = z.object({
+  schemaVersion: z.literal(SUPPORTED_SCHEMA_VERSION),
+  generator: z.object({
+    name: z.string().max(512),
+    version: z.string().max(512),
+    go: z.string().max(512),
+  }),
+  module: importPathSchema,
+  goos: z.string(),
+  goarch: z.string(),
+  commentSyntax: z.enum(['markdown', 'godoc']),
+  packages: z.array(packageSchema).superRefine((packages, ctx) => {
+    const importPaths = new Set<string>();
+    const dirs = new Set<string>();
+    const namespaces = new Map<string, string>();
+    const root = packages.find((pkg) => pkg.dir === '.');
+    packages.forEach((pkg, index) => {
+      if (importPaths.has(pkg.importPath)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, 'importPath'],
+          message: `duplicate package ${pkg.importPath}`,
+        });
+      }
+      importPaths.add(pkg.importPath);
+      if (dirs.has(pkg.dir)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, 'dir'],
+          message: `duplicate package directory ${pkg.dir}`,
+        });
+      }
+      dirs.add(pkg.dir);
+      const namespace = packageNamespace(pkg, root);
+      const other = namespaces.get(namespace);
+      if (other !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, 'dir'],
+          message: `packages ${other} and ${pkg.dir} would both be addressed as ${namespace}`,
+        });
+      }
+      namespaces.set(namespace, pkg.dir);
+    });
+  }),
+});
+
+type GoArtifact = z.infer<typeof goArtifactSchema>;
+type GoPackage = z.infer<typeof packageSchema>;
+type GoType = z.infer<typeof typeSchema>;
+type GoFunc = z.infer<typeof funcSchema>;
+type GoField = z.infer<typeof fieldSchema>;
+type GoValue = z.infer<typeof valueSchema>;
+type GoExample = z.infer<typeof exampleSchema>;
+type GoParam = z.infer<typeof paramSchema>;
+type GoCode = z.infer<typeof codeSchema>;
+type GoRef = z.infer<typeof refSchema>;
+type Location = { slug: string; anchor?: string; page?: string };
+type GoDoc = { tree: MdastRoot };
+
+const TYPE_TAGS: Record<GoType['kind'], string> = {
+  struct: 'STRUCT',
+  interface: 'INTERFACE',
+  defined: 'TYPE',
+  alias: 'TYPE',
+};
+
+export async function convertGo(sourcePath: string): Promise<SdkReference> {
+  const artifact = parseArtifact(await fse.readJson(sourcePath), sourcePath);
+  const index = new GoIndex(artifact);
+  const renderers = artifact.packages.map((pkg) => new GoRenderer(index, pkg));
+
+  const pages: SdkPage[] = [];
+  const groups: SdkNavGroup[] = [];
+  for (const renderer of renderers) {
+    const packagePages = renderer.packagePages();
+    pages.push(...packagePages, ...renderer.memberPages());
+    groups.push({ group: renderer.group, pages: packagePages.map((page) => page.slug) });
+  }
+
+  return { pages, groups };
+}
+
+function parseArtifact(raw: unknown, sourcePath: string): GoArtifact {
+  const version =
+    typeof raw === 'object' && raw !== null && 'schemaVersion' in raw
+      ? raw.schemaVersion
+      : undefined;
+  if (typeof version === 'number' && version !== SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(
+      `Go SDK artifact ${sourcePath} uses schema version ${version}, but Mintlify reads schema version ${SUPPORTED_SCHEMA_VERSION}. Regenerate it with a compatible mintlify-go-extractor release.`
+    );
+  }
+  const result = goArtifactSchema.safeParse(raw);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const detail = issue ? `${issue.path.join('.') || 'artifact'}: ${issue.message}` : 'invalid';
+    throw new Error(`Invalid Go SDK artifact ${sourcePath}: ${detail}`);
+  }
+  return result.data;
+}
+
+function slugify(name: string): string {
+  return name.replace(/[^\p{L}\p{N}\-_.]+/gu, '-').replace(/^-+|-+$/g, '') || 'item';
+}
+
+function packageBase(pkg: GoPackage): string {
+  return pkg.dir === '.' ? '' : pkg.dir.split('/').map(slugify).join('/');
+}
+
+// Packages are addressed as a tree headed by the root package's name and
+// continued by directory path, dotted: the root of openai-go is `package
+// openai` and its symbols `type openai.Client`; audio/client is `package
+// openai.audio.client` (or any trailing part, `package client`) and its
+// symbols `type openai.audio.client.Foo`. api/v1 (package api) is `package
+// api.v1`, not `package api`. The root prefix keeps a root package and a
+// top-level directory of the same name apart; a module without a root package
+// has nothing to keep apart and uses the directory path alone.
+function packageNamespace(pkg: Pick<GoPackage, 'dir' | 'name'>, root?: { name: string }): string {
+  if (pkg.dir === '.') return pkg.name;
+  const dotted = pkg.dir.replaceAll('/', '.');
+  return root ? `${root.name}.${dotted}` : dotted;
+}
+
+function packageTargetName(pkg: GoPackage): string {
+  return pkg.dir === '.' ? pkg.name : path.posix.basename(pkg.dir);
+}
+
+function packageParent(pkg: GoPackage, root?: GoPackage): string | undefined {
+  if (pkg.dir === '.') return undefined;
+  const parent = path.posix.dirname(pkg.dir);
+  const dotted = parent === '.' ? undefined : parent.replaceAll('/', '.');
+  if (!root) return dotted;
+  return dotted ? `${root.name}.${dotted}` : root.name;
+}
+
+function memberHeading(name: string): string {
+  return `${name}()`;
+}
+
+// Method headings carry an explicit id, pkg.go.dev style, so links to them
+// do not depend on how many same-named headings precede them on the page.
+function methodAnchor(type: GoType, method: GoFunc): string {
+  return `${type.name}.${method.name}`;
+}
+
+function packageFuncs(pkg: GoPackage): GoFunc[] {
+  return [...(pkg.funcs ?? []), ...(pkg.types ?? []).flatMap((type) => type.funcs ?? [])].sort(
+    (left, right) => left.name.localeCompare(right.name)
+  );
+}
+
+class GoIndex {
+  readonly module: string;
+  readonly root: GoPackage | undefined;
+  private readonly packages = new Map<string, string>();
+  private readonly symbols = new Map<string, Location>();
+  private readonly routes = new Map<string, number>();
+
+  constructor(artifact: GoArtifact) {
+    this.module = artifact.module;
+    this.root = artifact.packages.find((pkg) => pkg.dir === '.');
+    for (const pkg of artifact.packages) {
+      const base = packageBase(pkg);
+      const overview = { slug: this.route(base, PACKAGE_PAGE) };
+      this.packages.set(pkg.importPath, overview.slug);
+      for (const value of [...(pkg.consts ?? []), ...(pkg.vars ?? [])]) {
+        for (const name of value.names) this.add(pkg, name, overview);
+      }
+      for (const fn of packageFuncs(pkg)) {
+        this.add(pkg, fn.name, { slug: this.route(base, fn.name) });
+      }
+      for (const type of pkg.types ?? []) {
+        const slug = this.route(base, type.name);
+        this.add(pkg, type.name, { slug });
+        for (const value of [...(type.consts ?? []), ...(type.vars ?? [])]) {
+          for (const name of value.names) this.add(pkg, name, { slug });
+        }
+      }
+    }
+    for (const pkg of artifact.packages) {
+      for (const type of pkg.types ?? []) {
+        const slug = this.slugOf(pkg, type.name);
+        for (const method of type.methods ?? []) {
+          this.add(pkg, `${type.name}.${method.name}`, {
+            slug,
+            anchor: methodAnchor(type, method),
+            page: this.route(slug, method.name),
+          });
+        }
+        for (const field of type.fields ?? []) {
+          this.add(pkg, `${type.name}.${field.name}`, {
+            slug,
+            anchor: field.name,
+            page: this.route(slug, field.name),
+          });
+        }
+      }
+    }
+  }
+
+  private add(pkg: GoPackage, name: string, location: Location): void {
+    this.symbols.set(`${pkg.importPath}#${name}`, location);
+  }
+
+  private slugOf(pkg: GoPackage, name: string): string {
+    return this.symbols.get(`${pkg.importPath}#${name}`)?.slug ?? packageBase(pkg);
+  }
+
+  private route(base: string, name: string): string {
+    const slug = path.posix.join(base, slugify(name));
+    // Same key prebuild uses for route collisions (getGeneratedRouteKey).
+    const key = slug.normalize('NFC').toLowerCase();
+    const taken = this.routes.get(key);
+    if (taken === undefined) {
+      this.routes.set(key, 1);
+      return slug;
+    }
+    // A Go identifier cannot contain "-", so `${key}-${attempt}` is only ever a
+    // route this function reserved itself and the next number is free.
+    const attempt = taken + 1;
+    this.routes.set(key, attempt);
+    this.routes.set(`${key}-${attempt}`, 1);
+    return `${slug}-${attempt}`;
+  }
+
+  packageSlug(importPath: string): string | undefined {
+    return this.packages.get(importPath);
+  }
+
+  symbolSlug(importPath: string, name: string): string | undefined {
+    return this.symbols.get(`${importPath}#${name}`)?.slug;
+  }
+
+  memberPageSlug(importPath: string, name: string): string | undefined {
+    return this.symbols.get(`${importPath}#${name}`)?.page;
+  }
+
+  href(importPath: string, name: string | undefined, isPrivate: boolean): string | undefined {
+    if (name) {
+      const dot = name.indexOf('.');
+      const location =
+        this.symbols.get(`${importPath}#${name}`) ??
+        (dot > 0 ? this.symbols.get(`${importPath}#${name.slice(0, dot)}`) : undefined);
+      if (location) return `/${location.slug}${location.anchor ? `#${location.anchor}` : ''}`;
+    }
+    const packageSlug = this.packages.get(importPath);
+    if (packageSlug) return `/${packageSlug}`;
+    if (isPrivate) return undefined;
+    return `https://pkg.go.dev/${encodeHref(importPath)}${name ? `#${encodeHref(name)}` : ''}`;
+  }
+}
+
+class GoRenderer {
+  readonly group: string;
+  private readonly base: string;
+  private readonly funcs: GoFunc[];
+  private readonly rendered = new Map<string, GoDoc>();
+
+  constructor(
+    private readonly index: GoIndex,
+    private readonly pkg: GoPackage
+  ) {
+    this.group = pkg.dir === '.' ? pkg.name : pkg.dir;
+    this.base = packageBase(pkg);
+    this.funcs = packageFuncs(pkg);
+  }
+
+  packagePages(): SdkPage[] {
+    return [
+      this.packagePage(),
+      ...(this.pkg.types ?? []).map((type) => this.typePage(type)),
+      ...this.funcs.map((fn) => this.funcPage(fn)),
+    ];
+  }
+
+  memberPages(): SdkPage[] {
+    return (this.pkg.types ?? []).flatMap((type) => this.typeMemberPages(type));
+  }
+
+  private packagePage(): SdkPage {
+    const slug =
+      this.index.packageSlug(this.pkg.importPath) ?? path.posix.join(this.base, PACKAGE_PAGE);
+    const lines = [this.prose(this.pkg.doc), this.deprecated(this.pkg.deprecated)];
+    const types = this.pkg.types ?? [];
+    if (types.length) lines.push('## Types', this.indexList(types.map((type) => type.name)));
+    if (this.funcs.length) {
+      lines.push('## Functions', this.indexList(this.funcs.map((fn) => fn.name)));
+    }
+    lines.push(...this.valueSection('Constants', this.pkg.consts, 2));
+    lines.push(...this.valueSection('Variables', this.pkg.vars, 2));
+    lines.push(...this.exampleSection(this.pkg.examples, 2));
+    const parent = packageParent(this.pkg, this.index.root);
+    // The synopsis is the package doc's first sentence, so it is read from the
+    // doc's parse, which rendering the page needs anyway.
+    const synopsis = this.description(this.pkg.doc);
+    const readme = this.pkg.readme ? this.readme(this.pkg.readme, synopsis) : undefined;
+    const description = synopsis ?? readme?.description;
+    return {
+      slug,
+      title: `package ${this.pkg.name}`,
+      ...(description ? { description } : {}),
+      tag: 'PACKAGE',
+      ...(readme?.intro ? { intro: readme.intro } : {}),
+      content: join(lines),
+      target: {
+        kind: 'package',
+        name: packageTargetName(this.pkg),
+        ...(parent ? { namespace: parent } : {}),
+      },
+    };
+  }
+
+  // Renders a README the way pkg.go.dev shows it, minus the sentence the page
+  // shows as its description (see takeLeadingSentence).
+  private readme(markdown: string, synopsis?: string): { intro: string; description?: string } {
+    if (unparseable(markdown)) return { intro: codeBlock(markdown, 'text') };
+    const tree = parseMarkdown(markdown);
+    const first = tree.children[0];
+    if (first?.type === 'heading' && first.depth === 1) tree.children.shift();
+    visit(tree, 'heading', (node: Heading) => {
+      node.depth = Math.max(node.depth, MIN_README_HEADING_DEPTH) as Heading['depth'];
+    });
+    const imageDefinitions = new Set<string>();
+    const linkDefinitions = new Set<string>();
+    visit(tree, 'imageReference', (node: ImageReference) => {
+      imageDefinitions.add(node.identifier);
+    });
+    visit(tree, 'linkReference', (node: LinkReference) => {
+      linkDefinitions.add(node.identifier);
+    });
+    rewriteMdastLinks(tree, (node) =>
+      this.repoUrl(
+        node.url,
+        node.type === 'image' ||
+          (node.type === 'definition' &&
+            imageDefinitions.has(node.identifier) &&
+            !linkDefinitions.has(node.identifier))
+      )
+    );
+    const description = takeLeadingSentence(tree, synopsis);
+    return { intro: stringifyMdast(tree), ...(description ? { description } : {}) };
+  }
+
+  // The first sentence of a doc's opening paragraph, read from the parsed tree
+  // rather than from the Markdown source, so link syntax and escapes are
+  // already gone and the cost is linear in the doc's length.
+  private describe(markdown?: string): { description?: string } {
+    const description = this.description(markdown);
+    return description ? { description } : {};
+  }
+
+  private description(markdown?: string): string | undefined {
+    if (!markdown) return undefined;
+    const paragraph = this.doc(markdown).tree.children.find(
+      (node): node is Paragraph => node.type === 'paragraph'
+    );
+    if (!paragraph) return undefined;
+    return firstSentence(plainText(paragraph).replace(/\s+/g, ' ').trim());
+  }
+
+  // Relative README links resolve against the package directory in the
+  // repository; a leading slash means the repository root, as on GitHub.
+  private repoUrl(url: string, raw: boolean): string | undefined {
+    const href = safeHref(url);
+    if (href === undefined || !/^[^#]/.test(href) || /^[a-z][a-z0-9+.-]*:/i.test(href)) {
+      return href;
+    }
+    const match = GITHUB_MODULE.exec(this.index.module);
+    if (!match) return href;
+    const [, owner, repo, moduleDir = ''] = match;
+    const [file = '', hash] = href.split('#');
+    const resolved = file.startsWith('/')
+      ? path.posix.normalize(file.slice(1))
+      : path.posix.normalize(
+          path.posix.join(moduleDir.slice(1), this.pkg.dir === '.' ? '' : this.pkg.dir, file)
+        );
+    if (resolved.startsWith('..')) return href;
+    const view = raw ? 'raw' : 'blob';
+    return `https://github.com/${owner}/${repo}/${view}/HEAD/${resolved}${hash ? `#${hash}` : ''}`;
+  }
+
+  private typePage(type: GoType): SdkPage {
+    const lines = [
+      this.prose(type.doc),
+      this.deprecated(type.deprecated),
+      codeBlock(declarationHeader(type)),
+    ];
+    if (type.typeParams?.length) {
+      lines.push(
+        '## Type Parameters',
+        ...type.typeParams.map((param) => this.field(param.name, param.constraint))
+      );
+    }
+    if (type.fields?.length) {
+      lines.push('## Fields', ...type.fields.map((field) => this.fieldEntry(field)));
+    }
+    lines.push(...this.memberSection('Constructors', type.funcs));
+    lines.push(...this.memberSection('Methods', type.methods, type));
+    lines.push(...this.valueSection('Constants', type.consts, 2));
+    lines.push(...this.valueSection('Variables', type.vars, 2));
+    lines.push(...this.exampleSection(type.examples, 2));
+    return {
+      slug: this.slug(type.name),
+      title: type.name,
+      ...this.describe(type.doc),
+      tag: TYPE_TAGS[type.kind],
+      content: join(lines),
+      target: this.target(type.kind === 'interface' ? 'interface' : 'type', type.name),
+    };
+  }
+
+  private funcPage(fn: GoFunc): SdkPage {
+    const lines = [
+      this.prose(fn.doc),
+      this.deprecated(fn.deprecated),
+      codeBlock(codeText(fn.decl)),
+      ...this.signatureDetails(fn, 2),
+    ];
+    return {
+      slug: this.slug(fn.name),
+      title: fn.name,
+      ...this.describe(fn.doc),
+      tag: 'FUNCTION',
+      content: join(lines),
+      target: this.target('function', fn.name),
+    };
+  }
+
+  private typeMemberPages(type: GoType): SdkPage[] {
+    const methods = (type.methods ?? []).map(
+      (method): SdkPage => ({
+        slug: this.memberSlug(type, method.name),
+        title: `${type.name}.${method.name}`,
+        ...this.describe(method.doc),
+        tag: 'METHOD',
+        content: join(this.funcBody(method, 2)),
+        target: this.target('method', method.name, type.name),
+      })
+    );
+    const fields = (type.fields ?? []).map(
+      (field): SdkPage => ({
+        slug: this.memberSlug(type, field.name),
+        title: `${type.name}.${field.name}`,
+        ...this.describe(field.doc),
+        tag: 'FIELD',
+        content: this.fieldEntry(field),
+        target: this.target('property', field.name, type.name),
+      })
+    );
+    return [...methods, ...fields];
+  }
+
+  private target(kind: SdkPageTarget['kind'], name: string, parent?: string): SdkPageTarget {
+    return {
+      kind,
+      name,
+      ...(parent ? { parent } : {}),
+      namespace: packageNamespace(this.pkg, this.index.root),
+    };
+  }
+
+  private slug(name: string): string {
+    return (
+      this.index.symbolSlug(this.pkg.importPath, name) ?? path.posix.join(this.base, slugify(name))
+    );
+  }
+
+  private memberSlug(type: GoType, name: string): string {
+    return (
+      this.index.memberPageSlug(this.pkg.importPath, `${type.name}.${name}`) ??
+      path.posix.join(this.slug(type.name), slugify(name))
+    );
+  }
+
+  private indexList(names: string[]): string {
+    return names.map((name) => `- [${name}](/${this.slug(name)})`).join('\n');
+  }
+
+  private memberSection(heading: string, fns: GoFunc[] | undefined, owner?: GoType): string[] {
+    if (!fns?.length) return [];
+    const marker = '#'.repeat(MEMBER_HEADING_DEPTH);
+    return [
+      `## ${heading}`,
+      ...fns.flatMap((fn) => [
+        `${marker} ${memberHeading(fn.name)}${owner ? ` {#${methodAnchor(owner, fn)}}` : ''}`,
+        ...this.funcBody(fn, 4),
+      ]),
+    ];
+  }
+
+  private funcBody(fn: GoFunc, depth: number): string[] {
+    return [
+      codeBlock(codeText(fn.decl)),
+      this.prose(fn.doc),
+      this.deprecated(fn.deprecated),
+      ...this.signatureDetails(fn, depth),
+    ];
+  }
+
+  private signatureDetails(fn: GoFunc, depth: number): string[] {
+    const heading = '#'.repeat(depth);
+    const lines: string[] = [];
+    if (fn.typeParams?.length) {
+      lines.push(
+        `${heading} Type Parameters`,
+        ...fn.typeParams.map((param) => this.field(param.name, param.constraint))
+      );
+    }
+    const params = fn.params ?? [];
+    if (params.length) {
+      lines.push(
+        `${heading} Parameters`,
+        ...(params.every((param): param is GoParam & { name: string } => Boolean(param.name))
+          ? params.map((param) => this.field(param.name, param.type))
+          : [this.returns(params)])
+      );
+    }
+    if (fn.results?.length) lines.push(`${heading} Returns`, this.returns(fn.results));
+    lines.push(...this.exampleSection(fn.examples, depth));
+    return lines;
+  }
+
+  private returns(results: GoParam[]): string {
+    const tokens: LinkedToken[] = [];
+    results.forEach((result, position) => {
+      if (position > 0) tokens.push({ text: ', ' });
+      tokens.push(...this.tokens(result.type));
+    });
+    if (results.length > 1) {
+      tokens.unshift({ text: '(' });
+      tokens.push({ text: ')' });
+    }
+    return linkedCode(tokens) ?? inlineCode(tokens.map((token) => token.text).join(''));
+  }
+
+  private fieldEntry(field: GoField): string {
+    const body = join([
+      field.embedded ? 'Embedded field.' : undefined,
+      field.tag ? `**Tag:** ${inlineCode(field.tag)}` : undefined,
+      this.prose(field.doc),
+      this.deprecated(field.deprecated),
+    ]);
+    return this.field(field.name, field.type, body, field.name);
+  }
+
+  // The type attribute is cut at 80 characters, so a longer type is also
+  // written out in full in the body: linked when it has refs, plain otherwise.
+  private field(name: string, code: GoCode, body?: string, id?: string): string {
+    const typeHref = this.singleRefHref(code);
+    const text = codeText(code);
+    const full = typeHref
+      ? undefined
+      : (linkedCode(this.tokens(code)) ??
+        (text.length > MAX_TYPE_ATTR ? inlineCode(text) : undefined));
+    const content = join([full && `**Type:** ${full}`, body]);
+    return responseField(name, text, true, content, typeHref, id);
+  }
+
+  private singleRefHref(code: GoCode): string | undefined {
+    const position = code.findIndex((token) => token.ref);
+    if (position === -1 || position !== code.length - 1) return undefined;
+    const prefix = codeText(code.slice(0, position));
+    if (!/^(?:\*|\[\]|\.\.\.)*(?:[\p{L}_][\p{L}\p{N}_]*\.)?$/u.test(prefix)) return undefined;
+    const ref = code[position]?.ref;
+    const href = ref ? this.refHref(ref) : undefined;
+    return href?.startsWith('/') ? href : undefined;
+  }
+
+  private tokens(code: GoCode): LinkedToken[] {
+    return code.map((token) => {
+      const href = token.ref ? this.refHref(token.ref) : undefined;
+      return href ? { text: token.t, href } : { text: token.t };
+    });
+  }
+
+  private refHref(ref: GoRef): string | undefined {
+    return this.index.href(ref.pkg ?? this.pkg.importPath, ref.name, ref.private ?? false);
+  }
+
+  private valueSection(heading: string, values: GoValue[] | undefined, depth: number): string[] {
+    if (!values?.length) return [];
+    return [
+      `${'#'.repeat(depth)} ${heading}`,
+      ...values.flatMap((value) => [
+        codeBlock(codeText(value.decl)),
+        this.prose(value.doc),
+        this.deprecated(value.deprecated),
+      ]),
+    ];
+  }
+
+  private exampleSection(examples: GoExample[] | undefined, depth: number): string[] {
+    if (!examples?.length) return [];
+    const heading = '#'.repeat(depth);
+    return [
+      `${heading} Examples`,
+      ...examples.flatMap((example) => [
+        `${heading}# ${example.suffix ? `Example (${example.suffix})` : 'Example'}`,
+        this.prose(example.doc),
+        codeBlock(example.code),
+        example.output ? `Output:\n\n${codeBlock(example.output.replace(/\n+$/, ''), 'text')}` : '',
+      ]),
+    ];
+  }
+
+  private deprecated(text?: string): string {
+    if (!text) return '';
+    return `<Warning>\n${indent(`Deprecated: ${this.prose(text)}`)}\n</Warning>`;
+  }
+
+  private prose(markdown?: string): string {
+    return markdown ? stringifyMdast(this.doc(markdown).tree) : '';
+  }
+
+  private doc(markdown: string): GoDoc {
+    let doc = this.rendered.get(markdown);
+    if (!doc) {
+      doc = this.parseDoc(markdown);
+      this.rendered.set(markdown, doc);
+    }
+    return doc;
+  }
+
+  private parseDoc(markdown: string): GoDoc {
+    if (unparseable(markdown)) {
+      return {
+        tree: { type: 'root', children: [{ type: 'code', lang: 'text', value: markdown }] },
+      };
+    }
+    const tree = parseMarkdown(markdown, MIN_COMMENT_HEADING_DEPTH);
+    rewriteMdastLinks(tree, (node) => {
+      if (!node.url.startsWith('go:')) return safeHref(node.url);
+      return this.resolveDocLink(node.url.slice('go:'.length));
+    });
+    return { tree };
+  }
+
+  private resolveDocLink(target: string): string | undefined {
+    const hash = target.indexOf('#');
+    const importPath = hash === -1 ? target : target.slice(0, hash);
+    const name = hash === -1 ? undefined : target.slice(hash + 1);
+    return this.index.href(importPath, name, false);
+  }
+}
+
+function codeText(code: GoCode): string {
+  return code.map((token) => token.t).join('');
+}
+
+function declarationHeader(type: GoType): string {
+  const text = codeText(type.decl);
+  if (type.kind !== 'struct' && type.kind !== 'interface') return text;
+  const open = bodyStart(text, type.kind);
+  if (open === -1) return text;
+  if (type.kind === 'interface') {
+    const body = text.slice(open + type.kind.length + 3, text.lastIndexOf('}'));
+    const entries = body
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('//'));
+    const shown = (type.methods?.length ?? 0) + (type.fields?.length ?? 0);
+    if (entries.length > shown) return text;
+  }
+  return text.slice(0, open + type.kind.length + 1);
+}
+
+// The declaration's own body opens outside any type-parameter brackets; a
+// constraint written as `interface{ ... }` inside `[...]` comes first in the
+// text but is not it.
+function bodyStart(text: string, kind: 'struct' | 'interface'): number {
+  const marker = ` ${kind} {`;
+  let depth = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '[') depth += 1;
+    else if (char === ']') depth -= 1;
+    else if (depth === 0 && text.startsWith(marker, i)) return i;
+  }
+  return -1;
+}
+
+function codeBlock(code: string, lang = 'go'): string {
+  const longestRun = Math.max(0, ...(code.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = '`'.repeat(Math.max(3, longestRun + 1));
+  return `${fence}${lang}\n${code}\n${fence}`;
+}
+
+function join(chunks: (string | undefined)[]): string {
+  return chunks.filter(Boolean).join('\n\n');
+}
+
+// The README's first prose paragraph (badges, images, and HTML blocks such as a
+// centred <h1> are skipped) supplies the description when the page has none,
+// provided it is a single sentence, and is then removed from the intro since
+// the page already shows it. When the package doc supplied the description and
+// the README opens with the same sentence, that sentence is removed instead.
+function takeLeadingSentence(tree: MdastRoot, synopsis?: string): string | undefined {
+  const index = tree.children.findIndex(
+    (node) => node.type === 'paragraph' && !isHtmlParagraph(node) && isProseParagraph(node)
+  );
+  const paragraph = tree.children[index] as Paragraph | undefined;
+  if (!paragraph) return synopsis;
+  const text = plainText(paragraph).replace(/\s+/g, ' ').trim();
+  const sentence = leadingSentence(text);
+  if (!sentence || (synopsis !== undefined && truncate(sentence, MAX_DESCRIPTION) !== synopsis)) {
+    return synopsis;
+  }
+  if (sentence === text) {
+    tree.children.splice(index, 1);
+    return synopsis ?? truncate(sentence, MAX_DESCRIPTION);
+  }
+  if (synopsis !== undefined) dropLeadingSentence(paragraph);
+  return synopsis;
+}
+
+// Removes a paragraph's first sentence, whatever inline markup it contains,
+// by dropping the children that lie wholly inside it and trimming the text
+// node it ends in. When the sentence ends inside a link or emphasis, nothing
+// is removed rather than splitting that node.
+function dropLeadingSentence(paragraph: Paragraph): void {
+  const pieces = paragraph.children.map(plainText);
+  const end = /\.(?:\s|$)/.exec(pieces.join(''));
+  if (!end) return;
+  const stop = end.index + 1;
+  let offset = 0;
+  for (let i = 0; i < paragraph.children.length; i += 1) {
+    const child = paragraph.children[i];
+    const length = pieces[i]?.length ?? 0;
+    if (offset + length <= stop) {
+      offset += length;
+      continue;
+    }
+    if (offset === stop) {
+      // The sentence ended with the previous node; drop it and any hard
+      // break that separated it from the rest.
+      paragraph.children.splice(0, i);
+      while (paragraph.children[0]?.type === 'break') paragraph.children.shift();
+      const next = paragraph.children[0];
+      if (next?.type === 'text') {
+        next.value = next.value.trimStart();
+        if (next.value === '') paragraph.children.shift();
+      }
+      return;
+    }
+    if (child?.type !== 'text') return;
+    child.value = child.value.slice(stop - offset).trimStart();
+    paragraph.children.splice(0, i);
+    if (child.value === '') paragraph.children.shift();
+    return;
+  }
+  paragraph.children = [];
+}
+
+// Text past either limit is rendered as a text block instead of Markdown.
+// micromark is quadratic in unclosed brackets (80k `[a](` takes about 45 s)
+// and in balanced link and emphasis markup (40k nested brackets, `[]` pairs,
+// `[a]` references, or `*a` runs take 5 to 36 s), and remark-stringify is
+// quadratic in the characters it escapes (40k `<` or `{` take 0.7 s, minutes
+// at the 1 MiB cap). At 10k either costs well under 2 s. The largest real doc
+// seen (openai-go's README, 60 KB) has about 1,500 such characters and no more
+// than 3 unclosed brackets.
+const MAX_UNCLOSED = 1000;
+const MAX_MARKUP = 10000;
+const MARKUP = new Set(['[', ']', '*', '_', '<', '>', '{', '}', '`', '&']);
+
+function unparseable(markdown: string): boolean {
+  let square = 0;
+  let round = 0;
+  let unclosed = 0;
+  let markup = 0;
+  for (let i = 0; i < markdown.length; i += 1) {
+    const char = markdown[i];
+    if (char !== undefined && MARKUP.has(char)) markup += 1;
+    if (char === '\\') i += 1;
+    else if (char === '[') square += 1;
+    else if (char === '(') round += 1;
+    else if (char === ']') {
+      if (square > 0) square -= 1;
+      else unclosed += 1;
+    } else if (char === ')') {
+      if (round > 0) round -= 1;
+      else unclosed += 1;
+    }
+  }
+  return square + round + unclosed > MAX_UNCLOSED || markup > MAX_MARKUP;
+}
+
+const MAX_DESCRIPTION = 160;
+
+// The text up to and including the first full stop that ends a sentence, or
+// all of it; untruncated, so it can be compared with the paragraph it came from.
+function leadingSentence(text: string): string | undefined {
+  if (!text) return undefined;
+  const end = /\.\s/.exec(text);
+  return end ? text.slice(0, end.index + 1) : text;
+}
+
+function firstSentence(text: string): string | undefined {
+  const sentence = leadingSentence(text);
+  return sentence && truncate(sentence, MAX_DESCRIPTION);
+}