IntersectMBO / IntersectMBO/evolution-sdk

experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs

Open
#157 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
TypeScript
Stars
22
Forks
30
Avg merge
5h 29m
Merged PRs (30d)
12

Description

## Context

The current module reference docs are generated by \`@effect/docgen@0.5.2\` using the \`mikearnaldi/docgen-template\` theme. Output is static MDX with signatures and JSDoc text — no clickable type cross-references, no source links to GitHub.

The goal is Haddock-style behaviour: every type name in a signature is a link that jumps to that type's own documentation page.

## Proposed Experiment

Replace \`@effect/docgen\` with **TypeDoc + \`typedoc-plugin-markdown\`** on an isolated output path so both pipelines can run side-by-side without breaking the existing \`/docs/modules/\` route.

### What TypeDoc gives us

- Clickable cross-references for every type in every signature (uses the TypeScript compiler API to resolve them)
- Source links to GitHub out of the box via \`sourceLinkTemplate\`
- Handles generics, branded types, class methods, and conditional types correctly
- \`typedoc-plugin-markdown\` emits MDX consumable by fumadocs

### Implementation plan

1. Add \`typedoc\`, \`typedoc-plugin-markdown\`, and \`typedoc-plugin-frontmatter\` as dev dependencies in \`packages/evolution\`
2. Add a \`typedoc.json\` config in \`packages/evolution\` pointed at existing \`src/\` — output to a new \`docs-typedoc/\` directory
3. Add a \`generate-typedoc-docs\` script in \`docs/scripts/\` that copies the output into \`docs/content/docs/api/\` (parallel to the existing \`modules/\` path)
4. Wire the new path into fumadocs \`source.config.ts\` under a separate \`/docs/api/\` route
5. Audit the output: verify cross-references resolve, source links point correctly, category grouping is preserved
6. Compare UX against the existing \`/docs/modules/\` output and decide whether to migrate fully or keep both

### Acceptance Criteria

- [ ] TypeDoc generates MDX without errors for all exported symbols in \`packages/evolution/src\`
- [ ] Cross-reference links (e.g. clicking \`Data.Constr\` in a TSchema signature) resolve to the correct page
- [ ] Source links open the correct line in GitHub
- [ ] The new output is accessible at \`/docs/api/\` in the docs site without affecting \`/docs/modules/\`
- [ ] Existing \`@effect/docgen\` pipeline is untouched

## Notes

- This is explicitly experimental — full migration is a separate decision pending the audit
- \`externalPattern\` exclusions for Effect library internals will likely need tuning to avoid polluting the output with Effect framework types

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.