Rmarkdown conditional chunks to create multilingual pdf and html with images

Knit with multiple rendering options

I want to be able to knit my rmarkdown documents in different speaking language (english and french). I also want them to give similar rendering in html and in latex pdf so that I can use them in my courses as html version on the laptop, but also as printed version through the latex pdf. By the way, I also have a teacher and a student version for the R-scripts that I can purl from the Rmd file. This means many options for a unique rmarkdown document. Using a unique document allow me to directly modify things for the different versions at the same place. I do not have to jump from a file to another and verify that I copied every modification in the R-script or other… I personally use an external “run-all” R-script to choose options to run the different versions and rename output files.

A non exhaustive list of possibilities

In the upper output files, I list some of the tips I have to use to make this work and some bonus:

  • Use chunks options to render text according to speaking language chosen,
  • Use functions to render text color, background or format similar in pdf and html outputs,
  • Print inline (or not) images depending on speaking language,
    • Render two images side by side and centered on the page for html and pdf,
  • Allow verbatim chunk environment with background color for html and pdf,
  • Output R-script included in chunks for tutorials, with different versions for teacher and students.

I will modify this list if I face new difficulties or I find better ways to do things.

Output files in pdf, html, french and english

The complete list of tips can be seen on the following web pages (embedded in iframes). Rmd files and complementary ones needed to create these language specific HTML and PDF files are stored here on my github.

A package to use with caution

Formatting functions used in these Rmd files are implemented as a R package on my github account. However, they need to be used with caution because they require the use of external header files to be called when building your document: A tex file for “in_header” function for PDF output, and a css file for HTML output. Documentation is not completed. You can find the tutorial while following the links of the previous section. You can install it as follows.

# Library in development to be use with external customized header or css file
devtools::install_github("statnmap/Rmarkdown_tips")
library(KnitFmt)

Example: Include R output in conditional chunks

    ```{r CodeInChunkEN, echo=(lang == "EN"), eval=(lang == "EN"), results='asis'}
    cat(
    '### Example of title in a chunk
    #### Example of subtitle in a chunk
    - ', styleFmt("cat", "codecommand"), ' should be used with ',
    styleFmt("sep = \"\"", "codecommand"), ' otherwise a space will be added
    before "##subtitle", which avoid it to be recognised as a subtitle in markdown.
    - ', styleFmt("eval", "codecommand"), ' can be used with R object to knit
    chunk specific to language. Here ', styleFmt("lang", "codecommand"),
    ' is ', lang,  '\n',
    '- Double space should work to define new paragraph, but when using R
    functions, it may require "\\\\n"
    _(Note the number of backslash in the code here to print "\\\\n" correctly...)_.
        + ', styleFmt("For instance when using the format function,
                      following two spaces won\'t work:", "advert"), '  ',
    '    + This sentence won\'t be on a new line.',
    sep = "")
    ```

Example: two images side-by-side and centered

    ```{r, echo=FALSE, out.width='25%', fig.align='default', results='asis'}
    beginCentering()
    knitr::include_graphics(paste0(figWD, "/fr.png"))
    cat("\vspace{1cm}")
    cat(" ")
    knitr::include_graphics(paste0(figWD, "/gb.png"))
    endCentering()
    ```

Example: Include markdown syntax between commands \begin and \end in lateX format

  # Your rmarkdown code for a PDF output only
  # % -- command for pandoc trick with \begin and \end -- %
  \newcommand{\nopandoc}[1]{#1}

  \nopandoc{\begin{}}
  Your texte with a **markdown** _syntax_
  \nopandoc{\end}

  # Otherwise, use my functions beginStyleFmt and endStyleFmt
  # with this trick called in the "header" file of your Rmd document

Output files table of content

Complete HTML english version 1. Knit with multiple rendering options - 1.1 A non exhaustive list - 1.2 Functions for html or pdf specific rendering 2. Choose a language to knit - 2.1 Embed text in ‘asis’ chunks + 2.1.1 For titles and subtitles when at the beginning + 2.1.2 And for titles in the middle if there is space line above - 2.2 Include R outputs in conditional chunk + 2.2.1 Example of title in a chunk - 2.3 Conditional images and path + 2.3.1 When images are in a defined directory and are shown in paragraph different that text + 2.3.2 When images are in a changing directory and are shown inline 3. Two images side-by-side and centered 4. Student and teacher versions - 4.1 Create the tutorial roadmap + 4.1.1 Exercise example - 4.2 Purl the rmarkdown file 5. Try this script ! - 5.1 Some limits 6. Supplemental tips

comments powered by Disqus