fix: update docgen templates and automate API reference generation by stevep0z · Pull Request #140 · OpenZeppelin/docs

stevep0z · 2026-04-05T01:28:09Z

Summary

Fix docgen template helpers to resolve cross-standard contamination in API reference pages
Add template injection to generate-api-docs.js so the docs monorepo controls template quality
Add receiver workflows for openzeppelin-contracts and confidential-contracts
Add link validation step to all receiver workflows
Regenerate API reference for contracts 5.x, community-contracts, and confidential-contracts

Details

Template fixes (docgen/templates-md/helpers.js)

The previous helpers.js used fuzzy matching for natspec references, which caused cross-standard contamination. For example, the ERC20 constructor description referenced Governor.name and IERC6909Metadata.symbol instead of ERC20.name and ERC20.symbol.

Fixes include:

Strict reference matching with same-page preference
Absolute paths for cross-page links using API_DOCS_PATH
Multi-line callout handling (NOTE/WARNING blocks spanning multiple lines)
Bare < escaping in natspec to prevent MDX parse errors
Antora xref pattern conversion to markdown links
AsciiDoc heading conversion and orphaned delimiter cleanup

Collapsible inherited functions (docgen/templates-md/contract.hbs)

Inherited function/event/error listings in TOC sections are now wrapped in collapsible toggles. The contract's own items are visible by default; inherited items are accessible but not overwhelming. Empty toggles are filtered out.

Template injection (scripts/generate-api-docs.js)

The script now injects canonical MDX templates from docgen/templates-md/ into the cloned source repo before running docgen. This makes the docs monorepo the single source of truth for templates. Source repos do not need MDX templates committed.

The script also supports a --pre-generated flag for non-Solidity repos that generate MDX through their own tooling.

Receiver workflows

New workflows for openzeppelin-contracts (versioned, tag-based) and confidential-contracts (non-versioned, tag-based). Link validation step added to all receiver workflows including the existing community-contracts workflow.

Test plan

Run pnpm run check (0 errors)
Run pnpm run build (clean)
Visual inspection of API reference pages
After merge: manually trigger each receiver workflow to verify PR creation
Verify ERC20 page references only ERC20 contracts (no cross-contamination)
Verify collapsible toggles render and expand/collapse correctly
Verify GitHub source links point to correct repos and versions

