@algorandfoundation/algo-docs-sync

End-to-end documentation tooling for AlgoKit projects. Install once, pick the documentation generator you need, and every build copies your guides, invokes the configured generator (TypeDoc today, more stacks tomorrow), writes manifest.json, and publishes the result to a dedicated docs branch.

1. Install & authenticate

1. Add the tool as a dev dependency:

   npm install --save-dev @algorandfoundation/algo-docs-sync

2. Scaffold the repo

Run the initializer from your project root and choose a generator (required). For TypeScript repos you’ll typically pass typedoc; future generators (e.g., Python/Sphinx) will expose their own templates.

npx algo-docs init --generator typedoc

This command:

• Drops docs-config.json (guide + API glob rules plus a required generator field) and typedoc.json when using the typedoc generator.
• Copies .github/workflows/build-docs.yml, pre-wired with installation, build, manifest, and deploy steps.
• Creates a docs/ folder if it doesn’t exist so you can start committing guide markdown right away.

Commit the generated files (docs-config.json, typedoc.json, .github/workflows/build-docs.yml) before moving on.

3. What the pipeline does

docs-config.json declares a generator and a basePath. Every run of npx algo-docs build dispatches to the selected generator. For the typedoc generator the flow is:

1. Build – run TypeDoc (with typedoc-plugin-markdown) to generate API docs at basePath/api.
2. Stage – npx algo-docs stage reads from basePath/guides and basePath/api, applies include/exclude filters, and copies the results to docs-publish/<version>.
3. Manifest – npx algo-docs manifest writes basePath/manifest.json including repo metadata, git info, and tool versions.
4. Publish – the workflow clones the current docs-dist branch into docs-publish, stages the filtered docs, and pushes the whole tree back via peaceiris/actions-gh-pages.
   • Manual dispatches refresh only docs-dist/latest.
   • Release events drop the new build into docs-dist/v<tag> (e.g., docs-dist/v1.3.5) and also refresh docs-dist/latest so you always have a rolling view and versioned snapshots.

Developers can explore the generated docs locally by opening the basePath/ directory, while CI keeps the branch copy in sync.

4. Wire up GitHub Actions

The initializer drops the build-docs.yml workflow into the .github.workflows/ folder.

Key secrets:

• GITHUB_TOKEN (provided automatically) – used by peaceiris/actions-gh-pages to push to docs-dist. Ensure the repo’s Workflow permissions allow write access.

Once merged into your default branch, the workflow will:

• Update docs-dist/latest on pushes, pull requests, and manual dispatches.
• Create docs-dist/<release-tag> when you publish a GitHub Release.

You can download the generated artifact (docs-dist.zip) from each run if you need to inspect the raw files.

5. Local commands

• npx algo-docs validate – schema-check docs-config.json.
• npx algo-docs build – run TypeDoc to generate API docs at basePath/api. Pass --generator <name> to override the generator value declared in docs-config.json.
• npx algo-docs stage – copy and filter docs from basePath/guides and basePath/api to docs-publish/<version>. Use --version <tag> for versioned releases and --update-latest to also update the latest folder.
• npx algo-docs manifest – write basePath/manifest.json with repo metadata, git info, and tool versions.
• npx algo-docs migrate – update an existing docs-config.json to the latest schema version.

These commands respect --config, --verbose, and --quiet flags so you can customize paths or diagnostics when experimenting locally.

7. Generators

The CLI ships with a pluggable generator system:

| Name | Description | | -------- | ---------------------------------------------------------------- | | typedoc | Builds API markdown from TypeScript entry points using TypeDoc and typedoc-plugin-markdown. |

Set the generator in docs-config.json (e.g., "generator": "typedoc") or via --generator on the CLI. Additional stacks (Python/Sphinx, Rust/mdBook, etc.) can plug in without changing the shared workflow—just ship a new generator package and register it.

6. Where your docs live

| Location | When it updates | What it contains | | --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | basePath/ (workspace) | After npx algo-docs build locally or in CI | Working copy of guides (at basePath/guides) and API markdown (at basePath/api). Safe to inspect or serve locally. | | docs-publish/ (workspace) | After npx algo-docs stage | Filtered docs ready for publishing. Contains versioned folders (e.g., latest, v1.2.0). | | docs-dist/latest (branch) | Manual dispatches and releases | Rolling view of the most recently published docs. Release runs refresh this folder in addition to their versioned snapshot. | | docs-dist/<tag> (branch) | GitHub Release published | Immutable snapshot of the docs that correspond to that package version (e.g., v2.5.0). Useful for historic doc sets or version switchers. |

Publish targets can be adjusted by editing .github/workflows/build-docs.yml, but the defaults above cover most repos: "latest" for ongoing work, and "vX.Y.Z" for tagged releases.