A Renjin R package that converts R objects and functions into markdown text or html
The approach is similar to htmlcreator which renders r objects directly into html whereas this package renders r objects into markdown which can then be exported to html (or pdf or whatever).
r2md is an integral part in the support for the mdr file format which is somewhat similar to rmd (r markdown) in the sense that it enables enhancing markdown with r code to support reproducible research; but where rmd relies on knitr and "magic rules" for what and how to render r code, mdr puts the responsibility to generate markdown text from r code on you - and using r2md this is quite a pleasant experience giving you lots of control and power.
The mdr2html package can process mdr files and render it as html. This is used in the Munin reports server to support mdr files as one of its supported report formats.
add the dependency to your dependency manager e.g.
<dependency>
<groupId>se.alipsa</groupId>
<artifactId>r2md</artifactId>
<version>1.0.1</version>
</dependency>library("se.alipsa:r2md")
md.clear()
md.add("# Hello")md.content() (which return the markdown as a string (character vector)) will equal # Hello\n
Assuming the following markdown:
Some text
- bullet
This is how you can create that with r2md:
library("se.alipsa:r2md")
md.clear()
md.add("#### Hello2")$add("Some text")$add("- bullet")
# convert the markdown to html and print it
print(md.asHtml())will result in
<h4>Hello2</h4>
<p>Some text</p>
<ul>
<li>bullet</li>
</ul>The following table:
| employee | salary | startdate | endDate |
|---|---|---|---|
| John Doe | 21000 | 2013-11-01 | 2020-01-10 00:00:00 |
| Peter Smith | 23400 | 2018-03-25 | 2020-04-12 12:10:13 |
| Jane Doe | 26800 | 2017-03-14 | 2020-10-06 10:00:05 |
...can be created as a data.frame in R and converted to markdown:
library("se.alipsa:r2md")
employee <- c('John Doe','Peter Smith','Jane Doe')
salary <- c(21000, 23400, 26800)
startdate <- as.Date(c('2013-11-1','2018-3-25','2017-3-14'))
endDate <- as.POSIXct(c('2020-01-10 00:00:00', '2020-04-12 12:10:13', '2020-10-06 10:00:05'), tz='UTC' )
df <- data.frame(employee, salary, startdate, endDate)
md.add(df)md.content() will equal:
employee | salary | startdate | endDate
--- | --- | --- | ---
John Doe | 21000 | 2013-11-01 | 2020-01-10 00:00:00
Peter Smith | 23400 | 2018-03-25 | 2020-04-12 12:10:13
Jane Doe | 26800 | 2017-03-14 | 2020-10-06 10:00:05
...and md.asHtml() will equal:
<table>
<thead>
<tr><th>employee</th><th>salary</th><th>startdate</th><th>endDate</th></tr>
</thead>
<tbody>
<tr><td>John Doe</td><td>21000</td><td>2013-11-01</td><td>2020-01-10 00:00:00</td></tr>
<tr><td>Peter Smith</td><td>23400</td><td>2018-03-25</td><td>2020-04-12 12:10:13</td></tr>
<tr><td>Jane Doe</td><td>26800</td><td>2017-03-14</td><td>2020-10-06 10:00:05</td></tr>
</tbody>
</table>Adding links is just as expected: i.e. Google can be created
md.clear()
md.add("[Google](http://www.google.se)")... and when rendered as html it will result in
<p><a href="http://www.google.se">Google</a></p>An image such as:
can be referenced using
md.clear()
md.add("[Tree](https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg)")or, alternatively:
md.clear()
md.add(md.imgUrl("https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg", alt="Tree"))This latter form is useful if you want to add attributes e.g:
md.clear()
md.add(md.imgUrl("https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg", attr=list(id = "mystyle", class = "image")))md.content() will give you
{id = 'mystyle', class = 'image'}\n
...and md.asHtml() will result in
<p><img src="https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg" alt="" id="mystyle" class="image" /></p>If you want to embed the image content in the file itself (e.g. to create self contained single html files) you can use md.imgEmbed(fileNameOrUrl) to convert the file or url content to a base64 string, e.g:
md.clear()
md.add(md.imgEmbed("https://upload.wikimedia.org/wikipedia/commons/d/dd/Accounting-icon.png"))md.content() will be: \n
...and md.asHtml() will be:
<p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAE0AAABNCAAAAADGYrZsAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH1gkeAAohA+PvmwAAAMhJREFUWMPtmFEOwiAQRBlKxSt4/zOaolbGDw1qIyEkm0jS2fSnKX3ZwsvSBScfo0eYQsj3if5wjAF+goNnJtdlSbc1LZdzWrNrBuarMwsA2ZDmnWXsiMbdfCksaaGYVx/DftrnK6DsFW1rSKX+9RnYoLHPQa2pqmXD3v5ShrqYoT+ButEw3QFhOm+zaW7Z1BCa0vLANNUQ0fZK4x9yo1ZBtG4aNW+iiSbaj3/ycTsj6qRxhNzw1R2CzwuvTeV9U55w00yiDAPdA+74PJ7jCTFiAAAAAElFTkSuQmCC" alt="" /></p>The embedded technique is also used for plots. Behind the scenes the plot is exported to a png file which is then embedded using the same technique as for md.imgEmbed(). Here is an example of a barplot:
md.clear()
md.add("# Plot")
md.addPlot(
{
plot(mtcars$mpg ~ mtcars$hp)
abline(h = mean(mtcars$mpg))
},
width=350,
alt="mtcars mpg ~ hp",
attr=list(class="plot1", title="This is an important graph!"),
height=400
)Note that md.addPlot() takes an anonymous code block { } as the argument where you add all the plotting functions you need.
All additional arguments except alt and attr (width and height in this case, I put them first and last to illustrate that the
placement is not important) goes to the png() function.
The md.content() will return something like this for the above plot:
# Plot
{class="plot1" title="This is an important graph!"}
- Renjin The R implementation for the JVM for which this extension (package) is for.
- commons-io Used for some IO tasks such as downloading the content of a URL
- Flexmark Used to render markdown into html
See the pom.xml for more details.
- add md.addPlot to allow more flexibility
- update junit and maven enforcer plugin versions.
- Fix bug in md.imgEmbed for external resources, add additional tests
- Fix bug in getting content from a StringArrayVector
Initial version.