FEATURE: Figure out how to use Mkdocs "admonitions" together with pandoc

[sappelhoff]

We could use the admonitions package for Mkdocs to create "notes" or "warning", etc. in our spec like this:

I think this would be desirable from a formatting perspective. It can help us to draw more attention to some items, or provide extra information in boxes.

One immediate example I see would be a small "warning" box under the paragraph discussing anonymization of dates --> The warning would make users aware of potential issues with the FIF format (see #538)

Problems

This Mkdocs package and the involved syntax would probably (???) not translate well to PDF when we render the specification using pandoc. With the help of the set of tools written by @Arshitha --> https://github.com/bids-standard/bids-specification/tree/master/pdf_build_src

Solution

--> yet to be found.

If somebody agrees that "admonitions" would be helpful and is interested in enabling that for us: Please give it a shot!

If you (dear reader) disagree with "admonitions" being helpful for specification readers, please say so.

[oesteban]

jupyter-book uses pyppeteer to generate the PDF version.

It basically runs the HTML inside a headless Chromium browser and calls the print function.

The admonition boxes are very nicely rendered, but I'm very unsure of what would happen with the formatting overall.

[oesteban]

That said, I'm also unsure of how important is that the PDF version is nicely structured as a document instead of a direct print-out of the html.

[Remi-Gau]

I think we might want to be conservative when messing up the pdfs: see some of the comments regarding how the pdf can be used "THE" reference for people in industry: #135

[oesteban]

Maybe we should rescue Microsoft's chm format :D

[Remi-Gau]

I think that it is fair to close this one for now.