Why markdown?

The flextable package is an excellent package that allows fine controls on styling tables, and export it to variety of formats (HTML, MS Word, PDF). Especially, when output format is MS Word, this package is the best solution in R.

On the other hand, styling texts with the flextable package often require large efforts. The following example subscripts numeric values in chemical formulas.

df <- data.frame(Oxide = c("SiO2", "Al2O3"), stringsAsFactors = FALSE)
ft <- flextable::flextable(df)

ft %>%
  flextable::compose(
    i = 1, j = "Oxide",
    value = flextable::as_paragraph(
      "SiO", as_sub("2")
    )
  ) %>%
  flextable::compose(
    i = 2, j = "Oxide",
    value = flextable::as_paragraph(
      "Al", as_sub("2"), "O", as_sub("3")
    )
  )

The above example has two problems:

1. This is just a manual re-writing of the table.
   • Basically, users will explicitly input which characters to subscript.
   • For fine formatting, users have to apply compose for each cells one by one.
2. Users have to learn a lot of functions from the flextable package
   • compose, as_paragraph, and as_sub in the above example

The first point can be solved by using a for loop, however, the code becomes quite complex.

df <- data.frame(Oxide = c("SiO2", "Fe2O3"), stringsAsFactors = FALSE)
ft <- flextable::flextable(df)

for (i in seq(nrow(df))) {
  ft <- flextable::compose(
    ft, i = i, j = "Oxide",
    value = flextable::as_paragraph(
      list_values = df$Oxide[i] %>%
        stringr::str_replace_all("([2-9]+)", " \\1 ") %>%
        stringr::str_split(" ", simplify = TRUE) %>%
        purrr::map_if(
          function(x) stringr::str_detect(x, "[2-9]+"),
          flextable::as_sub
        )
    )
  )
}
ft

The ftExtra package provides easy solution by introducing markdown. As markdown texts self-explain their formats by plain texts, what users have to do is manipulations of character columns with their favorite tools such as the famous dplyr and stringr packages.

1. Preprocess a data frame to decorate texts with markdown syntax.
2. Convert the data frame into a flextable object with the flextable function or as_flextable function.
3. Format markdown columns with colformat_md

The following example elegantly simplifies the prior example.

df <- data.frame(Oxide = c("SiO2", "Fe2O3"), stringsAsFactors = FALSE)

df %>%
  dplyr::mutate(Oxide = stringr::str_replace_all(Oxide, "([2-9]+)", "~\\1~")) %>%
  flextable::flextable() %>%
  ftExtra::colformat_md()

The colformat_md function is smart enough to detect character columns, so users can start without learning its arguments. Of course, it is possible to chose columns.

Another workflow is to read a markdown-formatted table from a external file. Again, markdown is by design a plain text, and can easily be embed in any formats such as CSV and Excel. So users can do something like

readr::read_csv("example.csv") %>%
  flextable::flextable() %>%
  ftExtra::colformat_md()

By default, the ftExtra package employs Pandoc’s markdown, which is also employed by R Markdown. This enables consistent user experience when using the ftExtra package in R Markdown.

Basic examples

The example below shows that colformat_md() function parses markdown texts in the flextable object.

data.frame(
  a = c("**bold**", "*italic*"),
  b = c("^superscript^", "~subscript~"),
  c = c("`code`", "[underline]{.underline}"),
  d = c("*[**~ft~^Extra^**](https://ftextra.atusy.net/) is*",
        "[Cool]{.underline shading.color='skyblue'}"),
  stringsAsFactors = FALSE
) %>%
  as_flextable() %>%
  colformat_md()

The table header can also be formatted by specifying part = "header" or "all" to colformat_md()

Supported syntax are

• bold
• italic
• code
• ^superscript
• _subscript
• link
• footnote
• image
• line break
• citations
• math
• attributes with Span, Link, Code, and so on
  • to underline: [foo]{.underline})
  • to color: [foo]{color=red}
  • to highlight: [foo]{shading.color=gray}
  • to change font: [foo]{font.family=Roboto}
  • and the combinations of the above

Note that other syntax may result in unexpected behaviors. The ftExtra package does not support multiple paragraphs or block elements other than the paragraph.

data.frame(
  package = "ftExtra",
  description = "Extensions for 'Flextable'^[Supports of footnotes]",
  stringsAsFactors = FALSE
) %>%
  as_flextable() %>%
  colformat_md() %>%
  flextable::autofit(add_w = 0.5)

data.frame(
  package = "ftExtra^[Short of *flextable extra*]",
  description = "Extensions for 'Flextable'^[Supports of footnotes]"
) %>%
  as_flextable() %>%
  colformat_md(
    .footnote_options = footnote_options(ref = "i",
                                         prefix = '[',
                                         suffix = ']',
                                         start = 2,
                                         inline = TRUE,
                                         sep = "; ")
  ) %>%
  flextable::autofit(add_w = 0.5)

Images

Images can be inserted optionally with width and/or height attributes. Specifying one of them changes the other while keeping the aspect ratio.

data.frame(
  R = sprintf("![](%s)", system.file("img", "Rlogo.jpg", package="jpeg")),
  stringsAsFactors = FALSE
) %>%
  as_flextable() %>%
  colformat_md() %>%
  flextable::autofit()

The R logo is distributed by The R Foundation with the CC-BY-SA 4.0 license.

Line breaks

By default, soft line breaks becomes spaces.

data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>%
  as_flextable() %>%
  colformat_md()

Pandoc’s markdown supports hard line breaks by adding a backslash or double spaces at the end of a line.

data.frame(linebreak = c("a\\\nb"), stringsAsFactors = FALSE) %>%
  as_flextable() %>%
  colformat_md()

It is also possible to make \n as a hard line break by extending Pandoc’s Markdown.

data.frame(linebreak = c("a\nb"), stringsAsFactors = FALSE) %>%
  as_flextable() %>%
  colformat_md(md_extensions = "+hard_line_breaks")

Citations

Citations is experimentally supported. Note that there are no citation lists. It is expected to be produced by using R Markdown.

First, create a ftExtra.bib file like below.

@Manual{R-ftExtra,
  title = {ftExtra: Extensions for Flextable},
  author = {Atsushi Yasumoto},
  note = {https://ftextra.atusy.net, https://github.com/atusy/ftExtra},
  year = {2021},
}

Second, specify it within the YAML front matter. It may also be required to cite references in the nocite field.

---
bibliography: ftExtra.bib
nocite: @R-ftExtra
---

Finally, cite the references within tables.

data.frame(
  Cite = c("@R-ftExtra", "[@R-ftExtra]", "[-@R-ftExtra]"),
  stringsAsFactors = FALSE
) %>%
  as_flextable() %>%
  colformat_md() %>%
  flextable::autofit(add_w = 0.2)

Math

The rendering of math is also possible.

data.frame(math = "$e^{i\\theta} = \\cos \\theta + i \\sin \\theta$",
           stringsAsFactors = FALSE) %>%
  as_flextable() %>%
  colformat_md() %>%
  flextable::autofit(add_w = 0.2)

Note that results can be insufficient. This feature relies on Pandoc’s HTML writer, which

render TeX math as far as possible using Unicode characters
https://pandoc.org/MANUAL.html#math-rendering-in-html

Emoji

Pandoc’s markdown provides an extension, emoji. To use it with colformat_md(), specify md_extensions="+emoji".

data.frame(emoji = c(":+1:"), stringsAsFactors = FALSE) %>%
  as_flextable() %>%
  colformat_md(md_extensions = "+emoji")