INRIA / INRIA/scikit-learn-mooc
How to convey that admonitions are side-comments that may be skipped (in most cases)
- Dominant language
- Jupyter Notebook
- Stars
- 1.4k
- Forks
- 600
- Avg merge
- 6d 20h
- Merged PRs (30d)
- 2
Description
There is this weird contradiction that most of the time:
- we use admonitions for side-comments
- because they are colored brings more attention to them than they should. One example off the top of my head that we have in plenty of places:

Ideas of the top of my head:
- technically simpler but less visually appealing: can some admonitions advertising more easily that they are side-comments maybe with a less visible color e.g .greyish?
- technically harder but more visually appealing: is there a way to have a foldable admonition so that you see the title only and you can click on it to see more? Can we support a similar thing inside notebooks through our py-to-ipynb conversion logic in https://github.com/INRIA/scikit-learn-mooc/blob/bc157356571cddc9de6fba978e9446cecee1a0da/build_tools/convert-python-script-to-notebook.py#L120
Minor comments:
- I am pretty sure sometimes (quite rarely though I would say) we use admonitions as way to highlight that something is important.
- I guess there are more things than admonitions, like footnotes or sidenotes but supporting similar things in notebooks seems to hard
- does O'Reilly do something particular for this kind of stuff and his different notes to say "feel free to skip this" while still avoiding to disrupt the flow
Contributor guide
Assessment
This issue has not been assessed yet.