https://github.com/alipsa/mdr
Render mdr files as html
https://github.com/alipsa/mdr
r-package renjin
Last synced: 14 days ago
JSON representation
Render mdr files as html
- Host: GitHub
- URL: https://github.com/alipsa/mdr
- Owner: Alipsa
- License: mit
- Created: 2020-12-28T16:12:03.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2022-08-16T17:33:37.000Z (almost 4 years ago)
- Last Synced: 2024-05-01T11:27:02.888Z (about 2 years ago)
- Topics: r-package, renjin
- Language: JavaScript
- Homepage:
- Size: 120 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# mdr
A [Renjin](https://github.com/bedatadriven/renjin) package (extension) to render mdr files as markdown, html, or pdf
The *mdr* file format is somewhat similar to *rmd* (r markdown) in the sense that it enables enhancing markdown with r code to support
[reproducible research](https://en.wikipedia.org/wiki/Reproducibility#Reproducible_research_method); but
where rmd relies on knitr and "magic rules" for what and especially how to render r code, mdr puts the responsibility
to generate markdown text from r code on you - and using the [r2md](https://github.com/perNyfelt/r2md) package
this becomes quite a pleasant experience giving you lots of control and power.
The mdr package is essentially a package (Renjin extension) that processes mdr text or files and produces html.
This is used in the [Munin](https://github.com/perNyfelt/munin) reports server to support mdr files as one of its supported report formats.
Use the method `parseMdr()` to parse a mdr character vector (string), a mdr file, or a list of mdr lines into a r2md::Markdown object.
Typically, you will use the `renderMdr()` to parse and render the mdr content into html (or markdown by adding the outputType parameter,
e.g. `renderMdr(mdrFile, outputType="markdown"`). Valid outputTypes are `html` (default), `markdown`, and `pdf`.
To use it, add the following dependency to your pom.xml
```xml
se.alipsa
mdr
1.5.1
```
## Example
Given a mdr document with the following content:
````
# Summary
```{r}
md.add(summary(mtcars$qsec))
md.content()
```
How about that?
````
...the code: `html <- renderMdr(rmd)` will make the html variable contain the following html:
```html
Summary
Var1Freq
Min.14.5
1st Qu.16.892
Median17.71
Mean17.849
3rd Qu.18.9
Max.22.9
How about that?
```
(Note: indentation above added to clarity, the actual result does not indent the html code)
You can do whatever you like in the R code block but whatever is returned from the block (the last expression) is
assumed to be the markdown to render into html. So if you do:
````
# Summary
```{r}
md.add(mtcars, attr=list(class="table")
md.content()
"How about that?"
```
````
...none of the markdown code for mtcars will be run, the Markdown content that *will* be added is `"How about that?"`.
However, the code is still executed and since the session for subsequent code blocks is the same, md.content() will
still contain the mtcars data.frame if you set the subsequent code block option `initialize=FALSE` and not start that
subsequent code block with md.clear() or md.new() - then it will be truly lost.
So to summarise the key [r2md](https://github.com/perNyfelt/r2md) methods:
- md.new(x): begin a new markdown text
- md.add(x): append to the existing markdown text or start a new one if there was none before. The content can be text,
a data.frame or matrix, a t-test etc.
- md.plot({x}): append a series of plot commands
- md.clear(): removes the content of an existing markdown text or creates a new one if none existed before
where x is the content to add
## Configuration
The following code block options are supported:
- **echo**: Output the code before the result is outputted, defaults to FALSE
- **eval**: Whether to run the code or not, defaults to TRUE
- **include**: Whether the results of the evaluation should be outputted or not, defaults to TRUE
- **initialize**: Whether a code block should "start fresh" i.e. with md.clear() automatically or not, defaults to TRUE
Example:
````
# Summary
```{r echo=TRUE}
md.add(summary(mtcars$qsec))
# Return the markdown, technically md.add() and md.new() does that as well so we could have skipped the next line
md.content()
```
````
This results in
````html
Summary
```{r echo=TRUE}
md.add(summary(mtcars$qsec))
```
Var1Freq
Min.14.5
1st Qu.16.892
Median17.71
Mean17.849
3rd Qu.18.9
Max.22.9
````
For multiple option, just separate them with comma, e.g:
\`\`\`{r echo=TRUE, include=FALSE}
Note that if you set eval to FALSE, the 'include' parameter is ignored.
Setting include to TRUE makes no sense in that case and will just be ignored as it has no meaning.
[Here is an example](https://github.com/perNyfelt/mdr2html/blob/main/src/test/resources/research.mdr) of a mdr report.
See the [tests](https://github.com/perNyfelt/mdr2html/blob/main/src/test/R/Mdr2htmlTest.R) for more usage details.
# Version History
### Ver 1.5.3
### Ver 1.5.2, Aug 16, 2022
- upgrade maven plugins
- upgrade to r2md 1.0.4
- require java 11
### Ver 1.5.1, Jan 17, 2022
- Change default behavior of code blocks to default to do md.clear() in the beginning unless the `initialize` option
is set to FALSE (i.e. the old behavior).
### Ver 1.5.0, Dec 27, 2021
- upgrade r2md to 1.0.3 to add support for `htest` classes
- rename package to mdr
- add support for pdf output
### Ver 1.4.0, Dec 8, 2021
- upgrade r2md to 1.0.1 to add the md.addPlot function for more versatile plotting.
- switch to 3 position version scheme so bumping version to the 1.4.x range
### Ver 1.3, Jan 31, 2021
- add highlightJs code formatting
### Ver 1.2, Jan 24, 2021
- Remove dependency on htmlcreator
- Add versions plugin with rules excluding beta versions
- Add maven enforcer plugin to require minimum maven version
### Ver 1.1, Jan 10, 2021
Remove direct rendering to html with html.add and change to render into markdown and then to html.
parseMdr now returns a r2md::Markdown object, use renderMdr to get either html (default) or markdown content.
### Ver 1.0, 2021-Jan-08
- Initial release