# typedoc-plugin-external-module-name

> Specify the Typedoc Module of a file using @module annotation

Latest version **4.0.6** (published 2021-01-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install typedoc-plugin-external-module-name
pnpm add typedoc-plugin-external-module-name
yarn add typedoc-plugin-external-module-name
bun add typedoc-plugin-external-module-name
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.6 |
| Published | 2021-01-04 |
| First published | 2016-07-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 52.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 79 |
| Author | Chris Thielen |
| Maintainers | christopherthielen |
| Keywords | typedocplugin, typedoc |

## Links

- npm: https://www.npmjs.com/package/typedoc-plugin-external-module-name
- Repository: https://github.com/christopherthielen/typedoc-plugin-external-module-name
- Homepage: https://github.com/christopherthielen/typedoc-plugin-external-module-name#readme
- Issues: https://github.com/christopherthielen/typedoc-plugin-external-module-name/issues
- npm.io page: https://npm.io/package/typedoc-plugin-external-module-name

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) ^4.1.2
- [semver](https://npm.io/package/semver.md) ^7.1.1

## Recent versions

- 4.0.6 (latest) — 2021-01-04
- 4.0.5 — 2020-12-20
- 4.0.4 — 2020-12-17
- 4.0.3 — 2020-06-06
- 4.0.2 — 2020-06-06
- 4.0.1 — 2020-06-05
- 4.0.0 — 2020-05-31
- 3.1.0 — 2020-04-27
- 3.0.0 — 2020-01-16
- 2.2.1 — 2020-01-15
- 2.2.0 — 2020-01-15
- 2.1.0 — 2019-05-06
- 2.0.0 — 2019-01-10
- 1.1.3 — 2018-07-21
- 1.1.1 — 2018-02-07
- … 10 more at https://npm.io/package/typedoc-plugin-external-module-name/versions

## README

# typedoc-plugin-external-module-name

<img src="https://api.travis-ci.org/christopherthielen/typedoc-plugin-external-module-name.svg?branch=master">

## What

A [Typedoc](http://typedoc.org) plugin which allows code documentation to be organized into custom Modules.

_Note: In Typedoc 0.17.0 and above, Module refers to an ES6 Module._
_In Typedoc 0.16.x and below, an ES6 Module was called an [External Module](https://github.com/TypeStrong/TypeDoc/issues/109)._
_Although the plugin's name includes "External Module", it modifies Modules (ES6 Modules)_

By default, Typedoc creates a Module for each ES6 Module (each file).

This plugin allows documentation to be moved to arbitrary modules.
It also supports merging multiple modules into a single module.
By default, all Modules in a given directory will be merged into a single module.

Suppose your source files are organized like this:

```
thing1/foo.ts
thing1/bar.ts
thing2/baz.ts
thing2/qux.ts
```

By default, Typedoc would create four Modules:

- `thing1/foo`: contains `foo` documentation
- `thing1/bar`: contains `bar` documentation
- `thing2/baz`: contains `baz` documentation
- `thing2/qux`: contains `qux` documentation

With this plugin, Typedoc creates two Modules:

- `thing1`: contains `foo` and `bar` documentation
- `thing2`: contains `baz` and `qux` documentation

## Installing

Typedoc has the ability to discover and load typedoc plugins found in node_modules.
Simply install the package usng your package manager and run typedoc.

```
npm install -D typedoc-plugin-external-module-name
typedoc
```

## Using

### Directory Based

This plugin will combine documentation from the files in each given directory into a new Module.
The new module name is generated from the directory's location in the source tree.

### Explicit via Annotation

You can explicitly specify a Module name using the `@module` annotation.
Add a comment block at the top of a Typescript file with `@module modulename`.
Mark the comment block as `@packageDocumentation` to let typedoc know that this is documentation for the file (Module) itself
(see: [Typedoc Docs](https://typedoc.org/guides/doccomments/#files)).

```js
/**
 * @packageDocumentation
 * @module module1
 */
```

### Top level module comments

When multiple modules are merged, the merged module summary is chosen arbitrarily from the first file processed.
To use a specific file's comment block as the Module page summary, use `@preferred`.

```js
/**
 * This comment will be used as the summary for the "thing2" module.

 * @packageDocumentation
 * @module thing2
 * @preferred
 */
```

### Custom Module Name Generation

Create a file named `.typedoc-plugin-external-module-name.js` in the folder you launch typedoc from.
Create a custom mapping function in that file and export it using CommonJS.
For each Module, the plugin will call your function and use the return value as the Module Name.

```
module.exports = function customMappingFunction() {
  return "custom" // everything goes into "custom"
}
```

The Function should have the following signature:

```
type CustomModuleNameMappingFn = (
  explicitModuleAnnotation: string,
  implicitFromDirectory: string,
  path: string,
  reflection: Reflection,
  context: Context,
) => string;

```

The arguments are:

- `moduleAnnotation`: If the module has an explicit annotation, i.e., `@module explicit`
- `implicitFromDirectory`: The plugin's default mapping
- `path`: The path to the file
- `reflection`: The Module [`ContainerReflection`](https://typedoc.org/api/classes/containerreflection.html)
- `context`: The typedoc [`Context`](https://typedoc.org/api/classes/context.html)

Example:

```
const subpackage = new RegExp("packages/([^/]+)/");
module.exports = function customMappingFunction(explicit, implicit, path, reflection, context) {
  // extract the monorepo package from the path
  const package = subpackage.match(path)[1];
  // build the module name
  return `${package}/${implicit}`;
}
```

---
_Source: https://npm.io/package/typedoc-plugin-external-module-name · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._