How can I publish asciidoc containing plantUML digram to GitHub's Wiki

Question

Let's say I have this simple adoc file

:imagesdir: images

image::onion.png[]

[plantuml,plant,png]
....
usecase plant
....

the first line is just an image the second is a plantUml diagram.

by running

cp *.png out/images
asciidoctor -D out -r asciidoctor-diagram  root.adoc

I would copy all the images in the output folder and generate a html file including the plantUml diagram in png format in the out folder.

GitHub does not understand html. Though It does understand adoc, it doesn't render the plantUml diagrams.

Answer 1

GitHub has its own markdown dialect. I.e., we have to generate this format instead of html.

asciidoc does not support generating to markdown natively. Thus we have to use pandoc

asciidoctor -r asciidoctor-diagram -b docbook -o -  root.adoc | pandoc -f docbook -t gfm -o out/root.md

asciidoctor-diagram will generate the png files for the plantUml

-b docbook will transform adoc inot docbook format

pandoc will take the docbook format and generate the GigHub specific (-t grm) markdown

What still needs to be done is publish the markdown and the images to GitHub Wiki. The GitHub action file looks like this

name: publish adoc to wiki

on:
  push:
    branches:
      - main
   
permissions:
  contents: write
  packages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout base code
        uses: actions/checkout@v3
      - name: Generate asciidoc and copy images
        run: |
          sudo apt install graphviz
          sudo gem install asciidoctor-diagram
          sudo apt install pandoc
          mkdir -p out/images
          cp **/*.png out/images/
          asciidoctor -r asciidoctor-diagram -b docbook -o -  root.adoc | pandoc -f docbook -t gfm -o out/root.md
          cp images/*.png out/images/
      - name: Checkout wiki code
        uses: actions/checkout@v3
        with:
          repository: ${{github.repository}}.wiki
          path: tmp_wiki
      - name: Push to wiki
        run: |
          rsync -av --delete out/* tmp_wiki/ --exclude .git
          cd tmp_wiki
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add .
          git diff-index --quiet HEAD || git commit -m "Add changes" && git push

Answer 2

GitHub does not allow extensions to be used when rendering AsciiDoc, so you cannot publish an AsciiDoc document containing PlantUML source and expect the diagram to be rendered by GitHub.

I can see two options, although there may be others:

1. Render the PlantUML diagram locally and embed it in a separate version of the AsciiDoc file that you commit to your repo.

2. Use a GitHub action to publish a GitHub Pages site with the rendered PlantUML diagrams. This would perform the same steps as running asciidoctor locally.

Answer 3

To render the PlantUML diagram locally, you can use my Jamal preprocessor that has support for PlantUML natively before 2.5.0 and via Kroki following that version.

DISCLAIMER: I wrote Jamal; it is open source, available from Maven central as well as from https://github.com/verhas/jamal

You can edit your README.adoc.jam in IntelliJ or AsciidocFX, and the Acsiidoc preprocessor version of Jamal installed will continuously save the processed file into README.adoc containing the reference to the image, and it will also generate and regenerate the diagrams when needed.