diff options
author | Ivan Dolgov <ivan@qvarnlabs.com> | 2017-09-14 16:16:34 +0300 |
---|---|---|
committer | Ivan Dolgov <ivan@qvarnlabs.com> | 2017-09-14 16:16:34 +0300 |
commit | d21718d9911500105ea7b43f03ef19fbb11faf6f (patch) | |
tree | e47fefe931d77642026ad46380720d965cca9230 | |
parent | ea9e776e50ed805c33327c067a0e99c6f92e4f03 (diff) | |
download | ql-ikiwiki-publish-d21718d9911500105ea7b43f03ef19fbb11faf6f.tar.gz |
Add PlantUML support design doc
-rw-r--r-- | docs/plantuml.mdwn | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/docs/plantuml.mdwn b/docs/plantuml.mdwn new file mode 100644 index 0000000..c8d2bca --- /dev/null +++ b/docs/plantuml.mdwn @@ -0,0 +1,80 @@ +# PlantUML support + +PlantUML is a tool for generating UML (and some non-UML) diagrams from plain text +descriptions. Instead of creating and linking diagram images in Ikiwiki Markdown +files, embedded PlantUML source code is a more handy and git-friendly solution. + +The best way to implement this feature would of course be a PlantUML plugin for +Ikiwiki, but since we are much more comfortable with Python than Ruby we are +addind it to `ql-ikiwiki-publish`. + +## Implementation + +The idea is to detect diagram code included in wiki pages and replace it with a +link to a generated diagram image. + +It is also useful to be able to include external UML files instead of embedding +code directly into wiki pages. This way we can easily preview the diagrams +before committing. + +So basically what `ql-ikiwiki-publish` will be doing is as follows: + +1. Recognize relevant diagram code. + +2. Copy it into a temporary file. + +3. Generate a diagram image by running `plantuml` with the temp file as an + argument. + +4. Copy the diagram image into Ikiwiki output directory. + +5. Replace embedded diagram code or diagram file include statement with a `img` + directive containing a path or link to the diagram image. + +### Code block syntax + +In case of directly embedded diagram code, the most sensibe syntax seems to be +PlantUML within Markdown code block, which would look like this: + +[[!format md """ +``` +@startuml +Alice -> Bob: Hello +Bob -> Alice: Hello +@enduml +``` +"""]] + +Or like this: + +[[!format md """ + @startuml + Alice -> Bob: Hello + Bob -> Alice: Hello + @enduml +"""]] + +In case when raw PlantUML code needs to be shown instead of an image, `format` +directive syntax can be used to prevent the code from being replaced by +`ql-ikiwiki-publish`: + +``` +[[!format md """ +@startuml +Alice -> Bob: Hello +Bob -> Alice: Hello +@enduml +"""]] +``` + +### External file syntax + +In order to include an external diagram code file, we need a custom syntax only +recognizable by `ql-ikiwiki-publish` but preferably ignored by other Markdown +parsers. This can be achieved by using HTML comment syntax: + +[[!format html """ +<!-- INCLUDE_UML: some_file.puml --> +"""]] + +Pandoc-style triple dash can be also used to make it even more parser-friendly. |