DocFx.Plugins.PlantUml

DocFx.Plugins.PlantUml is a template for DocFx to allow DFM (DocFx MarkDown) documents to render diagrams using PlantUml

Installation Instructions

DocFx.Plugins.PlantUml uses PlantUml.Net. Ensure you have installed the requirements

Project Installation via NuGet

This method assumes you are including docfx.console.

(using package manager)

Install-Package DocFx.Plugins.PlantUml

Installing in this way will explicitly set the templates used in your project, the templates specified in docfx.json will be ignored!

To specify templates add them in a comma seperated list to the DocTemplate property in your project file.

e.g.

<PropertyGroup>
  <DocTemplate>default,my-custom-template</DocTemplate>
</PropertyGroup>

Manual Installation

Use nuget.exe to install to the project directory

nuget install DocFx.Plugins.PlantUml -ExcludeVersion -OutputDirectory .

Add to docfx.json

Now you need to tell DocFx where to find the new template...

assuming you extracted the package to the project directory:

in docfx.json:

...
    "template": [
      "default",
      "DocFx.Plugins.PlantUml/template"
    ]
...

Usage

To render a PlantUml diagram add a code block to you markup:

```plantUml

Bob->Alice : hello

```

should render:

Settings

The plugin can be configured in your docfx.json the following options are available:

Setting	Description	Default
plantUml.javaPath	path to java installation	uses the JAVA_HOME environment variable
plantUml.localGraphvizDotPath	path to graphviz dot exe (required for local rendering mode only)	none
plantUml.localPlantUmlPath	path to plantuml.jar	will look in project directory
plantUml.outputFormat	format of generated images (svg, ascii, ascii_unicode)	svg
plantUml.remoteUrl	url to remote PlantUml server (required for remote rendering mode only)	http://www.plantuml.com/plantuml/
plantUml.renderingMode	remote or local	remote

example:

...
    "markdownEngineProperties": {
      "plantUml.javaPath": "C:/Program Files/Java/jre1.8.0_171",
      "plantUml.localGraphvizDotPath": "C:/Program Files (x86)/Graphviz2.38/bin/dot.exe",
      "plantUml.localPlantUmlPath": "plantuml.jar",
      "plantUml.outputFormat":"png",
      "plantUml.remoteUrl":"http://www.plantuml.com/plantuml/",
      "plantUml.renderingMode":"remote"
    },
...

Local Rendering

By default, PlantUML documents will be rendered on the remote server. Local rendering mode uses a local copy of PlantUml to render diagrams.

Local rendering mode can be configured in in your docfx.json:

...
    "markdownEngineProperties": {
      "plantUml.renderingMode":"local"
    },
...

Requirements

Java

Install Java. Ensure that the JAVA_HOME environment variable is set.

PlantUml

Download PlantUml (pick whichever licence suits your needs), the .jar can be placed directly into the project root, or an alternate configuration can be specified in your docfx.json:

...
    "markdownEngineProperties": {
      "plantUml.localPlantUmlPath": "path/to/plantuml.jar"
    },
...

GraphViz Dot (optional)

GraphViz Dot is required for Local rendering mode of any diagram other than sequence.

Install GraphViz Dot You may need to set the GRAPHVIZ_DOT environment variable

see the PlantUml documentation for more detailed instructions.

Diagram syntax

see the PlantUml reference guide for more details

rkl1976 / docfx.plugins.plantuml Goto Github PK