chore: added markdown docs templates

[stevedylandev]

31/10/2025:

This PR adds the updated templates-md and config-md.js to the docs directory. By doing this we can generate API documentation for OpenZeppelin/docs remotely. Please see the guide here

Update (18/12/2025):

• Removes adoc in favor of markdown
• Removes Antora.yml
• Reworks the templates
• Adds a github workflow for automation
• Since the docs are now a separate Next.js project, a simple oz-docs.sh bash script is used in favor of docs-utils, which clones the @openzeppelin/docs repository and runs it locally with a chokidar watcher that re-prepares and syncs the docs into the local docs project on changes for a hot refresh experience.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "chore: added markdown docs templates" accurately describes the main objective of this changeset. The PR adds a new markdown documentation template system with several new files (contract.hbs, page.hbs, helpers.js, properties.js, and config-md.js) to enable API documentation generation. The title is specific and clearly communicates the primary change—adding markdown documentation templates—in a concise manner that a teammate scanning the commit history would immediately understand. The title is neither vague nor misleading and directly reflects the content of the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

♻️ Duplicate comments (1)

docs/templates-md/properties.js (1)

23-29: Code duplication and null safety issue.

This code duplicates the signature-building logic from the anchor function and has the same null safety concerns.

See the refactor suggestion in the previous comment (lines 10-16) which addresses both issues by extracting common logic and adding null checks.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3b358b3 and f41f1b0.

📒 Files selected for processing (6)

• docs/config-md.js (1 hunks)
• docs/templates-md/contract.hbs (1 hunks)
• docs/templates-md/helpers.js (1 hunks)
• docs/templates-md/page.hbs (1 hunks)
• docs/templates-md/properties.js (1 hunks)
• hardhat.config.js (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

hardhat.config.js (2)

docs/templates-md/helpers.js (2)

• require (1-1)
• require (4-4)

docs/templates-md/properties.js (2)

• require (1-1)
• require (2-2)

docs/templates-md/properties.js (1)

docs/templates-md/helpers.js (2)

• slug (67-72)
• i (139-139)

docs/templates-md/helpers.js (1)

docs/templates-md/properties.js (5)

• require (1-1)
• require (2-2)
• item (83-83)
• signature (11-11)
• signature (24-24)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: slither
• GitHub Check: tests-foundry
• GitHub Check: coverage
• GitHub Check: tests

🔇 Additional comments (3)

docs/templates-md/properties.js (3)

59-65: LGTM! Good defensive coding.

The ternary operator properly handles the case where item.variables doesn't exist, preventing potential runtime errors.

---

67-72: LGTM!

The function correctly aggregates publicly visible functions and public variables using AST queries with appropriate visibility filters.

---

47-57: Add null safety checks for item.inheritance.

All three functions assume item.inheritance exists and is an array. If it's undefined, calling .some() will throw a runtime error.

Apply this diff to add defensive checks:

 module.exports['has-functions'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.functions.length > 0);
+  return item.inheritance?.some(c => c.functions?.length > 0) ?? false;
 };
 
 module.exports['has-events'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.events.length > 0);
+  return item.inheritance?.some(c => c.events?.length > 0) ?? false;
 };
 
 module.exports['has-errors'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.errors.length > 0);
+  return item.inheritance?.some(c => c.errors?.length > 0) ?? false;
 };

Likely an incorrect or invalid review comment.

[stevedylandev]

Updated the following legacy patterns in the natspec:

• https://url[Link Text] -> [Link Text](https://url)
• WARNING: | IMPORTANT: | CAUTION: | IMPORTANT: -> <Callout type=warn"></Callout>
• NOTE: | TIP: ->
• Delimitters such as ==== -> #### or removed if no header text
  present

With the adoc conversion to mdx in addition to these changes to the natspec we were able to simplify docs/helpers.js. While it is still a fair bit larger than the original version, much of this was necessary to make docgen work with markdown syntax and keeping cross reference links.

[james-toussaint]

So most replacing logic can be removed now right?

[stevedylandev]

I think for this repo we could remove pieces like L:146-149 and maybe L:157-162, but these are patterns used in other libraries. We definitely still need L:151-155 and the rest of functions to handle instances where a contract references another contract, .e.g. you might have {ERC20} inside ERC1155 comments and we need to turn that into a markdown link.

[ernestognw]

I would also remove L:146-149

[gonzaotc]

I honestly do not like the NatSpec changes of TIP, WARNING and NOTE into writting HTML components inside our contracts. While it remains functional, I think it looks much worse for a human reading the contracts directly. Therefore, I think the parsing into HTML components should happen outside of the contracts and maintain human-first readability.

[james-toussaint]

I honestly do not like the NatSpec changes of TIP, WARNING and NOTE into writting HTML components inside our contracts. While it remains functional, I think it looks much worse for a human reading the contracts directly. Therefore, I think the parsing into HTML components should happen outside of the contracts and maintain human-first readability.

Yes, at the very beginning I thought changing these were the only things required for the API doc migration so why not doing it, but afterward considering the later high templating/processing, I would also like to come back to the original NatSpec 👍

[gonzaotc]

Just automated the watch mode so changes are hot-refreshed on the local copy of the docs repository. Also added cache so it is updated instead of being re-clonned each time docs are run

[ernestognw]

I'm leaving some observations and recommendations but I don't want to block the PR. There may be still some details in how we're processing the docs but we can sort them out easily as long as we have a preview for future PRs.

[ernestognw]

Haven't checked personally but I feel there might be orphan exported functions here now that we changed the contract.hbs and page.hbs. It may be good to do a cleanup of this and the properties.js file

[james-toussaint]

At least internal-variables things got removed from documentation, do you confirm we don't need it in the final public documentation?

[ernestognw]

They're not referenced in the docs repo, and also these should apply only to the templates in this repo so I think it's safe to remove them

[ernestognw]

Closing in favor of #225