fmt_markdown: Format Markdown text

In rstudio/gt: Easily Create Presentation-Ready Display Tables

Format Markdown text

Description

Any Markdown-formatted text in the incoming cells will be transformed to the appropriate output type during render when using fmt_markdown().

Usage

fmt_markdown(
  data,
  columns = everything(),
  rows = everything(),
  md_engine = c("markdown", "commonmark")
)

Arguments

data	The gt table data object ⁠obj:<gt_tbl>⁠ // required This is the gt table object that is commonly created through use of the gt() function.
columns	Columns to target <column-targeting expression> // default: everything() Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range() and everything()).
rows	Rows to target <row-targeting expression> // default: everything() In conjunction with columns, we can specify which of their rows should undergo formatting. The default everything() results in all rows in columns being formatted. Alternatively, we can supply a vector of row captions within c(), a vector of row indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()). We can also use expressions to filter down to the rows we need (e.g., ⁠[colname_1] > 100 & [colname_2] < 50⁠).
md_engine	Choice of Markdown engine ⁠singl-kw:[markdown|commonmark]⁠ // default: "markdown" The engine preference for Markdown rendering. By default, this is set to "markdown" where gt will use the markdown package for Markdown conversion to HTML and LaTeX. The other option is "commonmark" and with that the commonmark package will be used.

Value

An object of class gt_tbl.

Compatibility of arguments with the from_column() helper function

from_column() can be used with the md_engine argument of fmt_markdown() to obtain varying parameter values from a specified column within the table. This means that each row could be formatted a little bit differently.

Please note that for this argument (md_engine), a from_column() call needs to reference a column that has data of the character type. Additional columns for parameter values can be generated with cols_add() (if not already present). Columns that contain parameter data can also be hidden from final display with cols_hide().

Examples

Create a few Markdown-based text snippets.

text_1a <- "
### This is Markdown.

Markdown's syntax is comprised entirely of
punctuation characters, which punctuation
characters have been carefully chosen so as
to look like what they mean... assuming
you've ever used email.
"

text_1b <- "
Info on Markdown syntax can be found
[here](https://daringfireball.net/projects/markdown/).
"

text_2a <- "
The **gt** package has these datasets:

 - `countrypops`
 - `sza`
 - `gtcars`
 - `sp500`
 - `pizzaplace`
 - `exibble`
"

text_2b <- "
There's a quick reference [here](https://commonmark.org/help/).
"

Arrange the text snippets as a tibble using dplyr::tribble(), then, create a gt table and format all columns with fmt_markdown().

dplyr::tribble(
  ~Markdown, ~md,
  text_1a,   text_2a,
  text_1b,   text_2b,
) |>
  gt() |>
  fmt_markdown(columns = everything()) |>
  tab_options(table.width = px(400))

fmt_markdown() can also handle LaTeX math formulas enclosed in "$..$" (inline math) and also "$$..$$" (display math). The following table has body cells that contain mathematical formulas in display mode (i.e., the formulas are surrounded by "$$"). Further to this, math can be used within md() wherever there is the possibility to insert text into the table (e.g., with cols_label(), tab_header(), etc.).

dplyr::tibble(
  idx = 1:5,
  l_time_domain =
    c(
      "$$1$$",
      "$${{\\bf{e}}^{a\\,t}}$$",
      "$${t^n},\\,\\,\\,\\,\\,n = 1,2,3, \\ldots$$",
      "$${t^p}, p > -1$$",
      "$$\\sqrt t$$"
    ),
  l_laplace_s_domain =
    c(
      "$$\\frac{1}{s}$$",
      "$$\\frac{1}{{s - a}}$$",
      "$$\\frac{{n!}}{{{s^{n + 1}}}}$$",
      "$$\\frac{{\\Gamma \\left( {p + 1} \\right)}}{{{s^{p + 1}}}}$$",
      "$$\\frac{{\\sqrt \\pi }}{{2{s^{\\frac{3}{2}}}}}$$"
    )
) |>
  gt(rowname_col = "idx") |>
  fmt_markdown() |>
  cols_label(
    l_time_domain = md(
      "Time Domain<br/>$\\small{f\\left( t \\right) =
      {\\mathcal{L}^{\\,\\, - 1}}\\left\\{ {F\\left( s \\right)} \\right\\}}$"
    ),
    l_laplace_s_domain = md(
      "$s$ Domain<br/>$\\small{F\\left( s \\right) =
      \\mathcal{L}\\left\\{ {f\\left( t \\right)} \\right\\}}$"
    )
  ) |>
  tab_header(
    title = md(
      "A (Small) Table of Laplace Transforms &mdash; $\\small{{\\mathcal{L}}}$"
    ),
    subtitle = md(
      "Five commonly used Laplace transforms and formulas.<br/><br/>"
    )
  ) |>
  cols_align(align = "center") |>
  opt_align_table_header(align = "left") |>
  cols_width(
    idx ~ px(50),
    l_time_domain ~ px(300),
    l_laplace_s_domain ~ px(600)
  ) |>
  opt_stylize(
    style = 2,
    color = "gray",
    add_row_striping = FALSE
  ) |>
  opt_table_outline(style = "invisible") |>
  tab_style(
    style = cell_fill(color = "gray95"),
    locations = cells_body(columns = l_time_domain)
  ) |>
  tab_options(
    heading.title.font.size = px(32),
    heading.subtitle.font.size = px(18),
    heading.padding = px(0),
    footnotes.multiline = FALSE,
    column_labels.border.lr.style = "solid",
    column_labels.border.lr.width = px(1)
  )

Function ID

3-27

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

The vector-formatting version of this function: vec_fmt_markdown().

Other data formatting functions: data_color(), fmt(), fmt_auto(), fmt_bins(), fmt_bytes(), fmt_chem(), fmt_country(), fmt_currency(), fmt_date(), fmt_datetime(), fmt_duration(), fmt_email(), fmt_engineering(), fmt_flag(), fmt_fraction(), fmt_icon(), fmt_image(), fmt_index(), fmt_integer(), fmt_number(), fmt_partsper(), fmt_passthrough(), fmt_percent(), fmt_roman(), fmt_scientific(), fmt_spelled_num(), fmt_tf(), fmt_time(), fmt_units(), fmt_url(), sub_large_vals(), sub_missing(), sub_small_vals(), sub_values(), sub_zero()

rstudio/gt documentation built on Dec. 2, 2024, 11:05 a.m.