docs: Updated docs to include PlantUML extension (#9607)

* Added PlantUML extension documentation * Remove reference to DFM flavour markdown * Revert removal of DFM reference
dotnet · Jan 13, 2024 · 6476473 · 6476473
1 parent 8851faa
commit 6476473
Showing 1 changed file with 78 additions and 1 deletion.
diff --git a/docs/docs/markdown.md b/docs/docs/markdown.md
@@ -284,6 +284,83 @@ class Class10 {
 }
 ```
 
+## PlantUML Diagrams
+
+You can embed [PlantUML](https://plantuml.com/) diagrams using markdown code blocks:
+
+Example:
+
+    ```plantuml
+    Bob -> Alice : hello
+    ```
+
+This will be rendered as:
+
+![alt-text](https://www.plantuml.com/plantuml/svg/SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80)
+
+There are plenty of other diagrams supported by PlantUML such as:
+
+* [Sequence diagram](http://plantuml.com/sequence-diagram)
+* [Use Case diagram](http://plantuml.com/use-case-diagram)
+* [Class diagram](http://plantuml.com/activity-diagram-beta)
+* [Activity diagram](http://plantuml.com/activity-diagram-beta)
+* [Component diagram](http://plantuml.com/component-diagram)
+* [State diagram](http://plantuml.com/state-diagram)
+* [Gantt diagram](https://plantuml.com/gantt-diagram)
+* [Deployment diagram](http://plantuml.com/deployment-diagram)
+* [Mindmap diagram](https://plantuml.com/mindmap-diagram)
+
+Refer to the [PlantUml reference guide](http://plantuml.com/PlantUML_Language_Reference_Guide.pdf) for more details.
+
+### Settings
+
+The PlantUML extension can be configured using the `build.markdownEngineProperties.plantUml` property of your `docfx.json` file:
+
+```json
+{
+  "build": {
+    "markdownEngineProperties": {
+      "plantUml": {
+          "outputFormat": "svg",
+          "remoteUrl": "http://www.plantuml.com/plantuml/",
+          "renderingMode": "remote"
+      }
+    }
+  }
+}
+```
+
+The following settings are available for configuration:
+
+| Setting | Description | Default |
+| ------- | ----------- | ---------|
+| `javaPath`              | path to java installation                                               | uses the JAVA_HOME environment variable |
+| `localGraphvizDotPath`  | path to graphviz dot exe (required for local rendering mode only)       | none                                    |
+| `localPlantUmlPath`     | path to plantuml.jar                                                    | will look in project directory          |
+| `outputFormat`          | format of generated images (svg, ascii, ascii_unicode)                  | svg                                     |
+| `remoteUrl`             | url to remote PlantUml server (required for remote rendering mode only) | http://www.plantuml.com/plantuml/       |
+| `renderingMode`         | remote or local                                                         | remote                            
+
+### Local Rendering
+
+By default, PlantUML diagrams will be rendered on the remote server. Local rendering mode uses a [local copy](https://plantuml.com/faq-install) of PlantUML to render diagrams.  Local rendering mode can be configured in your `docfx.json` file:
+
+```json
+{
+  "build": {
+    "markdownEngineProperties": {
+      "plantUml": {
+          "localPlantUmlPath": "path/to/plantuml.jar",
+          "renderingMode": "local"
+      }
+    }
+  }
+}
+```
+
+> [!NOTE]
+> GraphViz Dot is required for local rendering mode of any diagram other than sequence. Refer to the [PlantUML documentation](http://plantuml.com/graphviz-dot) for more detailed instructions.
+
 ## Include Markdown Files
 
 Where markdown files need to be repeated in multiple articles, you can use an include file. The includes feature replace the reference with the contents of the included file at build time.
@@ -453,4 +530,4 @@ For example:
 ```
 
 In GFM, it will be rendered as a paragraph with content `[!NOTE] This is code.` in blockquote.  
-In DFM, it will be rendered as a code in note.
+In DFM, it will be rendered as a code in note.