add support for diagrams

Author: sneakers-the-rat

README.md

@@ -65,6 +65,11 @@ listed in `Dockerfile` should be installed.
 
 You will also need the [Hack](https://github.com/source-foundry/Hack) font by `source-foundry`.
 
+To render diagrams you will need to have installed the relevant diagram library:
+
+- mermaid: `npm install -g @mermaid-js/mermaid-cli`
+- graphviz: ([consult docs](https://graphviz.org/download/))
+
 ## Versions
 
 Inara is versioned using [SemVer](https://semver.org). Docker

data/defaults/shared.yaml

@@ -8,6 +8,13 @@ metadata:
   # cannot be overwritten in the paper YAML.
   lang: 'en-US'
 
+  engine:
+    dot: true
+    plantuml: false
+    asymptote: false
+    mermaid: true
+    tikz: false
+
 resource-path:
   - '/usr/local/share/openjournals'
   - '.'
@@ -25,6 +32,10 @@ filters:
     path: time.lua
   - type: lua
     path: normalize-author-names.lua
+  - type: lua
+    path: substitute-in-format.lua
+  - type: lua
+    path: diagram.lua
 
 # ERROR, WARNING, or INFO
 verbosity: INFO

data/filters/diagram.lua

@@ -0,0 +1 @@
+../../vendor/diagram-1.0.0/_extensions/diagram/diagram.lua

example/paper.md

@@ -279,6 +279,120 @@ Rendered:
    gained as heat, $Q$, less the thermodynamic work, $W$, done by the
    system on its surroundings. $$\Delta U = Q - W$$
 
+### Code examples
+
+Code examples can be written in fenced code blocks and highlighted with the provided language. 
+
+For example:
+
+```` 
+```python
+import shutil
+
+def hello_world():
+    # shutil.rmtree('/')
+    # on second thought
+    print('hello world')
+```
+````
+
+creates:
+
+```python
+import shutil
+
+def hello_world():
+    # shutil.rmtree('/')
+    # on second thought
+    print('hello world')
+```
+
+### Diagrams
+
+Diagrams[^diagrams] can be written within fenced code blocks using:
+
+[^diagrams]: Thanks to the [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram/tree/main) pandoc filter
+
+- [`mermaid`](https://mermaid.js.org/)
+- `dot` ([graphviz](https://graphviz.org/))
+
+See the linked documentation for more information on available diagram types and syntax, particularly with mermaid which is under active development.
+
+For example, using mermaid:
+
+```` markdown
+``` mermaid
+%%| label: open_review
+%%| caption: Open Software Review: a state diagram
+stateDiagram-v2
+  direction LR
+  Ship: Ship It
+  [*] --> Code
+  Code --> Compile
+  Compile --> Bug
+  Bug --> Cry
+  Cry --> Code
+  Bug --> YOLO
+  YOLO --> Ship
+  Ship --> [*]
+```
+````
+
+Creates:
+
+``` mermaid
+%%| label: open_source
+%%| caption: Open Source: a state diagram
+stateDiagram-v2
+  direction LR
+  Ship: Ship It
+  [*] --> Code
+  Code --> Compile
+  Compile --> Bug
+  Bug --> Cry
+  Cry --> Code
+  Bug --> YOLO
+  YOLO --> Ship
+  Ship --> [*]
+```
+
+Similarly, with dot/graphviz:
+
+````markdown
+``` dot
+digraph {
+  rankdir=LR
+  submit -> read
+  subgraph cluster_review {
+      label="review"
+      read -> issue
+      issue -> PR
+      PR -> read
+  }
+  read -> lgtm
+  lgtm -> thanks[label="say thanks"]
+  thanks -> friends[label="make friends!"]
+}
+```
+````
+
+Creates:
+
+``` dot
+digraph {
+  rankdir=LR
+  submit -> read
+  subgraph cluster_review {
+      label="review"
+      read -> issue
+      issue -> PR
+      PR -> read
+  }
+  read -> lgtm
+  lgtm -> thanks[label="say thanks"]
+  thanks -> friends[label="make friends!"]
+}
+```
 
 # Article metadata
 

vendor/diagram-1.0.0/.gitignore

@@ -0,0 +1,2 @@
+sample.html
+tmp-latex

vendor/diagram-1.0.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# diagram
+
+The diagram filter is versioned using [Semantic Versioning][].
+
+[Semantic Versioning]: https://semver.org/
+
+## v1.0.0
+
+Released 2023-05-22.
+
+- First release of the Lua filter; may it live long and prosper.

vendor/diagram-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright © 2019-2023 Albert Krewinkel
+Copyright © 2019 Thorsten Sommer
+Copyright © 2018 Florian Schätzig
+Copyright © 2018 John MacFarlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vendor/diagram-1.0.0/Makefile

@@ -0,0 +1,22 @@
+FILTER_FILE := $(wildcard *.lua)
+PANDOC ?= pandoc
+DIFF ?= diff
+
+.PHONY: test
+test: test-asymptote test-dot test-mermaid test-plantuml test-tikz \
+	test-no-alt-or-caption
+
+test-%: test/test-%.yaml test/input-%.md $(FILTER_FILE)
+	@$(PANDOC) --defaults test/test-$*.yaml | \
+	  $(DIFF) test/expected-$*.html -
+
+sample.html: sample.md diagram.lua
+	@$(PANDOC) --self-contained \
+	    --lua-filter=diagram.lua \
+	    --metadata=pythonPath:"python3" \
+	    --metadata=title:"README" \
+	    --output=$@ $<
+
+clean:
+	@rm -f sample.html
+	@rm -rf tmp-latex