zhuyadong / DocFx.Plugins.PlantUml

A DocFX plugin to render PlantUml diagrams from markdown code blocks

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

DocFx.Plugins.PlantUml

Build status

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

  1. Use nuget.exe to install to the project directory
nuget install DocFx.Plugins.PlantUml -ExcludeVersion -OutputDirectory .
  1. 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"
    ]
...

Download 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"
    },
...

Usage

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

```plantUml

Bob->Alice : hello

```

should render:

Bob->Alice : hello

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",
    },
...

Diagram syntax

see the PlantUml reference guide for more details

ezoic increase your site revenue

About

A DocFX plugin to render PlantUml diagrams from markdown code blocks

License:MIT License


Languages

Language:C# 100.0%