Add more out-of-box custom block environments

[cderv]

Currently, we mainly support Theorem and Proof: https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#theorems

It would be interesting to support more generic Note block with pre defined style as we can see in several places.

• block example https://bookdown.org/yihui/bookdown/custom-blocks.html where the required CSS is only in the book
• Jupyter book content block: https://jupyterbook.org/content/content-blocks.html
• http://desiree.rbind.io/post/2019/making-tip-boxes-with-bookdown-and-rmarkdown/
• Mkdocs: https://squidfunk.github.io/mkdocs-material/reference/admonitions/

See also #940 (comment) for ideas.

Creating issue here for reference, but maybe this should not be in bookdown, or not all.

But support for some special block to support HTML and PDF output would be interesting.

For example in LaTeX:

• https://tex.stackexchange.com/questions/53245/pretty-formattings-for-warning-and-info-blocks
• https://ctan.org/tex-archive/graphics/bclogo/
• https://tex.stackexchange.com/questions/8689/how-to-create-a-warning-box-like-this-see-the-figure-to-get-the-idea
• https://ctan.org/pkg/awesomebox and https://ctan.org/pkg/tcolorbox used in this nice book template https://github.com/Wandmalfarbe/pandoc-latex-template with blocks:

[cderv]

This is also what is done in bs4_book() with some special css

bookdown/inst/resources/bs4_book/bs4_book.css

Lines 458 to 489 in f7d0622

	.rmdnote, .rmdcaution, .rmdimportant, .rmdtip, .rmdwarning {
	margin: 1rem calc(-2px - 0.5em);
	padding: 1rem;
	border: 2px solid #eee;
	}
	.rmdnote > *:last-child, .rmdcaution > *:last-child, .rmdimportant > *:last-child, .rmdtip > *:last-child, .rmdwarning > *:last-child {
	margin-bottom: 0;
	}
	@media (max-width: 767.98px) {
	.rmdnote, .rmdcaution, .rmdimportant, .rmdtip, .rmdwarning {
	margin: 1rem -1rem;
	border-width: 4px;
	}
	}
	.rmdnote {
	border-color: var(--primary);
	}
	.rmdimportant {
	border-color: var(--success);
	}
	.rmdcaution {
	border-color: var(--danger);
	}
	.rmdwarning {
	border-color: var(--warning);
	}
	.rmdtip {
	border-color: var(--info);
	}

Example:

• https://mastering-shiny.org/basic-app.html#create-app
• https://github.com/hadley/mastering-shiny/blob/ac79538a51032df97c19d61222efecacaeb5f8eb/basic-app.Rmd#L60-L66

but not sure it will render in PDF for now. It will just be ignored for now.

[yihui]

For LaTeX output, my hack was to use a bullet and define the bullet symbol to be an icon:

bookdown/inst/examples/latex/preamble.tex

Lines 59 to 89 in 6bc7368

	\newenvironment{rmdblock}[1]
	{
	\begin{itemize}
	\renewcommand{\labelitemi}{
	\raisebox{-.7\height}[0pt][0pt]{
	{\setkeys{Gin}{width=3em,keepaspectratio}\includegraphics{images/#1}}
	}
	}
	\setlength{\fboxsep}{1em}
	\begin{kframe}
	\item
	}
	{
	\end{kframe}
	\end{itemize}
	}
	\newenvironment{rmdnote}
	{\begin{rmdblock}{note}}
	{\end{rmdblock}}
	\newenvironment{rmdcaution}
	{\begin{rmdblock}{caution}}
	{\end{rmdblock}}
	\newenvironment{rmdimportant}
	{\begin{rmdblock}{important}}
	{\end{rmdblock}}
	\newenvironment{rmdtip}
	{\begin{rmdblock}{tip}}
	{\end{rmdblock}}
	\newenvironment{rmdwarning}
	{\begin{rmdblock}{warning}}
	{\end{rmdblock}}

There are dedicated LaTeX packages for this task such as awesomebox and tcolorbox as you mentioned above. I don't have much experience with them, though. We briefly mentioned awesomebox in the cookbook: https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html

I'm not sure if this feature should belong to bookdown or not.

[cderv]

I'm not sure if this feature should belong to bookdown or not.

You think it could belong to its own package ? Initially I posted here because it seems feature wanted for books (as the block engine set in bookdown, or the equivalent in jupyter book).

Having it elsewhere would indeed allow us to use it in different type of output. 🤔
I'll think of it more and maybe try it out outside of bookdown.

[yihui]

I think it will definitely benefit non-bookdown users. I'm hesitating because this feature will introduce LaTeX and HTML dependencies that can't be well defined. For example, users may have different preferences over which LaTeX environment to use (like my \itemize hack above, or awesomebox, or tcolorbox), or which icons to use, or margin, padding, bg color, and so on. There is too much that can be customized, and I'm not sure how we can satisfy the potential demand for customization.

That said, I think it's fine to start from bookdown, and move this feature into core rmarkdown when necessary. That shouldn't break anything.

[cderv]

There is too much that can be customized, and I'm not sure how we can satisfy the potential demand for customization.

I completely understand this. However I find that not offering a simple solution does not help all users to benefit from an advanced feature.

I was thinking of this feature as

• bookdown should offer opinionated ways of doing this (choice of tools, of style, ...) so that anyone can easily use it.
• This way would use a simple common syntax like fenced div :::
• An opt out mechanism would allow advanced users to deactivate bookdown ways and provide the necessary files and configuration to customize (new CSS, new preamble, ...)

I believe today you can already do that if you now how (adding correct CSS classes and defining LaTeX environment) but you need the knowledge and I feel it should be easier like with Jupyter book content block, or Mkdoc's content block

[cderv]

cc @apreshill this is the issue I mentioned during the meeting

[tchevri]

Again thank you so much for everything you did, regarding this and #940, really can't thank you enough.
Quick question though, if I may?
I expected the div syntax to allow me to make full use of rmarkdown format, as opposed to the more limited block engine?
Therefore, I was expecting this to work:
::: {.theorem}
`r if (out_type=="beamer") "- "` Let $m$ be an even integer and $p$ be any integer. Then, $m \cdot p$ is an even integer.
:::
but funny enough, when i compile, the whole theorem gets gobbled up - nothing prints...
(I took this from my document, but if I add the same `r ` command into your sample bookdown book theorem in chapter 5, i get the exact same result, obviously.
Should i be expecting the `r ` command causes the theorem to no longer appear in the pdf?

Since the answer is probably no, I tried a much simpler version and I modified only your chapter 5 theorem, adding a simple -:
- For a right triangle, etc...
Doing so messes up the github compile (I get two messy bullet points) and in the bookdown::pdf_book compile, I no longer get the theorem at all.... (same for my custom bookdown::beamer_presentation2).
Seems very odd to meL since I am only adding one character, I can't be messing it up??
just to confirm the issue is not on my end, I tried directly with your bookdown template and i am getting the same result, so i am guessing you should be able to reproduce very easily and tell me if i am doing something wrong.

many thanks
thomas

[cderv]

Hi @tchevri,

I think you found an issue. We use a Lua filter to power this feature, and I think we only expect a paragraph inside such env. Adding a - first will not create a paragrah but a bullet list element and our Lua filter does not seem to support that.

I moved your comment in a issue. Please next time, open a new issue when you report something not directly related to the issue in which you comment. Thank you !