plantuml_markdown

Markdown extension for PlantUML

To install, run nikola plugin -i plantuml_markdown

This plugin renders PlantUML in Markdown files.

Requirements

  • Python >= 3.6 (we use markdown>=3.3.0 which requires it)

Usage

Diagrams are rendered as inline SVGs.

A code listing can be rendered at either side of the diagram or on its own.

SVG diagram
-----------

```plantuml
A -> B : foo
```

Diagram with listing on the left
--------------------------------

```{ .plantuml listing+svg }
A -> B : foo
```

Diagram with listing on the right
---------------------------------

```{ .plantuml svg+listing }
A -> B : foo
```

Just the listing
----------------

```{ .plantuml listing }
A -> B : foo
```

All fenced code options are available e.g.

HTML IDs (for top level div & each listing line)
------------------------------------------------

```{ .plantuml svg+listing #my_id }
A -> B : foo
```

Line Numbering
--------------

```{ .plantuml listing #my_id linenos=true }
A -> B : foo
```

Line Highlighting
-----------------
```{ .plantuml listing hl_lines="1 2" }
A -> B : foo
B -> A : bar
A -> B : baz
```

A common prefix can be specified for all subsequent diagrams in a page. The most common use for this is probably page specific theming. e.g.

```plantuml-prefix
' This block specifies the "prefix" and does not render as HTML
skinparam ArrowFontName Courier
skinparam ArrowFontColor Red
```

```plantuml
A -> B : This arrow uses red Courier font
```

```plantuml
A -> B : So does this one
```

The prefix can be changed and following diagrams will use the new (possibly empty) prefix:

```plantuml-prefix
```

```plantuml
A -> B : This arrow uses the default style
```

Known Issues

  • Code listings do not have pretty syntax highlighting because there is no Pygments Lexer for PlantUML.

Suggested Configuration:

#
# IMPORTANT
#
# You also need to configure the "plantuml" plugin.
#
# When editing pages it will help to set "PLANTUML_CONTINUE_AFTER_FAILURE=True"
# so PlantUML errors will be shown in the output HTML.
#

#
# PLANTUML_MARKDOWN_ARGS (list of strings) - CLI arguments that are sent to PlantUML when rendering for markdown files,
# see https://plantuml.com/command-line
#
# Note this is independent of PLANTUML_ARGS in the "plantuml" plugin.
# If you want them to be the same then do "PLANTUML_ARGS = PLANTUML_MARKDOWN_ARGS = [ ... ]"
#
# Examples
# --------
# Use a common style file for all diagrams:
#   [ '-Imy_plantuml_style.iuml' ]
#
# Specify the style in conf.py
#   [ '-chide footbox', '-SShadowing=false' ]
#
PLANTUML_MARKDOWN_ARGS = []

Requirements:

  • Markdown>=3.3.0 (Python package)
  • plantuml (Nikola plugin)

Issues? Questions?

You can report issues with this plugin and request help via GitHub Issues.