…t fixes - Remove fuzzy reference matching that caused cross-standard contamination (e.g., ERC20 constructor referencing Governor.name, IERC6909Metadata.symbol) - Add same-page preference so {name} on an ERC20 page resolves to ERC20.name - Use absolute paths for cross-page links via API_DOCS_PATH - Fix multi-line callout handling (NOTE: blocks spanning multiple lines) - Escape bare < in natspec (e.g., < 0x80) to prevent MDX parse errors - Convert Antora xref patterns to markdown links - Convert AsciiDoc headings (====) to markdown (####) - Clean up orphaned block delimiters - Strip /index from links for Fumadocs compatibility

Regenerated from openzeppelin-contracts (master) and openzeppelin-community-contracts (master) using updated docgen templates. - All cross-page links use absolute paths - No cross-standard contamination in reference resolution - No legacy AsciiDoc patterns in output - 0 link validation errors

Wrap inherited function/event/error listings in <details>/<summary> toggles so the contract's own items are prominent and inherited items are accessible but not overwhelming. Only renders toggles for inherited contracts that have items for that section (no empty toggles). Also regenerates API reference output with updated template.

The script now injects canonical MDX templates from docgen/templates-md/ into the cloned source repo before running docgen. This means source repos don't need to have MDX templates committed — the docs monorepo is the single source of truth. - Copies templates-md/ and config-md.js into cloned repo - Customizes API_DOCS_PATH, GitHub link, and import path per source repo - Patches hardhat config to use config-md - Overwrites config.js so prepare-docs.sh scripts still work - Handles local paths, broken symlinks, both .js and .ts hardhat configs - Adds --skip-template-inject flag for repos that already have MDX templates

Regenerated via generate-api-docs.js with template injection for: - openzeppelin-contracts (master) -> content/contracts/5.x/api/ - openzeppelin-community-contracts (master) -> content/community-contracts/api/ - openzeppelin-confidential-contracts (master) -> content/confidential-contracts/api/ All repos: 0 link errors, clean build.

New GitHub Actions receiver workflows for API doc generation: - generate-api-docs-contracts.yml: versioned paths (5.x/api), tag-based - generate-api-docs-confidential-contracts.yml: non-versioned (api/), tag-based Both include link validation step before PR creation.

Adds postinstall + lint:links step before PR creation to catch broken links in generated docs before they're merged.

Prevents temp directories from showing in source control if a generate-api-docs.js run is interrupted before cleanup.

For repos using Move, Rust, Cairo, or other languages that generate MDX through their own tooling, the script can now skip template injection and docgen entirely and just copy pre-generated MDX files. Usage: node generate-api-docs.js --repo <url> --api-output <dir> --pre-generated <path> This keeps the workflow generator-agnostic: Solidity repos use the default injection mode, other repos use --pre-generated.

netlify · 2026-04-05T01:28:16Z

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Name	Link
🔨 Latest commit	`80a979a`
🔍 Latest deploy log	https://app.netlify.com/projects/openzeppelin-docs-v2/deploys/69d1c1339df29f0009309642
😎 Deploy Preview	https://deploy-preview-140--openzeppelin-docs-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

.github/workflows/generate-api-docs-confidential-contracts.yml

.github/workflows/generate-api-docs-contracts.yml

Replace the old manual template-copy instructions with documentation for the template injection approach and automated GitHub workflow. Covers Solidity repos, non-Solidity repos (--pre-generated flag), canonical template locations, and versioning strategy.

- Use execFileSync for git clone to prevent command injection from CLI arguments (array args instead of shell string interpolation) - Add explicit permissions block to all receiver workflows to limit GITHUB_TOKEN scope to contents:write and pull-requests:write

ernestognw · 2026-04-06T20:17:52Z

docgen/templates-md/helpers.js

This is still fuzzy. I believe we should update it to use the same-page preference logic that findBestMatch has

ernestognw · 2026-04-06T20:21:30Z

docgen/templates-md/helpers.js

-  result = result.replace(/^(NOTE|TIP):\s*(.+)$/gm, '<Callout>\n$2\n</Callout>');
-  result = result.replace(/^(IMPORTANT|WARNING):\s*(.+)$/gm, '<Callout type="warn">\n$2\n</Callout>');
+  // Handle single/multi-line admonitions (NOTE: content until blank line)
+  result = result.replace(/^(NOTE|TIP):\s*([\s\S]*?)(?=\n\n|$)/gm, '<Callout>\n$2\n</Callout>');


With the m flag, $ matches end of each line, not end of string. This means multi-line content after NOTE: would still only capture the first line

Maybe this would work but it's a bit too dense:

Suggested change

result = result.replace(/^(NOTE|TIP):\s*([\s\S]*?)(?=\n\n|$)/gm, '<Callout>\n$2\n</Callout>');

result = result.replace(/(^|\n)(NOTE|TIP):\s*([\s\S]*?)(?=\n\n|$(?![\s\S]))/g, '$1<Callout>\n$3\n</Callout>');

It may be better to match with a different strategy here. But please confirm

ernestognw · 2026-04-06T20:26:23Z

scripts/generate-api-docs.js

The script does two things that overlap:

Copies config-md.js to docs/config-md.js AND also overwrites docs/config.js with config-md.js content.

Then patches hardhat.config.js to change require('./docs/config') → require('./docs/config-md').

The hardhat overwrite is redundant since config.js is already overwritten with the md config content. I believe we should simplify it. It seems we're carrying older design decisions and I'm worried the script might get even more confusing later on

ernestognw · 2026-04-06T20:28:28Z

scripts/generate-api-docs.js

+			if (config.includes("require('./docs/config')")) {
+				config = config.replace(
+					"require('./docs/config')",
+					"require('./docs/config-md')",
+				);


I find this expression pretty brittle because it's relying on single quotes '. If we change a linter or something like that, this may silently fail in the future.

Given my previous comment, this replace might be irrelevant

ernestognw · 2026-04-06T20:29:31Z

.github/workflows/generate-api-docs-contracts.yml

These workflows (generate-api-docs-contracts.yml, generate-api-docs-confidential-contracts.yml, generate-api-docs-community-contracts.yml) are almost identical. We should parameterize them to reuse the logic

ernestognw · 2026-04-06T20:30:05Z

.github/workflows/generate-api-docs-confidential-contracts.yml

+            BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')
+
+            git checkout -b "$BRANCH_NAME"
+            git add .


This is too broad, maybe:

Suggested change

git add .

git add content/ examples/

ernestognw · 2026-04-06T20:30:10Z

.github/workflows/generate-api-docs-contracts.yml

+            BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')
+
+            git checkout -b "$BRANCH_NAME"
+            git add .


ernestognw · 2026-04-06T20:33:16Z

.github/workflows/generate-api-docs-contracts.yml

+
+            Auto-generated via workflow_dispatch" \
+                     --base main \
+                     --head "$BRANCH_NAME" || echo "⚠️  Pull Request creation failed"


If the PR creation fails we're only logging the failure. I believe we should fail this step or use GIthub CI annotations (e.g. ::warning / ::error)

ernestognw · 2026-04-06T20:38:53Z

content/contracts/5.x/api/token/ERC20.mdx

-<Callout type="warn">
-In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning
+[CAUTION]
+#### In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning


This seems wrong

The [CAUTION] tag isn't converted to a , and the ==== heading became ####

stevep0z added 9 commits April 2, 2026 10:22

feat: add link validation to community-contracts receiver workflow

388812e

Adds postinstall + lint:links step before PR creation to catch broken links in generated docs before they're merged.

chore: add temp-* to gitignore for generate-api-docs cleanup

814a708

Prevents temp directories from showing in source control if a generate-api-docs.js run is interrupted before cleanup.

stevep0z self-assigned this Apr 5, 2026

github-advanced-security bot found potential problems Apr 5, 2026

View reviewed changes

.github/workflows/generate-api-docs-confidential-contracts.yml Fixed Show fixed Hide fixed

.github/workflows/generate-api-docs-contracts.yml Fixed Show fixed Hide fixed

stevep0z added 2 commits April 4, 2026 20:41

stevep0z mentioned this pull request Apr 6, 2026

Update docs workflow for new docs monorepo OpenZeppelin/openzeppelin-contracts#6463

Open

ernestognw reviewed Apr 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: update docgen templates and automate API reference generation#140

fix: update docgen templates and automate API reference generation#140
stevep0z wants to merge 11 commits intomainfrom
fix/docgen-template-fixes

stevep0z commented Apr 5, 2026

Uh oh!

netlify bot commented Apr 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

ernestognw Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	result = result.replace(/^(NOTE\|TIP):\s([\s\S]?)(?=\n\n\|$)/gm, '<Callout>\n$2\n</Callout>');
	result = result.replace(/(^\|\n)(NOTE\|TIP):\s([\s\S]?)(?=\n\n\|$(?![\s\S]))/g, '$1<Callout>\n$3\n</Callout>');

Conversation

stevep0z commented Apr 5, 2026

Summary

Details

Template fixes (docgen/templates-md/helpers.js)

Collapsible inherited functions (docgen/templates-md/contract.hbs)

Template injection (scripts/generate-api-docs.js)

Receiver workflows

Test plan

Uh oh!

netlify bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Apr 5, 2026 •

edited

Loading