PlantUML Pleasantness: Create diagrams from NPM and Typedoc

What if you have created an awesome diagram with PlantUML, and you would like to include that diagram in your documentation?

In this small tutorial we can include a generated PlantUML diagram in typedoc (a way of documenting typescript packages). Note: Graphiz needs to be installed to run this diagram generation.

First install the typedoc plugin:

npm install typedoc --saveDev

Now, create a typedoc.json in the root of your project. This file describes how typedoc should generate the documentation.

{

  "emitDecoratorMetadata": true,

  "excludeExternals": true,

  "experimentalDecorators": true,

  "hideGenerator": true,

  "ignoreCompilerErrors": true,

  "includeDeclarations": false,

  "mode": "file",

  "module": "commonjs",

  "moduleResolution": "node",

  "out": "./build/docs",

  "preserveConstEnums": true,

  "stripInternal": true,

  "suppressExcessPropertyErrors": true,

  "suppressImplicitAnyIndexErrors": true,

  "target": "ES5"

}

Next install node-plantuml https://www.npmjs.com/package/node-plantuml globally. We should install this globally so we can also use the CLI as a NPM script later.

npm install -g node-plantuml

Go ahead and put the following snippet in your package.json

"scripts": {

     "docs": "typedoc --options typedoc.json ./src/ && puml generate my-diagram.puml -o build/docs/my-diagram.png"

}

Finally we are able to create typescript documentation with our generated PNG diagram. If we would include the image in our README as follows:

<a href="./my-diagram.png" target="_blank"></a>

and run the following command from the command-line:

npm run docs

Our documentation at ./build/docs our index page shows the README with our generated diagram.