In depth user guide

[veenone]

Hi,

I'm interested to use this filter for my purpose. However I still haven't been able to make it work especially for PlantUML and mermaid (as I'm a beginner with pandoc)..

My need is to generate my markdown files which has both PlantUML and mermaid chart.

Can you provide me working example for both? At least to make these charts properly generated in both PDF and HTML format

I also have confusion in setting up the jar file of PlantUML and the executable for mermaid.

I think this ticket is similar to issue #28

Thank you!

[tarleb]

Checkout the test folder for working examples.

Please also checkout Quarto, which has Mermaid support built-in. But you'll still need this filter for PlantUML. You can find examples for using this filter with Quarto by searching the closed issues of this repository.

We can't help with general setup questions, sorry.

[tarleb]

A better user guide would still be great, of course, so I'll leave this open. Any help with this would be appreciated.

[veenone]

thanks for your information @tarleb
I'll check Quarto out to as the mermaid generator alternative
maybe I could make some contribution on this userguide part later on

[tarleb]

Oh, I understand now why PlantUML is more difficult to setup. I've pushed a new commit that should make it easier. You can now use:

diagram:
  engine:
    plantuml:
      execpath: ['java', '-jar', 'path/to/plantuml.jar']

[veenone]

Hi @tarleb ,

Thank you for your update, I have checked the latest change on the execpath but I'm still unable to generate the file, with the following warning :

[WARNING] Scripting warning at diagram.lua line 523 column 1: diagram.lua: plantuml: createProcess: does not exist (No such file or directory)

btw for your information, here's my configuration :

7-chart.md

# chart example
## mermaid

### sequence diagram
```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob, how are you ?
    Bob->>Alice: Fine, thank you. And you?
    create participant Carl
    Alice->>Carl: Hi Carl!
    create actor D as Donald
    Carl->>D: Hi!
    destroy Carl
    Alice-xCarl: We are too many
    destroy Bob
    Bob->>Alice: I agree
```


## plantUML
### sequence

```plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

```

this is my metadata.yml

---
title: "Template Doc"
title-prefix: "User Manual"
subtitle: "User Manual"
author: [AuthorName]
date: ""
subject: "Markdown"
keywords: [Markdown, Example]
lang: "en"
titlepage: true
titlepage-text-color: "430099"
titlepage-rule-color: "430099"
titlepage-rule-height: 2
toc-own-page: true
diagram:
  engine:
    plantuml:
      execpath: ['java', '-jar', 'c:/tools/plantuml.jar']
      mime-type:
        application/pdf: false
        image/png: true
...

and this is how I call the pandoc :

pandoc \
        metadata.yml \
        7-chart.md  \
        --output manual.pdf \
        --template tool/template/eisvogel1.tex \
        --from markdown \
        --listings \
        --number-sections \
        --table-of-contents \
        --lua-filter=diagram.lua \
        --metadata date="2024-09-29"

I know there's something incorrect in my configuration however I'm kinda lost here...
do you know what should be fixed?

btw I also already installed quatro for mermaid generation but it also doesn't work.

[tarleb]

Can you update to the latest development version once more? Line 523, which is mentioned in the error message that you're seeing, is an empty line in the current dev version.

Your setup looks fine to me, so if the version in the main branch doesn't work, then there might be a bug somewhere.

[tarleb]

To use Mermaid with Quarto use

``` {mermaid}
...
```

Note the curly braces.

[veenone]

Hi @tarleb ,

thank you for pointing out the possibility of the impact from the latest change on the filter file.
I clone the latest repo and made a comparison with the one in my environment.
in fact the changes that I saw is the additions on cetz engine.
However I use the latest one with the same configuration, now the PlantUML is properly generated :)

however for the mermaid chart, I made the syntax adjustment as you mentioned but it doesn't generate the chart :

and this is what I changed in my md:

      ```{mermaid}
      %%| filename: flowchart
      %%| fig-cap: A simple flowchart.
      flowchart LR
            A-->B
            B-->C
            C-->D
            D-->E
            click A "https://www.github.com" _blank
            click B "https://www.github.com" "Open this in a new tab" _blank
            click C href "https://www.github.com" _blank
            click D href "https://www.github.com" "Open this in a new tab" _blank
      ```



      ### sequence diagram
      
      ```{mermaid}
      sequenceDiagram
          Alice->>Bob: Hello Bob, how are you ?
          Bob->>Alice: Fine, thank you. And you?
          create participant Carl
          Alice->>Carl: Hi Carl!
          create actor D as Donald
          Carl->>D: Hi!
          destroy Carl
          Alice-xCarl: We are too many
          destroy Bob
          Bob->>Alice: I agree
      ```

I checked that quarto cli is callable already.
Am I missing something?

[tarleb]

Happy to hear that PlantUML seems to be working now.

To let Quarto handle the Mermaid diagram you'll need to process the input file with Quarto, e.g. by running quarto render. The diagram filter should then be installed as a Quarto extension. Things work a bit differently with Quarto, it's not a drop-in pandoc replacement.

[veenone]

I just following your clue and indeed to use quarto render , I need to first change the extension to qmd and it converted the mermaid properly.

So in this case of mine, where my approach is to use pandoc to convert markdown with both content (mermaid / plantUML) will it be impossible / technically complicated to convert both models at 1 go ? I think the easiest solution to stick with plantUML for all diagrams..

[tarleb]

If you copy diagram.lua to _extensions/diagram/diagram.lua, then you can use the filter by adding this YAML to your qmd file:

filters:
  - diagram.lua

Or use it for some formats only. See also the file test/plantuml-quarto.qmd.

[veenone]

got it! thanks.

btw for the execpath configuration introduced in the last changes,
is it possible to set the jar file path with environment variable ?

current configuration:

---
diagram:
  engine:
    plantuml:
      execpath: ['java', '-jar', 'c:/tools/plantuml.jar']
      mime-types:
        application/pdf: false
        image/png: true
...

what I want to do :

---
diagram:
  engine:
    plantuml:
      execpath: ['java', '-jar',  $(TOOL_DIR)'/plantuml.jar']
      mime-types:
        application/pdf: false
        image/png: true
...

where $(TOOL_DIR) value is a path defined in other metadata / in a make file before executing pandoc

[tarleb]

That's not possible yet, but seems like a good idea. Please open a new feature request for that.

[veenone]

Done! Submitted in #43