Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#157 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Stale
Tech stack
typescript
Domain
documentation, tooling

Research direction

Start by reading packages/evolution/src, the existing docs/scripts/ generation flow, and fumadocs source.config.ts. Run the current module-doc pipeline, then evaluate a parallel TypeDoc output under docs-typedoc/ and docs/content/docs/api/. Done means the documented acceptance criteria pass without changing /docs/modules/, followed by the planned UX audit and migration decision.

Written by the indexing model from the issue text.

Description

documentation enhancement

Context

The current module reference docs are generated by `@effect/[email protected]` 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
Dominant language
TypeScript
Stars
22
Forks
31
Avg merge
3d 4h
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from IntersectMBO/evolution-sdk

All issues in IntersectMBO/evolution-sdk

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.