<p><div><div><div><div data-width="100" data-show-faces="false" data-send="true" data-layout="button_count" data-height="21" data-href="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/"></div></div><div><a data-url="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/" data-counturl="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/" data-count="horizontal" data-text="High Performance CommonMark and Github Markdown Rendering in R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://ropensci.org/blog/blog/2016/12/02/commonmark"> rOpenSci Blog - R</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>This week the folks at Github have open sourced their <a target="_blank" rel="nofollow" href="https://github.com/github/cmark">fork</a> of libcmark (based on the extensive <a target="_blank" rel="nofollow" href="https://github.com/jgm/cmark/pull/123">PR by Mathieu Duponchelle</a>), which they use to render markdown text within documents, issues, comments and anything else on the Github website. The new release of the <a target="_blank" rel="nofollow" href="https://cran.r-project.org/web/packages/commonmark/index.html">commonmark</a> R package incorporates this library so that we can take advantage of Github quality markdown rendering in R.</p>
<p>The most exciting change is that the library has gained an extension mechanism to provide optional rendering features which are missing from the commonmark spec. Most notably, Github has added extentions for rendering GFM style tables and autolinks, both very useful features for R users.</p>
<p><img alt="consolemd" src="https://i1.wp.com/ropensci.org/assets/blog-images/consolemd.png?w=456" data-recalc-dims="1"></p>
<h2>What is CommonMark</h2>
<p><a target="_blank" rel="nofollow" href="http://spec.commonmark.org/">CommonMark</a> is an initiative by Professor John MacFarlane (author of Pandoc) to formally define markdown syntax specification and provide high quality reference implementations. His high performance <a target="_blank" rel="nofollow" href="https://github.com/jgm/cmark">cmark</a> C library converts markdown text into xml, html, latex or groff man in the <a target="_blank" rel="nofollow" href="https://github.com/jgm/cmark#readme">blink of an eye</a>.</p>
<p>The <a target="_blank" rel="nofollow" href="https://cran.r-project.org/web/packages/commonmark/index.html">commonmark</a> R package wraps libcmark and has been on CRAN for a while. It should replace the old <a target="_blank" rel="nofollow" href="https://cran.r-project.org/web/packages/markdown/index.html">markdown</a> package which is based on the deprecated Sundown library (the <a target="_blank" rel="nofollow" href="https://github.com/vmg/sundown">author</a> of Sundown now works for Github and is one of the contributors to libcmark).</p>
<h2>CommonMark Extensions</h2>
<p>Commonmark is extremely reliable and optimized, but the disadvantage of the formal specification is that it can take a long time for new feature proposals to be adopted. For example a <a target="_blank" rel="nofollow" href="https://talk.commonmark.org/t/tables-in-pure-markdown/81">proposal</a> for markdown tables has been open for over two years, but ironing out the syntax details has proven to be difficult.</p>
<p>For this reason many commonmark implementations include 'extensions' to enable features which are not (yet) part of the official specification. The current version of the commonmark R package offers 4 such extensions:</p>
<ul>
<li><strong>table</strong> support rendering of tables</li>
<li><strong>strikethough</strong> via <code>~sometext~</code> syntax</li>
<li><strong>autolink</strong> automatically turn URLs into hyperlinks</li>
<li><strong>tagfilter</strong> blacklist html tags: <code>title</code> <code>textarea</code> <code>style</code> <code>xmp</code> <code>iframe</code><br>
<code>noembed</code> <code>noframes</code> <code>script</code> <code>plaintext</code>.</li>
</ul>
<p>These extensions were added by Github to support <a target="_blank" rel="nofollow" href="https://guides.github.com/features/mastering-markdown/">GitHub Flavored Markdown</a>.</p>
<p><img alt="roxygenmd" src="https://i0.wp.com/ropensci.org/assets/blog-images/autolink.png?w=456" data-recalc-dims="1"></p>
<p>Note that extensions are not enabled by default. For example to render tables, you need to set the <code>extensions</code> parameter to <code>TRUE</code> or <code>&quot;table&quot;</code>. </p>
<h2>Markdown and Roxygen</h2>
<p>We also use commonmark in the upcoming version 6.0 of roxygen2 to support <a target="_blank" rel="nofollow" href="https://github.com/klutometis/roxygen/blob/master/vignettes/markdown.Rmd">markdown within roxygen</a>, which is super awesome.</p>
<p><img alt="roxygenmd" src="https://i0.wp.com/ropensci.org/assets/blog-images/roxygenmd.png?w=456" data-recalc-dims="1"></p>
<p>To give this a try you need the development version of roxygen2:</p>
<div>
<pre><code data-lang="r">devtools<span>::</span>install_github<span>(</span><span>&quot;klutometis/roxygen&quot;</span><span>)</span>
</code></pre>
</div>
<p>To enable markdown roxygen for a given package, all you need to do is add a line with <code>Roxygen: list(markdown = TRUE)</code> to the package DESCRIPTION file. For more details check out the <a target="_blank" rel="nofollow" href="https://github.com/klutometis/roxygen/blob/master/vignettes/markdown.Rmd">vignette</a>.<br>
There is also package <a target="_blank" rel="nofollow" href="https://github.com/r-pkgs/roxygen2md">roxygen2md</a> which will automatically convert existing roxygen code to markdown.</p>
<p><div><div><div><div data-width="55" data-show-faces="false" data-send="true" data-layout="box_count" data-height="62" data-href="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/"></div></div><div><a data-url="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/" data-counturl="https://www.r-bloggers.com/high-performance-commonmark-and-github-markdown-rendering-in-r/" data-count="vertical" data-text="High Performance CommonMark and Github Markdown Rendering in R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="http://ropensci.org/blog/blog/2016/12/02/commonmark"> rOpenSci Blog - R</a></strong>.</div>
<hr>
<a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="https://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a title="The R Project for Statistical Computing" rel="nofollow" href="https://www.r-project.org/">R</a> news and <a title="R tutorials" rel="nofollow" href="https://www.r-bloggers.com/?s=tutorial">tutorials</a> on topics such as: <a title="Data science" rel="nofollow" href="https://www.r-bloggers.com/?s=data%20science">Data science</a>, <a title="Big Data" rel="nofollow" href="https://www.r-bloggers.com/?s=Big%20Data">Big Data, <a title="R jobs" rel="nofollow" href="https://www.r-users.com/">R jobs</a>, visualization (<a title="ggplot and ggplot2 tutorials" rel="nofollow" href="https://www.r-bloggers.com/?s=ggplot2">ggplot2</a>, <a title="Boxplots using lattice and ggplot2 tutorials" rel="nofollow" href="https://www.r-bloggers.com/?s=boxplot">Boxplots</a>, <a title="Maps and gis" rel="nofollow" href="https://www.r-bloggers.com/?s=map">maps</a>, <a title="Animation in R" rel="nofollow" href="https://www.r-bloggers.com/?s=animation">animation</a>), programming (<a title="RStudio IDE for R" rel="nofollow" href="https://www.r-bloggers.com/?s=RStudio">RStudio</a>, <a title="Sweave and literate programming" rel="nofollow" href="https://www.r-bloggers.com/?s=sweave">Sweave</a>, <a title="LaTeX in R" rel="nofollow" href="https://www.r-bloggers.com/?s=LaTeX">LaTeX</a>, <a title="SQL and databases" rel="nofollow" href="https://www.r-bloggers.com/?s=SQL">SQL</a>, <a title="Eclipse IDE for R" rel="nofollow" href="https://www.r-bloggers.com/?s=eclipse">Eclipse</a>, <a title="git and github, Version Control System" rel="nofollow" href="https://www.r-bloggers.com/?s=git">git</a>, <a title="Large data in R using Hadoop" rel="nofollow" href="https://www.r-bloggers.com/?s=hadoop">hadoop</a>, <a title="Web Scraping of google, facebook, yahoo, twitter and more using R" rel="nofollow" href="https://www.r-bloggers.com/?s=Web+Scraping">Web Scraping</a>) statistics (<a title="Regressions and ANOVA analysis tutorials" rel="nofollow" href="https://www.r-bloggers.com/?s=regression">regression</a>, <a title="principal component analysis tutorial" rel="nofollow" href="https://www.r-bloggers.com/?s=PCA">PCA</a>, <a title="Time series" rel="nofollow" href="https://www.r-bloggers.com/?s=time+series">time series</a>, <a title="finance trading" rel="nofollow" href="https://www.r-bloggers.com/?s=trading">trading</a>) and more...
<img height="1" alt="" width="1" src="http://feeds.feedburner.com/~r/RBloggers/~4/KeLD6CILP9k"></a></div>