# @effect/docgen > An opinionated documentation generator for Effect projects Latest version **0.5.2** (published 2024-12-30) · MIT license · 0 weekly downloads ## Install ```sh npm install @effect/docgen pnpm add @effect/docgen yarn add @effect/docgen bun add @effect/docgen ``` Provides the command `docgen`. ## Health **Score 40/100 (D)** — status: stable. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; large bundle; pre 1.0. Negative: stale. ## Facts | | | |---|---| | Version | 0.5.2 | | Published | 2024-12-30 | | First published | 2023-05-30 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=18.0.0 | | Dependencies | 4 | | Unpacked size | 13.2 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 52 | | Author | Giulio Canti | | Maintainers | schickling, michael.arnaldi, effect-bot | ## Links - npm: https://www.npmjs.com/package/@effect/docgen - Repository: https://github.com/effect-ts/docgen - Issues: https://github.com/effect-ts/docgen/issues - npm.io page: https://npm.io/package/@effect/docgen ## Dependencies (4) - [glob](https://npm.io/package/glob.md) ^10.3.12 - [doctrine](https://npm.io/package/doctrine.md) ^3.0.0 - [prettier](https://npm.io/package/prettier.md) ^3.2.5 - [@effect/markdown-toc](https://npm.io/package/@effect/markdown-toc.md) ^0.1.0 ## Recent versions - 0.5.2 (latest) — 2024-12-30 - 4.0.0-rc.115 (rc) — 2026-09-11 - 4.0.0-beta.107 (beta) — 2026-08-10 - 4.0.0-rc.114 — 2026-09-11 - 4.0.0-rc.113 — 2026-09-10 - 4.0.0-rc.112 — 2026-08-25 - 4.0.0-rc.111 — 2026-08-20 - 4.0.0-rc.110 — 2026-08-17 - 4.0.0-rc.109 — 2026-08-14 - 4.0.0-rc.108 — 2026-08-12 - 4.0.0-beta.106 — 2026-08-08 - 4.0.0-beta.105 — 2026-08-07 - 4.0.0-beta.104 — 2026-08-06 - 4.0.0-beta.103 — 2026-08-04 - 4.0.0-beta.102 — 2026-07-27 - … 33 more at https://npm.io/package/@effect/docgen/versions ## README An opinionated documentation generator for Effect projects. # Credits This library was inspired by the following projects: - [docs-ts](https://github.com/gcanti/docs-ts) # Setup 1. Install `@effect/docgen` as a dev dependency: ```shell pnpm add @effect/docgen -D ``` 2. (Optional) Add a `docgen.json` configuration file. ```json { "$schema": "node_modules/@effect/docgen/schema.json" } ``` 3. Add the following script to your `package.json` file: ```json { "scripts": { "docgen": "docgen" } } ``` > [!WARNING] > To use "@effect/docgen", Node.js v18 or above is required. ## Example Configuration The `docgen.json` configuration file allows you to customize `docgen`'s behavior. Here's an example configuration: ```json { "exclude": ["src/internal/**/*.ts"], "parseCompilerOptions": { "noEmit": true, "strict": true, "skipLibCheck": true, "moduleResolution": "Bundler", "target": "ES2022", "lib": ["ES2022", "DOM"], "paths": { "@effect/": ["./src/index.js"], "@effect//test/*": ["./test/*.js"], "@effect//examples/*": ["./examples/*.js"], "@effect//*": ["./src/*.js"] } }, "examplesCompilerOptions": { "noEmit": true, "strict": true, "skipLibCheck": true, "moduleResolution": "Bundler", "target": "ES2022", "lib": ["ES2022", "DOM"], "paths": { "@effect/": ["../../src/index.js"], "@effect//test/*": ["../../test/*.js"], "@effect//examples/*": ["../../examples/*.js"], "@effect//*": ["../../src/*.js"] } } } ``` # Supported JSDoc Tags | Tag | Description | Default | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `@category` | Groups associated module exports together in the generated documentation. | `'utils'` | | `@example` | Allows usage examples to be provided for your source code. All examples are type checked using `ts-node`. Examples are also run using `ts-node` and the NodeJS [assert](https://nodejs.org/api/assert.html) module can be used for on-the-fly testing. | | | `@since` | Allows for documenting most recent library version in which a given piece of source code was updated. | | | `@deprecated` | Marks source code as deprecated, which will ~~strikethrough~~ the name of the annotated module or function in the generated documentation. | `false` | | `@internal` | Prevents `docgen` from generating documentation for the annotated block of code. Additionally, if the `stripInternal` flag is set to `true` in `tsconfig.json`, TypeScript will not emit declarations for the annotated code. | | | `@ignore` | Prevents `docgen` from generating documentation for the annotated block of code. | | By default, `docgen` will search for files in the `src` directory and will output generated files into a `docs` directory. For information on how to configure `docgen`, see the [Configuration](#configuration) section below. # Configuration `docgen` is meant to be a zero-configuration command-line tool by default. However, there are several configuration settings that can be specified for `docgen`. To customize the configuration of `docgen`, create a `docgen.json` file in the root directory of your project and indicate the custom configuration parameters that the tool should use when generating documentation. The `docgen.json` configuration file adheres to the following interface: ```ts interface Config { readonly projectHomepage?: string; readonly srcDir?: string; readonly outDir?: string; readonly theme?: string; readonly enableSearch?: boolean; readonly enforceDescriptions?: boolean; readonly enforceExamples?: boolean; readonly enforceVersion?: boolean; readonly exclude?: ReadonlyArray; readonly parseCompilerOptions?: string | Record; readonly examplesCompilerOptions?: string | Record; } ``` The following table describes each configuration parameter, its purpose, and its default value. | Parameter | Description | Default Value | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | | projectHomepage | Will link to the project homepage from the [Auxiliary Links](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/#auxiliary-links) of the generated documentation. | `homepage` in `package.json` | | srcDir | The directory in which `docgen` will search for TypeScript files to parse. | `'src'` | | outDir | The directory to which `docgen` will generate its output markdown documents. | `'docs'` | | theme | The theme that `docgen` will specify should be used for GitHub Docs in the generated `_config.yml` file. | `'mikearnaldi/just-the-docs'` | | enableSearch | Whether or not search should be enabled for GitHub Docs in the generated `_config.yml` file. | `true` | | enforceDescriptions | Whether or not descriptions for each module export should be required. | `false` | | enforceExamples | Whether or not `@example` tags for each module export should be required. (**Note**: examples will not be enforced in module documentation) | `false` | | enforceVersion | Whether or not `@since` tags for each module export should be required. | `true` | | exclude | An array of glob strings specifying files that should be excluded from the documentation. | `[]` | | parseCompilerOptions | tsconfig for parsing options (or path to a tsconfig) | {} | | examplesCompilerOptions | tsconfig for the examples options (or path to a tsconfig) | {} | # FAQ **Q:** For functions that have overloaded definitions, is it possible to document each overload separately? **A:** No, `docgen` will use the documentation provided for the first overload of a function in its generated output. # License The MIT License (MIT) --- _Source: https://npm.io/package/@effect/docgen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._