Skip to content

Runtime Core API index links to namespace pages that the typedoc plugin deletes #1784

Description

@joshunrau

The Runtime Core API index links to five namespace pages that the typedoc plugin deletes, so every namespace link on it is a 404. With a single entry point, typedoc-plugin-markdown writes each namespace's index as namespaces/<Name>/README.md, and the generated top-level README.md links to them. onRendererPageEnd treats any README.md below the root as a per-entry-point readme ("Do not save README.md files for multiple entry points") and removes it at the end of rendering. That branch exists for documenting several entry points, but this site documents one (runtime-core/lib/index.d.ts), so the files it deletes are the namespace pages. The FileInstrument, FormInstrument, FormTypes, InteractiveInstrument and SeriesInstrument links on https://opendatacapture.org/en/runtime-core-docs/readme/ all return 404, and so do the same five on the French fallback copy. A reader who follows the API index into any namespace hits a dead end.

Where

apps/outreach/src/plugins/starlight-plugin-typedoc/typedoc.ts:105-115:

// Returning `true` will delete the page from the filesystem.
function onRendererPageEnd(event: MarkdownPageEvent) {
  if (!event.contents) {
    return false;
  } else if (/^.+[/\\]README\.md$/.test(event.url)) {
    // Do not save `README.md` files for multiple entry points.
    ...
    return true;
  }

The links it breaks, in the generated apps/outreach/src/content/docs/en/runtime-core-docs/README.md:

## Namespaces

- [FileInstrument](/en/runtime-core-docs/namespaces/fileinstrument/readme/)
- [FormInstrument](/en/runtime-core-docs/namespaces/forminstrument/readme/)

Reproduce

  1. pnpm --filter @opendatacapture/outreach build.
  2. ls apps/outreach/src/content/docs/en/runtime-core-docs/namespaces/FormInstrument and ls apps/outreach/dist/en/runtime-core-docs/namespaces/forminstrument.
  3. Open /en/runtime-core-docs/readme/ and click any entry under "Namespaces".

Actual: each namespace directory holds only type-aliases/, the five readme/ pages are missing from dist/, and the links 404.
Expected: each namespace has an index page listing its members, and the API index links resolve.

Tests

apps/outreach has no unit or Playwright suite, by decision (apps/outreach/AGENTS.md). Verify through the build: every /en/runtime-core-docs/... href in dist/en/runtime-core-docs/readme/index.html resolves to a file under dist/.

Suggested fix

Only drop a nested README.md when the plugin is documenting several packages (entryPointStrategy === 'packages'), which this site never does. Since the plugin has exactly one configuration, the simpler change is to delete the README.md branch from onRendererPageEnd.

Activity

  1. added
    BugType: existing behavior is wrong
    Difficulty: LowIsolated change, about 2 hours or less
    Area: Outreachapps/outreach and docs/ (marketing site and user documentation)
    on Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Area: Outreachapps/outreach and docs/ (marketing site and user documentation)BugType: existing behavior is wrongDifficulty: LowIsolated change, about 2 hours or lessPriority: MediumReal value; schedule normally

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions