blob: c8d2bca6ac806aa01e12b9ba3653821c45ab1c41 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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.
|
