Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (60 loc) · 5.25 KB

AGENTS.md

File metadata and controls

86 lines (60 loc) · 5.25 KB
Raw

AGENTS.md — Identus Documentation Portal

Identus documentation site built with Docusaurus 3. Yarn-based monorepo that aggregates content from local files and two git submodules.

Commands

yarn install        # Install deps; postinstall hook runs prepare.sh automatically
yarn start          # Dev server (also runs prepare.sh before starting)
yarn build          # Production build (prepare.sh → Docusaurus SSG → static site in build/)
yarn clear          # Clear Docusaurus cache (.docusaurus/)
yarn serve          # Serve the production build locally

prepare.sh runs docusaurus clean-api-docs all && docusaurus gen-api-docs all — it is invoked automatically by yarn install (postinstall) and by yarn start/yarn build. You do not need to run it manually.

Content architecture

All documentation content flows into a single Docusaurus instance via three source paths configured in src/config/constants.ts:

Source path Contents Origin
documentation/ Learn, develop, reference sections Local (committed in this repo)
cloud-agent/docs/docusaurus/ Cloud Agent guides and OpenAPI spec cloud-agent/ git submodule
sdk-ts/docs/ TypeScript SDK docs (TypeDoc-generated) sdk-ts/ git submodule

Three sidebars (sidebars.ts) map to three top-level nav items:

  • Learn → learnSidebar (discovers learn/ across all content sources)
  • Developers → developersSidebar (discovers develop/)
  • Reference → referenceSidebar (discovers reference/)

Sidebar items are resolved at build time by src/utils/discovery.ts — it scans each content source for sidebar.ts files or _category_.json files and falls back to auto-generated items sorted by sidebar_position frontmatter.

Auto-generated content — do not edit manually

  • documentation/reference/Cloud Agent API/ — Generated by docusaurus-plugin-openapi-docs from cloud-agent/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml. Regenerated by prepare.sh. Any manual edits here are overwritten on the next build.
  • SDK TypeDoc pages (sdk-ts/docs/sdk/) — Pre-generated by TypeDoc in the sdk-ts submodule and committed there; consumed read-only by this repo. (docusaurus-plugin-typedoc is a devDependency but is not configured in the Docusaurus build pipeline.) A custom parseFrontMatter hook in docusaurus.config.ts extracts titles from these pages so they render correctly in sidebars. Do not hand-edit these files — regenerate them in the sdk-ts submodule instead.

Submodules

cloud-agent/ and sdk-ts/ are git submodules providing their documentation and OpenAPI specs:

git submodule init
git submodule update --remote --recursive

CI updates submodules weekly via .github/workflows/update-submodules.yml. When working with submodule content, ensure the submodule is checked out at the correct commit.

Sidebar & navigation customization

  • sidebars.ts — Entry point; calls discoverSidebar() for each section
  • src/utils/discovery.ts — Scans content paths, loads per-directory sidebar.ts or _category_.json, falls back to auto-generation
  • src/config/presets.ts — Multi-doc preset wiring; configures the docs plugin with include globs, the OpenAPI plugin, and remarkLinkFixer
  • src/plugins/remarkLinkFixer.js — Rewrites legacy markdown links (e.g., old /home/ paths) to current URLs; rules configured in presets.ts
  • src/config/headerMenu.ts — Top navbar items
  • _category_.json in content dirs — Sets label, position, collapsibility for sidebar categories

API doc generation (Redocly)

redocly.yaml configures Redocly OpenAPI rendering (theme colors, sidebar, code blocks). This controls how the Cloud Agent API reference looks inside the Docusaurus site. The underlying spec file is cloud-agent/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml.

Build output

yarn build produces a static site in build/ that is deployed to https://hyperledger-identus.github.io/docs/ via release-gh-pages.yml. The site is a static SSG — no server-side rendering.

CI & quality checks

  • Mega-linter — Runs on all PRs (.github/workflows/mega-linter.yml); applies auto-fixes and creates fix PRs
  • Linkinator — Checks broken links on push to main and weekly on Mondays (.github/workflows/link-check.yml); config in .linkinatorrc.json
  • GitHub Pages deploy — release-gh-pages.yml builds and deploys on push to main; uses peaceiris/actions-gh-pages with IDENTUS_CI token

Key config files

File Purpose
docusaurus.config.ts Docusaurus core config: site metadata, markdown settings, front matter hooks, plugins
src/config/presets.ts Multi-doc preset: content sources, OpenAPI plugin config, remark link fixer rules
src/config/constants.ts Content path constants (documentation/, cloud-agent/docs/docusaurus/, sdk-ts/docs/)
src/config/headerMenu.ts Navbar sidebar associations
src/utils/discovery.ts Auto-discovers sidebar items from content directories
sidebars.ts Sidebar wiring using discoverSidebar()
redocly.yaml Redocly OpenAPI rendering theme
prepare.sh Pre-build: cleans and regenerates API docs
package.json Scripts, deps, Yarn 4 config