Skip to content

ci(docs): bundle TypeDoc into Antora docs, drop GitHub Pages and Vercel - #186

Merged
johnymontana merged 3 commits into
mainfrom
fix-actions
Sep 10, 2026
Merged

ci(docs): bundle TypeDoc into Antora docs, drop GitHub Pages and Vercel#186
johnymontana merged 3 commits into
mainfrom
fix-actions

Conversation

@johnymontana

Copy link
Copy Markdown
Collaborator

Why

The docs-typedoc.yml workflow was failing on every run: it deployed the
TypeDoc API reference to GitHub Pages, but Pages is not enabled for this repo
(configure-pages → 404). Separately, the Vercel project that served the
Antora docs has been removed, leaving docs/vercel.json and related docs
stale. 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.json now outputs to
    docs/modules/ROOT/attachments/api/typescript/. Antora publishes the
    attachments/ family verbatim, so the API reference travels with the rest
    of the docs through the labs-pages build — no separate hosting.
  • The generated output (138 files, ~2.1MB) is committed and no longer
    gitignored (removed the stale typescript/docs-api/ entry).
  • docs-typedoc.yml rewritten: on pushes to main touching
    typescript/src** it regenerates the TypeDoc, commits the result to main
    as github-actions[bot] (only when output changed), and dispatches the
    labs-pages rebuild directly — the explicit dispatch is required because
    pushes made with GITHUB_TOKEN do not trigger trigger-labs-build.yml.
    Reuses the existing LABS_PAGES_TOKEN secret. The typescript-v* tag
    trigger was dropped (the workflow must commit to main; release version
    bumps touch typescript/package.json on main and trigger it anyway).

Link fixes

  • reference/typescript-api.adoc and sdks/typescript.adoc now link via
    {attachmentsdir}/api/typescript/... instead of neo4j-labs.github.io.
    The old deep links were doubly broken: Pages aside, TypeDoc emits
    module-prefixed filenames (classes/index.MemoryClient.html, not
    classes/MemoryClient.html). Every link is verified against the actual
    generated files in a full local Antora build.
  • typescript/README.md and CHANGELOG.md now point at
    neo4j.com/labs/agent-memory/reference/typescript-api.

Vercel removal

  • Deleted docs/vercel.json. There were no Vercel deploy workflows — the
    deploy ran through the (already disconnected) Vercel Git integration. The
    vercel-ai jobs in ci-typescript.yml / publish-nams-ai-provider.yml
    are the Vercel AI SDK provider package, not deployment, and are
    untouched.
  • Updated stale references: CLAUDE.md deployment section now describes the
    labs-pages flow; CONTRIBUTING.md workflow table updated.

Verification

  • npm run docs:api generates into the attachments dir cleanly
    (0 errors, 11 pre-existing warnings).
  • Full Antora build publishes _attachments/api/typescript/ and all rendered
    links resolve to real files.
  • make test-docs-links test-docs-build: 17/17 passed.

Notes for reviewers

  • The workflow commits generated HTML to main. This is inherent to the
    approach: 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 rebuild dispatch depends on the existing LABS_PAGES_TOKEN secret
    (same dependency as trigger-labs-build.yml).

@prakriti-solankey prakriti-solankey left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@johnymontana
johnymontana merged commit a4284b7 into main Sep 10, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants