--- title: simplermarkdown css: "style.css" --- Introduction to simplermarkdown -------------------------------------- First write a markdown file using [pandoc markdown](https://pandoc.org/MANUAL.html#pandocs-markdown). The package uses pandoc to parse the markdown and runs any code blocks tagged as being R-code. The result a new markdown file that can be further processed using pandoc and compiled to, for example, PDF or HTML. To process your markdown file you can use the `mdweave` function: ``` mdweave("mydocument.md", "mydocument_woven.md") ``` The resulting document `mydocument_woven.md` can then be processes further using pandoc. Below is a ready to run example using an example document in the package: ``` library(simplermarkdown) example1 <- system.file("examples/example1.md", package = "simplermarkdown") mdweave(example1, "example1_woven.md") system("pandoc example1_woven.md -o example1.pdf") ``` The package also includes the functions `mdweave_to_pdf`, `mdweave_to_html` and `mdweave_to_tex`, that combine these last two function calls. Therefore, the example above could also have been written as: ``` library(simplermarkdown) example1 <- system.file("examples/example1.md", package = "simplermarkdown") mdweave_to_pdf(example1, "example1.pdf") ``` Although it is possible to pass additional arguments to `pandoc` through the `mdweave_to_...` functions, it is probably just as easy to call `pandoc` directly. ## Writing markdown An example of a basic code block tagged as being R-code is shown below. The id/label if the block is `codeblock1`. ````` ```{#codeblock1 .R} a <- 1+1 a ``` ````` By default the code in the code block is run and both the code and the output of the code are shown in the generated new code block. In the output file this will result in ```{#codeblock1 .R} a <- 1+1 a ``` Note that the `.R` needs to be the first argument starting with a `.` for the codeblock. For example ` ```{#codeblock .foo .R foo=bar} ` won't be evaluated, while ` ```{#codeblock foo=bar .R .foo} ` will. By default the code in the code block is run and both the code and the output of the code are shown in the generated new code block. Arguments can be used to suppress either showing the code or the output: ````` ```{#codeblock1 .R echo=FALSE results=TRUE} a <- 1+1 ``` ````` Inline code is also supported. Again it should be tagged with `{.R}`: ``` The average value of `Sepal.Width` is `mean(iris$Sepal.Width)`{.R} and that of `Petal.Width` is `mean(iris$Petal.Width)`{.R}. ``` The final result of the inline code will always be included as text into the resulting markdown document. In case of code blocks the code is passed on to a function. Depending on the function used this can result in a code blocks with the evaluated code (the default), tables, figures and you can also specify your own functions. ### Figures To generate a figure use the `output_figure` function. The function will run the code, capture any output on the specified device and generate a markdown image include. ````` ```{.R #myfigure fun=output_figure name="test" caption="My figure" device="pdf" width=8 height=6} plot(dta$Sepal.Width, dta$Petal.Width) ``` ````` `output_figure` accepts the options `caption` (default none), `device` (possible values are `"png"` and `"pdf"`), `echo` (default `FALSE`; echo the commands to the output) and `results` (default `FALSE`; show output of the command (other than the figure) in the output). Additional arguments such as `width` and `height` are passed on to the device (in this case `pdf()`). When an id is given for the code block (as `#myfigure` above) this is also added to the figure. The figures are saved in the folder `figures` in the current folder. This can be controlled by the `dir` argument. ### Tables To generate a table, we tell it to pass the code in the code block to the function `output_table` from the `simplermarkdown` package. This function will take the final result and generate a markdown table from that. Any additional arguments of the code block are passed on to the `output_table` function. ````` ```{.R #mytable fun=output_table caption="Sample iris"} dta$foo <- dta$Sepal.Width/dta$Sepal.Length dta[1:20, ] ``` ````` `output_table` only accepts the `caption` argument. Unfortunately, pandoc does not yet support adding id's to tables at the moment without the [pandoc crossref filter](https://github.com/lierdakil/pandoc-crossref). Therefore, simplermarkdown also doesn't add the id to the resulting table as this would interfere with regular pandoc use. Should you want to add an id to the table in order to use it with the crossref filter: you can either do ```` : Sample iris {#mytable} ```{.R fun=output_table} iris[1:5, ] ``` ```` or ```` ```{.R fun=output_table caption="Sample iris {#mytable}"} iris[1:5, ] ``` ```` ### Other output By using the `output_raw` filter, any other output can be generated. This function will run the code, capture any output and put that directly into the resulting markdown document. For example, let's print a list with all of the iris species: ````` ```{.R fun=output_raw} writeLines(paste("-", levels(iris$Species))) ``` ````` Or you can write your own filter function. This function will get the code in the code block as character vector as it's first argument, the language of the code block, and the id of the code block and any other arguments given. For example: ``` print_in_bold <- function(code, language = "R", id = "", ...) { cat("\n**", code, "**\n", sep = "") } ``` This function could for example be defined in a block in the markdown file. Afterwards, this function can be used in your markdown document as: ````` ```{.R fun=print_in_bold} Hello World! ``` ````` Using as a vignette engine ----------------------------------------------------------------------- To use simplermarkdown as an engine for your R-package vignettes you will need to do the following: #### Specify simplermarkdown as your vignette builder in your `DESCRIPTION` file: ``` VignetteBuilder: simplermarkdown ``` #### Add simplermarkdown as a dependency of your package. If your package doesn't use simplermarkdown otherwise you can add it to your `Suggests` field in the `DESCRIPTION` file: ``` Suggests: simplermarkdown ``` #### Use the extension `.md` for your vignette. Create the vignette in the `vignettes` directory in your package source. #### Specify the vignette engine in your vignette. You have to add the following line to your vignette: ``` %\VignetteEngine{simplermarkdown::mdweave_to_html} ``` Instead of `mdweave_to_html` you can also use `mdweave_to_pdf` to generate a vignette in PDF format. It is easiest to do this in a comment section in your markdown file. For example, start your markdown file with: ``` --- title: [The title of the vignette] --- [And the contents of your vignette] ``` ### Custom styling By default the default templates and styling of the pandoc installation on your machine will be used. However, you can also specify custom styling in the header of your markdown file. See the [documentation of Pandoc](https://pandoc.org/MANUAL.html) for more information. For example, if you generate HTML output and you want to use a custom CSS-stylesheet, you can place the stylesheet in the `vignettes` directory and refer to the stylesheet in the header: ``` --- title: [The title of the vignette] css: custom_styling.css --- ``` ## A note about paths and working directories `simplermarkdown` tries to assume as little as possible about possible workflows. However, this also means that you, the user, are responsible for some things where other packages might make assumptions. One of the places where this is the case is for paths and working directories. And this is especially relevant when including figures and when generating figures using R. As an example take the following project directory: ````` report/ report.md figures/ figure1.png report/output/ ````` The report contains the following code: `````  ```{.R fun=output_figure name="figure2" caption="Caption", device="png"} plot(1:10) ``` ````` Assume the current working directory is the root of the project directory and that we run `mdweave` as: ````` mdweave("report/report.md", "report/output/report.md") ````` Figures are by default created in the directory `figures` in the target directory. Therefore the directory structure after running `mdweave` is: ````` report/ report.md figures/ figure1.png ouput/ report.md figures/ figure2.png ````` And the resulting markdown file will contain the following markdown: `````   ````` As you can see, we now have two locations with figures. When running `pandoc` from the root directory of the project to create the final output: ````` pandoc report/output/report.md -s -o report/output/report.html ````` `pandoc` will not be able to find the first figure. It will find the second figure. When you would run the final `pandoc` command from the `report/output` directory. `pandoc` will not be able to find any of the figures. There are several possible solutions for the example above: - When working on linux or mac, you could create a symbolic link from `report/output/figures` to `report/figures`. - Copy `report/figures` to `report/output/figures`. - Path of least resistance: run `mdweave` and `pandoc` from the `report` directory and also put the output in the same directory. - And probably others. Note that the same issues occur when referencing stylesheets etc. in the meta block of the markdown file.