{"_id":"@algorandfoundation/algo-docs-sync","_rev":"6-b2c443a31b5536dd3774a25a458f5915","name":"@algorandfoundation/algo-docs-sync","dist-tags":{"latest":"1.5.0"},"versions":{"0.0.1":{"name":"@algorandfoundation/algo-docs-sync","version":"0.0.1","keywords":[],"author":"","license":"MIT","_id":"@algorandfoundation/algo-docs-sync@0.0.1","maintainers":[{"name":"bruno.martins.algorand.foundation","email":"bruno.martins@algorand.foundation"},{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},{"name":"shane-at-algo","email":"shane.mcgovern@algorand.foundation"},{"name":"hmd2v","email":"yared@679labs.com"},{"name":"joe-p","email":"joepolny@gmail.com"},{"name":"bitd13co","email":"bit@d13.co"},{"name":"krby","email":"kyle.breeding@algorand.foundation"}],"dist":{"shasum":"e01f956e6c8db02cbdaf012a6e7a7ce1f26bc0cb","tarball":"https://registry.npmjs.org/@algorandfoundation/algo-docs-sync/-/algo-docs-sync-0.0.1.tgz","fileCount":3,"integrity":"sha512-lNGqxozD/hYO9aeGjof0q0XO5b9SVSq2SOGEr49DAsc89JvJlUMRpSC91OnQFe0M7Z4sKRn56HsIGd2kzEY7/g==","signatures":[{"sig":"MEUCIA9qSkflyLWq4p0Tlp5GFG7ree+QGwEmV+Oau44a3oVzAiEAnXA96YWpjAnHE5CxCIBej9a8yPUvNkNFUSZGlPJdJ9M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":574},"main":"index.js","type":"commonjs","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},"_npmVersion":"11.6.0","description":"Algorand documentation","directories":{},"_nodeVersion":"24.8.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/algo-docs-sync_0.0.1_1764836394724_0.3581643692103784","host":"s3://npm-registry-packages-npm-production"}},"1.4.2":{"name":"@algorandfoundation/algo-docs-sync","version":"1.4.2","license":"MIT","_id":"@algorandfoundation/algo-docs-sync@1.4.2","maintainers":[{"name":"bruno.martins.algorand.foundation","email":"bruno.martins@algorand.foundation"},{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},{"name":"shane-at-algo","email":"shane.mcgovern@algorand.foundation"},{"name":"hmd2v","email":"yared@679labs.com"},{"name":"joe-p","email":"joepolny@gmail.com"},{"name":"bitd13co","email":"bit@d13.co"},{"name":"krby","email":"kyle.breeding@algorand.foundation"}],"homepage":"https://github.com/algorandfoundation/algo-docs-sync#readme","bugs":{"url":"https://github.com/algorandfoundation/algo-docs-sync/issues"},"bin":{"algo-docs":"bin/algo-docs","build-docs":"bin/build-docs","generate-manifest":"bin/generate-manifest"},"dist":{"shasum":"b48c880dd1efb7f97d25d7f993c1ed463fe6bd3a","tarball":"https://registry.npmjs.org/@algorandfoundation/algo-docs-sync/-/algo-docs-sync-1.4.2.tgz","fileCount":94,"integrity":"sha512-G75Ezx3G/AEMldVhZdY4ZZ/GZBsy5yUd2DrgOuckt2WaKiR7PzgrlJJmJ7KkRaV1zwKZiT4PxgEDaGZZ+LoZ7w==","signatures":[{"sig":"MEUCIHl9lF5qneyjn/qD2Q2kxi6OR08dd7BEOLC5eVM+tHpAAiEA4PBUOygjQaodjXViSOpGWTRCecBVbiOSX5IkrfWZtxI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113605},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"7b0e480a76f52b7e8b5d1ea1d06c0a020a154ed8","private":false,"release":{"plugins":[["@semantic-release/commit-analyzer",{"preset":"conventionalcommits","releaseRules":[{"type":"build","release":"patch"},{"type":"chore","release":"patch"}]}],["@semantic-release/release-notes-generator",{"preset":"conventionalcommits","presetConfig":{"types":[{"type":"feat","section":"Features"},{"type":"fix","section":"Bug Fixes"},{"type":"build","hidden":false,"section":"Dependencies and Other Build Updates"}]}}],"@semantic-release/npm","@semantic-release/github"],"branches":["main"]},"scripts":{"lint":"eslint . && prettier -c ./src/**","test":"jest","build":"tsc","lint:fix":"eslint . --fix && prettier -c ./src/** --write","prepublishOnly":"npm run build && npm test","semantic-release":"semantic-release"},"_npmUser":{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},"repository":{"url":"git+https://github.com/algorandfoundation/algo-docs-sync.git","type":"git"},"_npmVersion":"10.9.4","description":"Documentation generation tools for AlgoKit TypeScript projects","directories":{},"_nodeVersion":"20.19.6","dependencies":{"ajv":"^8.0.0","ora":"^5.4.1","chalk":"^4.1.2","semver":"^7.6.0","fs-extra":"^11.0.0","commander":"^14.0.2","picomatch":"^4.0.3","ajv-formats":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","eslint":"^8.0.0","ts-jest":"^29.0.0","typedoc":"^0.28.14","prettier":"^3.6.2","typescript":"^5.0.0","@types/jest":"^30.0.0","@types/node":"^20.0.0","@types/fs-extra":"^11.0.0","@types/picomatch":"^4.0.2","semantic-release":"^23.0.6","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","typedoc-plugin-markdown":"^4.9.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","conventional-changelog-conventionalcommits":"^7.0.2"},"peerDependencies":{"typedoc":"^0.28.14","typedoc-plugin-markdown":"^4.9.0","typedoc-plugin-frontmatter":"^1.3.0"},"_npmOperationalInternal":{"tmp":"tmp/algo-docs-sync_1.4.2_1764837009336_0.38692386286976377","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"@algorandfoundation/algo-docs-sync","version":"1.5.0","license":"MIT","_id":"@algorandfoundation/algo-docs-sync@1.5.0","maintainers":[{"name":"bruno.martins.algorand.foundation","email":"bruno.martins@algorand.foundation"},{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},{"name":"shane-at-algo","email":"shane.mcgovern@algorand.foundation"},{"name":"hmd2v","email":"yared@679labs.com"},{"name":"joe-p","email":"joepolny@gmail.com"},{"name":"bitd13co","email":"bit@d13.co"},{"name":"krby","email":"kyle.breeding@algorand.foundation"}],"homepage":"https://github.com/algorandfoundation/algo-docs-sync#readme","bugs":{"url":"https://github.com/algorandfoundation/algo-docs-sync/issues"},"bin":{"algo-docs":"bin/algo-docs","build-docs":"bin/build-docs","generate-manifest":"bin/generate-manifest"},"dist":{"shasum":"ae573fc4b4159cbe2e8c03115acc19ab4d231245","tarball":"https://registry.npmjs.org/@algorandfoundation/algo-docs-sync/-/algo-docs-sync-1.5.0.tgz","fileCount":94,"integrity":"sha512-szQNbXHaLCFn5YNyHq8mwGKJZFblRmL0yKKApbdOrE1PfgCMBhc1B1gckSAgR+vKDlsgbJzQTEDWUir08CyWjg==","signatures":[{"sig":"MEYCIQDOiOvywcGYnG88pXr3XLDX0oN8lZLefn8E+kCQEgjPFQIhAJThG96alUPcQ7cgITBHeKByE3/NE5uB4za1yZbygO/n","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114933},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"dc4eefa67fef5cdfd0347fb0c8d3f4162b50e607","private":false,"release":{"plugins":[["@semantic-release/commit-analyzer",{"preset":"conventionalcommits","releaseRules":[{"type":"build","release":"patch"},{"type":"chore","release":"patch"}]}],["@semantic-release/release-notes-generator",{"preset":"conventionalcommits","presetConfig":{"types":[{"type":"feat","section":"Features"},{"type":"fix","section":"Bug Fixes"},{"type":"build","hidden":false,"section":"Dependencies and Other Build Updates"}]}}],"@semantic-release/npm","@semantic-release/github"],"branches":["main"]},"scripts":{"lint":"eslint . && prettier -c ./src/**","test":"jest","build":"tsc","lint:fix":"eslint . --fix && prettier -c ./src/** --write","prepublishOnly":"npm run build && npm test","semantic-release":"semantic-release"},"_npmUser":{"name":"dev_algorand.foundation","email":"dev+npm@algorand.foundation"},"repository":{"url":"git+https://github.com/algorandfoundation/algo-docs-sync.git","type":"git"},"_npmVersion":"10.9.4","description":"Documentation generation tools for AlgoKit TypeScript projects","directories":{},"_nodeVersion":"20.19.6","dependencies":{"ajv":"^8.0.0","ora":"^5.4.1","chalk":"^4.1.2","semver":"^7.6.0","fs-extra":"^11.0.0","commander":"^14.0.2","picomatch":"^4.0.3","ajv-formats":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","eslint":"^9.39.1","ts-jest":"^29.0.0","typedoc":"^0.28.14","prettier":"^3.6.2","typescript":"^5.0.0","@types/jest":"^30.0.0","@types/node":"^24.10.1","@types/semver":"^7.7.1","@types/fs-extra":"^11.0.0","@types/picomatch":"^4.0.2","semantic-release":"^23.0.6","typescript-eslint":"^8.0.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","typedoc-plugin-markdown":"^4.9.0","conventional-changelog-conventionalcommits":"^7.0.2"},"peerDependencies":{"typedoc":"^0.28.14","typedoc-plugin-markdown":"^4.9.0","typedoc-plugin-frontmatter":"^1.3.0"},"_npmOperationalInternal":{"tmp":"tmp/algo-docs-sync_1.5.0_1764848291265_0.4323431202226551","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-12-04T08:19:54.672Z","modified":"2026-04-08T12:47:08.289Z","0.0.1":"2025-12-04T08:19:54.862Z","1.4.2":"2025-12-04T08:30:09.471Z","1.5.0":"2025-12-04T11:38:11.419Z"},"bugs":{"url":"https://github.com/algorandfoundation/algo-docs-sync/issues"},"license":"MIT","homepage":"https://github.com/algorandfoundation/algo-docs-sync#readme","repository":{"url":"git+https://github.com/algorandfoundation/algo-docs-sync.git","type":"git"},"description":"Documentation generation tools for AlgoKit TypeScript projects","maintainers":[{"email":"bruno.martins@algorand.foundation","name":"bruno.martins.algorand.foundation"},{"email":"dev+npm@algorand.foundation","name":"dev_algorand.foundation"},{"email":"shane.mcgovern@algorand.foundation","name":"shane-at-algo"},{"email":"joepolny@gmail.com","name":"joe-p"},{"email":"bit@d13.co","name":"bitd13co"},{"email":"kyle.breeding@algorand.foundation","name":"krby"}],"readme":"# @algorandfoundation/algo-docs-sync\n\nEnd-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.\n\n---\n\n## 1. Install & authenticate\n\n1. Add the tool as a dev dependency:\n ```bash\n npm install --save-dev @algorandfoundation/algo-docs-sync\n ```\n\n---\n\n## 2. Scaffold the repo\n\nRun 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.\n\n```bash\nnpx algo-docs init --generator typedoc\n```\n\nThis command:\n\n- Drops `docs-config.json` (guide + API glob rules plus a required `generator` field) and `typedoc.json` when using the `typedoc` generator.\n- Copies `.github/workflows/build-docs.yml`, pre-wired with installation, build, manifest, and deploy steps.\n- Creates a `docs/` folder if it doesn’t exist so you can start committing guide markdown right away.\n\nCommit the generated files (`docs-config.json`, `typedoc.json`, `.github/workflows/build-docs.yml`) before moving on.\n\n---\n\n## 3. What the pipeline does\n\n`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:\n\n1. **Build** – run TypeDoc (with `typedoc-plugin-markdown`) to generate API docs at `basePath/api`.\n2. **Stage** – `npx algo-docs stage` reads from `basePath/guides` and `basePath/api`, applies include/exclude filters, and copies the results to `docs-publish/`.\n3. **Manifest** – `npx algo-docs manifest` writes `basePath/manifest.json` including repo metadata, git info, and tool versions.\n4. **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`.\n - Manual dispatches refresh only `docs-dist/latest`.\n - Release events drop the new build into `docs-dist/v` (e.g., `docs-dist/v1.3.5`) **and** also refresh `docs-dist/latest` so you always have a rolling view and versioned snapshots.\n\nDevelopers can explore the generated docs locally by opening the `basePath/` directory, while CI keeps the branch copy in sync.\n\n---\n\n## 4. Wire up GitHub Actions\n\nThe initializer drops the `build-docs.yml` workflow into the `.github.workflows/` folder.\n\nKey secrets:\n\n- `GITHUB_TOKEN` (provided automatically) – used by `peaceiris/actions-gh-pages` to push to `docs-dist`. Ensure the repo’s Workflow permissions allow write access.\n\nOnce merged into your default branch, the workflow will:\n\n- Update `docs-dist/latest` on pushes, pull requests, and manual dispatches.\n- Create `docs-dist/` when you publish a GitHub Release.\n\nYou can download the generated artifact (`docs-dist.zip`) from each run if you need to inspect the raw files.\n\n---\n\n## 5. Local commands\n\n- `npx algo-docs validate` – schema-check `docs-config.json`.\n- `npx algo-docs build` – run TypeDoc to generate API docs at `basePath/api`. Pass `--generator ` to override the `generator` value declared in `docs-config.json`.\n- `npx algo-docs stage` – copy and filter docs from `basePath/guides` and `basePath/api` to `docs-publish/`. Use `--version ` for versioned releases and `--update-latest` to also update the latest folder.\n- `npx algo-docs manifest` – write `basePath/manifest.json` with repo metadata, git info, and tool versions.\n- `npx algo-docs migrate` – update an existing `docs-config.json` to the latest schema version.\n\nThese commands respect `--config`, `--verbose`, and `--quiet` flags so you can customize paths or diagnostics when experimenting locally.\n\n---\n\n## 7. Generators\n\nThe CLI ships with a pluggable generator system:\n\n| Name | Description |\n| -------- | ---------------------------------------------------------------- |\n| `typedoc` | Builds API markdown from TypeScript entry points using TypeDoc and `typedoc-plugin-markdown`. |\n\nSet 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.\n\n---\n\n## 6. Where your docs live\n\n| Location | When it updates | What it contains |\n| --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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. |\n| `docs-publish/` (workspace) | After `npx algo-docs stage` | Filtered docs ready for publishing. Contains versioned folders (e.g., `latest`, `v1.2.0`). |\n| `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. |\n| `docs-dist/` (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. |\n\nPublish 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.\n","readmeFilename":"README.md"}