search

bids-standard / bids-specification

Brain Imaging Data Structure (BIDS) Specification
https://bids-specification.readthedocs.io/
Creative Commons Attribution 4.0 International
265 stars 154 forks source link

improve admonition handling code #1752

Open Remi-Gau opened 3 months ago

Remi-Gau commented 3 months ago

Currently admonition removal deletes the entire admonition "directive" during the pdf build

!!! note "foo bar"

    LOREM ispum

becomes this

LOREM ispum

From personal experience (and seeing @oesteban work with them) it adds mental load when writing them by having to keep in mind this extra rule "don't put anything meaningful in the title of the admonition".

I could try to make this a bit nicer by making the code do this:

This:

!!! note "foo bar"

    LOREM ispum

becomes this

**Note**: foo bar
LOREM ispum

@oesteban @effigies @sappelhoff

Any thoughts?

oesteban commented 3 months ago

That would be a great start, and honestly, I am not sure the PDF rendering should get much further than that.

Perhaps it would be a better effort to set the correct HTTP metadata headers in the document so printing to PDF does generate a nice-looking document.

Markdown-based slides engines rely on the browser's printing feature to do that. I think CI/CD can run chrome or firefox headlessly and print out a PDF.