ci(docs): bundle TypeDoc into Antora docs, drop GitHub Pages and Vercel - #186
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The
docs-typedoc.ymlworkflow was failing on every run: it deployed theTypeDoc API reference to GitHub Pages, but Pages is not enabled for this repo
(
configure-pages→ 404). Separately, the Vercel project that served theAntora docs has been removed, leaving
docs/vercel.jsonand related docsstale. The docs site is published by the neo4j-contrib/labs-pages build,
which consumes this repo's committed Antora component.
What changed
TypeDoc ships inside the Antora component
typescript/typedoc.jsonnow outputs todocs/modules/ROOT/attachments/api/typescript/. Antora publishes theattachments/family verbatim, so the API reference travels with the restof the docs through the labs-pages build — no separate hosting.
gitignored (removed the stale
typescript/docs-api/entry).docs-typedoc.ymlrewritten: on pushes tomaintouchingtypescript/src**it regenerates the TypeDoc, commits the result tomainas
github-actions[bot](only when output changed), and dispatches thelabs-pages rebuild directly — the explicit dispatch is required because
pushes made with
GITHUB_TOKENdo not triggertrigger-labs-build.yml.Reuses the existing
LABS_PAGES_TOKENsecret. Thetypescript-v*tagtrigger was dropped (the workflow must commit to
main; release versionbumps touch
typescript/package.jsononmainand trigger it anyway).Link fixes
reference/typescript-api.adocandsdks/typescript.adocnow link via{attachmentsdir}/api/typescript/...instead ofneo4j-labs.github.io.The old deep links were doubly broken: Pages aside, TypeDoc emits
module-prefixed filenames (
classes/index.MemoryClient.html, notclasses/MemoryClient.html). Every link is verified against the actualgenerated files in a full local Antora build.
typescript/README.mdandCHANGELOG.mdnow point atneo4j.com/labs/agent-memory/reference/typescript-api.Vercel removal
docs/vercel.json. There were no Vercel deploy workflows — thedeploy ran through the (already disconnected) Vercel Git integration. The
vercel-aijobs inci-typescript.yml/publish-nams-ai-provider.ymlare the Vercel AI SDK provider package, not deployment, and are
untouched.
CLAUDE.mddeployment section now describes thelabs-pages flow;
CONTRIBUTING.mdworkflow table updated.Verification
npm run docs:apigenerates into the attachments dir cleanly(0 errors, 11 pre-existing warnings).
_attachments/api/typescript/and all renderedlinks resolve to real files.
make test-docs-links test-docs-build: 17/17 passed.Notes for reviewers
main. This is inherent to theapproach: labs-pages reads the committed git tree, so generated output must
live in it. Expect a bot commit after merges that touch
typescript/src/**.LABS_PAGES_TOKENsecret(same dependency as
trigger-labs-build.yml).