https://github.com/ferdodo/typedoc-plugin-include-example
Typedoc plugin to include files as example
https://github.com/ferdodo/typedoc-plugin-include-example
example plugin typedoc typedoc-plugin
Last synced: 10 months ago
JSON representation
Typedoc plugin to include files as example
- Host: GitHub
- URL: https://github.com/ferdodo/typedoc-plugin-include-example
- Owner: ferdodo
- License: mit
- Created: 2023-09-07T07:04:18.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-02-17T01:02:38.000Z (11 months ago)
- Last Synced: 2025-03-20T20:17:42.056Z (10 months ago)
- Topics: example, plugin, typedoc, typedoc-plugin
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/typedoc-plugin-include-example
- Size: 452 KB
- Stars: 4
- Watchers: 1
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/typedoc-plugin-include-example)
[](https://www.npmjs.com/package/typedoc-plugin-include-example)
[](https://github.com/ferdodo/typedoc-plugin-include-example)
[](https://bundlephobia.com/package/typedoc-plugin-include-example)
[](https://ferdodo.github.io/typedoc-plugin-include-example/reports/mutation/mutation.html)
[](https://ferdodo.github.io/typedoc-plugin-include-example/)
Include code examples in your [typedoc](https://typedoc.org/) documentations.
### Installation
```bash
$ npm install --save-dev typedoc-plugin-include-example
```
### Usage
Write your example in a file.
```javascript
import { greet } from "./greet.js"
greet();
```
Add the @includeExample tag with the example path.
```javascript
/**
* @includeExample src/greet.example.js
*/
export function greet() {
console.log("Hello there.")
}
```
Then generate your documentation using typedoc.
```bash
$ npx typedoc --plugin typedoc-plugin-include-example
```
### Why including examples ?
Demonstrating how to use with examples has always been an essential part of making documentations accessible for newcomers. This plugin provides a conventionnal way of defining examples within your whole documentation.
Files as example never get out of date. If you're using type checking or other tools for code validation, example will need to be updated to follow the project evolutions.
### Best practice
I recommend to include a whole file for each example, not specific lines, because line numbers can quickly get out of date. In the future I'll make the file path optionnal, making the convention `./.example.` the default for example file paths.
### Features
- Selecting specific lines.
- Selecting line ranges.
- Using multiple selections.
See the [Documentation](./docs.md) for full usage.
### Links
- [Typedoc](https://typedoc.org/)'s website.
- [Package](https://www.npmjs.com/package/typedoc-plugin-include-example) on Npm.
- [Demonsration](https://ferdodo.github.io/typedoc-plugin-include-example/) of what examples looks like.
- [Documentation](./docs.md) detailling specific features.
- [Coverage testing](https://ferdodo.github.io/typedoc-plugin-include-example/reports/mutation/mutation.html) report to visualise unit testing efficiency.