Rmd – language extensions beyond markdown


#1

markdown, knitr, pandoc, are fantastic tools, and rmarkdown does a great job at linking all the steps. However, it seems to me that the Rmd format has also the potential to complement the oft-limiting markdown specs, with custom extensions tailored for data-heavy and/or finely-formatted reports.

There are two aspects to this proposal:

  1. Convenience. Sure, we can already specify a custom figure alignment, figure size, etc. by embedding a figure in a knitr chunk,
{r echo=FALSE, out.width="0.8\\textwidth", fig.align='center'}
knitr::include_graphics('external_pic.png')

or start a paragraph with

`r newthought('In his later books')` Tufte...

but it’s hardly convenient, and affects legibility. Since R (knitr) is going to process the Rmd file before pandoc ever sees it, we could introduce an arbitrary convention to make it more writer-friendly, e.g.

.{width='0.8', align='center'}
![](external_pic.png)

and

.{$ In his later books} Tufte...

which knitr would process to output valid markdown to feed to pandoc, with raw html or tex where necessary, conditional on the chosen output format.
The delimiters would

  1. More flexibility. markdown is, by design, limited in features (tables, bibliography, styles, etc.). With a pre-processing step and a language such as R, we are free to overcome such limitations and add new features. This is particularly important in data-heavy reports, but also complex / polished documents such as books, where the simplicity of the markdown language can be limiting. (this is particularly visible with the number of existing / requested extensions in any markdown implementation).

If there’s a strong reason to keep the Rmd format 100% markdown-compatible (e.g displaying the source nicely on github), then such extensions could simply be wrapped in backticks like the current inline r syntax.


#2

@baptiste I agree that one could extend R Markdown to make it easy to do more tasks. It might be best to package these extensions in a separate package to keep R Markdown lean.

If you are interested in giving it a try, the flexdashboard package could serve as a model. It extends R Markdown along the lines you suggest (in this case, to make it easy to layout dashboards).