[ENH] allow using of mkdoc admonitions

[Remi-Gau]

• add a script to remove mkdoc admonitions
• run it during pdf build
• add minimal testing to help debugging if needed
• add example admonition to highlight the bids examples repo

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 87.93%. Comparing base (c9e4779) to head (f9e699b).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1711   +/-   ##
=======================================
  Coverage   87.93%   87.93%           
=======================================
  Files          16       16           
  Lines        1351     1351           
=======================================
  Hits         1188     1188           
  Misses        163      163           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[Remi-Gau]

Example of admonition:

https://bids-specification--1711.org.readthedocs.build/en/1711/modality-specific-files/near-infrared-spectroscopy.html

Rendered PDF:

[Remi-Gau]

@tsalo @sappelhoff @effigies This is a draft but as far as I can tell this would allow using admonitions without breaking the PDF build.

Can you have a quick look and tell me if you see something I am missing?

[Remi-Gau]

the remark linting will be annoying though

[Remi-Gau]

an easy fix

OK so it seems that remark-lint-code-block-style is set to fenced by remark-preset-lint-markdown-style-guide

So need to find how to unset that.

[tsalo]

This looks awesome!

[Remi-Gau]

PDF looks fine to me.

Note that some links are not rendered in the pdf but this is not related to this PR.

For example the link at the top of the genetic section:

[`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)

I think this is because of the back tick in the square brackets.

[Remi-Gau]

For contributors: should we preface our admonitions with some markdown comments the way we do it the macros so that users are not confused about what they are ?

[tsalo]

I don't think that's necessary. Macros aren't exactly common, but admonitions are. We can have that info in a style guide if we want though.

[Remi-Gau]

I don't think that's necessary. Macros aren't exactly common, but admonitions are. We can have that info in a style guide if we want though.

OK so something to add in the contributing.md

[Remi-Gau]

Actually before merging.

• handle admonition that start with ??? and ???+
• ~~possibly simplify mkdoc macro that adds admonition below the filename templates~~