Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭
  • 哪里不对？
#157 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
停滞
技术栈
typescript
领域
documentation, tooling

调研方向

先阅读 packages/evolution/src、现有的 docs/scripts/ 生成流程以及 fumadocs source.config.ts。运行当前的模块文档流水线，然后评估 docs-typedoc/ 和 docs/content/docs/api/ 下的并行 TypeDoc 输出。在不修改 /docs/modules/ 的情况下通过已记录的验收标准，随后完成计划中的 UX 审计和迁移决策，即视为完成。

由索引模型根据 Issue 内容生成。

描述

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
主要语言
TypeScript
星标
22
派生
35
平均合并
23 小时 52 分钟
30 天内合并 PR
41

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

IntersectMBO/evolution-sdk 的其他 Issue

查看 IntersectMBO/evolution-sdk 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。