` and `` tags. This function either calls
8 | #' [md_fence()] or [md_indent()] based on the `type` argument.
9 | #'
10 | #' @param x A character vector of lines to be wrapped concatenated into a single
11 | #' block, possibly created by [readLines()] or [deparse()].
12 | #' @param ... Arguments to be passed to [md_fence()] or [md_indent()].
13 | #' @param type The type of code block to be created. Either "tick", "tilde"
14 | #' (which call [md_fence()]) or "indent" (which calls [md_indent()]).
15 | #' @return A `glue` object of length 1, with elements of `x` formatted via
16 | #' [md_fence()] or [md_indent()].
17 | #' @family leaf block functions
18 | #' @examples
19 | #' md_chunk("$ sudo apt install r-base-dev", info = "bash")
20 | #' md_indent(
21 | #' n = c(4, 4, 6),
22 | #' x = c(
23 | #' "library(dplyr)",
24 | #' "starwars %>%",
25 | #' "filter(species == 'Droid')"
26 | #' )
27 | #' )
28 | #' @export
29 | md_chunk <- function(x, type = c("tick", "tilde", "indent"), ...) {
30 | type <- match.arg(type)
31 | if (type == "tick") {
32 | md_fence(x, char = "`", ...)
33 | } else {
34 | if (type == "tilde") {
35 | md_fence(x, char = "~", ...)
36 | } else {
37 | md_indent(x, ...)
38 | }
39 | }
40 | }
41 |
42 | #' Markdown indented code block
43 | #'
44 | #' Turn a character vector of lines into a single code block with each line
45 | #' indented four spaces. This markdown leaf block can be rendered as nested HTML
46 | #' `` and `` tags. This is the code block format required by legacy
47 | #' Reddit-flavored Markdown.
48 | #'
49 | #' @details
50 | #' An indented code block is composed of one or more indented chunks separated
51 | #' by blank lines. An indented chunk is a sequence of non-blank lines, each
52 | #' indented four or more spaces. The contents of the code block are the literal
53 | #' contents of the lines, including trailing line endings, minus four spaces of
54 | #' indentation. An indented code block has no info string.
55 | #' @param x A character vector of lines to be wrapped concatenated into a
56 | #' single block, possibly created by [readLines()] or [deparse()].
57 | #' @param n A numeric vector
58 | #' @return A `glue` object of length 1, with the elements of `x` preceded with
59 | #' 4 spaces and separated by a newline.
60 | #' @family leaf block functions
61 | #' @examples
62 | #' md_indent(deparse(md_bold))
63 | #' @importFrom glue glue glue_collapse
64 | #' @export
65 | md_indent <- function(x, n = 4) {
66 | if (min(n) < 4) {
67 | stop("Indented code blocks must be indented by at least four spaces.")
68 | }
69 | glue::glue("{strrep(' ', n)}{x}")
70 | }
71 |
72 | #' Markdown fenced code block
73 | #'
74 | #' Turn a character vector of lines into a single code block with lines
75 | #' bookended with a code fence of backticks or tildes. This markdown leaf block
76 | #' can be rendered as HTML `` tags inside `` tags.
77 | #'
78 | #' @details
79 | #' A code fence is a sequence of at least three consecutive backtick characters
80 | #' ... or tildes (`~`). (Tildes and backticks cannot be mixed.) A fenced code
81 | #' block begins with a code fence, indented no more than three spaces.
82 | #'
83 | #' The line with the opening code fence may optionally contain some text
84 | #' following the code fence; this is trimmed of leading and trailing whitespace
85 | #' and called the info string...
86 | #'
87 | #' The content of the code block consists of all subsequent lines, until a
88 | #' closing code fence of the same type as the code block began with (backticks
89 | #' or tildes), and with at least as many backticks or tildes as the opening code
90 | #' fence...
91 | #'
92 | #' A fenced code block may interrupt a paragraph, and does not require a blank
93 | #' line either before or after.
94 | #'
95 | #' The content of a code fence is treated as literal text, not parsed as
96 | #' inlines. The first word of the info string is typically used to specify the
97 | #' language of the code sample, and rendered in the class attribute of the code
98 | #' tag. However, this spec does not mandate any particular treatment of the info
99 | #' string (see the `info` argument).
100 | #' @param x A character vector of lines to be wrapped concatenated into a single
101 | #' block, possibly created by possibly created by [readLines()] or
102 | #' [deparse()].
103 | #' @param char The character to use in the code fence; either backtick
104 | #' characters... or tildes (`~`). Defaults to backticks.
105 | #' @param info The info string text to follow the initial code fence, typically
106 | #' a code for the language of the lines of `x`. Defaults to `r`.
107 | #' @return A character vector wrapped on either side by code fences.
108 | #' @family leaf block functions
109 | #' @examples
110 | #' md_fence(deparse(sd))
111 | #' md_fence(c("library(dplyr)", "starwars %>%", " filter(species == 'Droid')"))
112 | #' @importFrom glue glue glue_collapse
113 | #' @export
114 | md_fence <- function(x, char = c("`", "~"), info = "r") {
115 | char <- match.arg(char)
116 | if (!is.null(info)) {
117 | if (char == "`" & grepl("`", info)) {
118 | stop("The info string cannot contain any backtick characters.")
119 | }
120 | }
121 | string <- glue_collapse(x, sep = "\n")
122 | fence <- strrep(char, 3)
123 | info <- if (is.null(info)) {
124 | ""
125 | } else {
126 | info
127 | }
128 | glue::glue("{fence}{info}\n{string}\n{fence}")
129 | }
130 |
--------------------------------------------------------------------------------
/R/md-convert.R:
--------------------------------------------------------------------------------
1 | #' Convert markdown to HTML
2 | #'
3 | #' Take a character vector of valid markdown text and pass it to
4 | #' [markdown::markdownToHTML()] to create a glue vector of HTML fragments.
5 | #' Primarily used to test that `md_*()` functions create vectors that meet the
6 | #' GFM spec and can be rendered as HTML.
7 | #'
8 | #' @details
9 | #' GFM enables the `tagfilter` extension, where the following HTML tags will be
10 | #' filtered when rendering HTML output...
11 | #' @param x A character vector of _markdown_ text to be converted.
12 | #' @param frag logical; Whether only a single HTML fragment should be returned.
13 | #' `TRUE` by default.
14 | #' @param disallow logical; Should [md_disallow()] be called on the converted
15 | #' output?
16 | #' @return A `glue` vector of length 1 containing HTML tags.
17 | #' @family inline functions
18 | #' @examples
19 | #' md_convert(x = md_bold("test"))
20 | #' @importFrom glue as_glue
21 | #' @export
22 | md_convert <- function(x, frag = TRUE, disallow = TRUE) {
23 | if (!has_markdown()) {
24 | stop("Package 'markdown' needed for this function to work.")
25 | } else {
26 | html <- markdown::mark_html(text = x, template = !frag, options = c(
27 | "-smart", "-tasklist"
28 | ))
29 | if (disallow) {
30 | md_disallow(html)
31 | } else {
32 | glue::as_glue(html)
33 | }
34 | }
35 | }
36 |
37 | #' Disallow certain raw HTML
38 | #'
39 | #' Take a character vector of raw HTML text (possibly via [md_convert()]) and
40 | #' disallow certain tags by replacing `<` with `<`.
41 | #'
42 | #' @details
43 | #' GFM enables the tagfilter extension, where the following HTML tags will be
44 | #' filtered when rendering HTML output:
45 | #' * ``
46 | #' * `<textarea>`
47 | #' * `<style>`
48 | #' * `<xmp>`
49 | #' * `<iframe>`
50 | #' * `<noembed>`
51 | #' * `<noframes>`
52 | #' * `<script>`
53 | #' * `<plaintext>`
54 | #'
55 | #' Filtering is done by replacing the leading `<` with the entity `<`. These
56 | #' tags are chosen in particular as they change how HTML is interpreted in a way
57 | #' unique to them (i.e. nested HTML is interpreted differently), and this is
58 | #' usually undesireable (sic) in the context of other rendered Markdown content.
59 | #'
60 | #' All other HTML tags are left untouched.
61 | #' @param html A character vector of _markdown_ text to be converted.
62 | #' @return A `glue` vector of length 1 containing HTML tags.
63 | #' @family inline functions
64 | #' @examples
65 | #' md_disallow("<title>GitHub Flavored Markdown Spec ")
66 | #' @importFrom glue as_glue
67 | #' @export
68 | md_disallow <- function(html) {
69 | bad <- c(
70 | "<(title)",
71 | "<(textarea)",
72 | "<(style)",
73 | "<(xmp)",
74 | "<(iframe)",
75 | "<(noembed)",
76 | "<(noframes)",
77 | "<(script)",
78 | "<(plaintext)"
79 | )
80 | for (i in seq_along(bad)) {
81 | html <- gsub(
82 | pattern = bad[[i]],
83 | replacement = "<\\1",
84 | x = html,
85 | ignore.case = TRUE
86 | )
87 | }
88 | glue::as_glue(html)
89 | }
90 |
--------------------------------------------------------------------------------
/R/md-escape.R:
--------------------------------------------------------------------------------
1 | #' Backslash escape all punctuation
2 | #'
3 | #' Take a character vector containing punctuation and return a glue vector with
4 | #' every punctuation mark prepended with double escape backslashes.
5 | #'
6 | #' When trying to format text containing markdown syntax characters, it's
7 | #' necessary to "escape" those characters so that they are ignored by
8 | #' formatting.
9 | #'
10 | #' @details
11 | #' Any ASCII punctuation character may be backslash-escaped... Escaped
12 | #' characters are treated as regular characters and do not have their usual
13 | #' Markdown meanings.
14 | #' @param x A character vector of strings containing punctuation that might
15 | #' accidentally be considered markdown syntax.
16 | #' @return A character string with all `[:punct:]` properly escaped with
17 | #' prepended backslashes.
18 | #' @family inline functions
19 | #' @examples
20 | #' md_escape("# six seasons and a movie")
21 | #' @importFrom glue as_glue
22 | #' @export
23 | md_escape <- function(x) {
24 | glue::as_glue(gsub(pattern = "([[:punct:]])", replacement = "\\\\\\1", x))
25 | }
26 |
--------------------------------------------------------------------------------
/R/md-heading.R:
--------------------------------------------------------------------------------
1 | #' Markdown ATX headings
2 | #'
3 | #' Turn a character vector into a vector of valid markdown ATX headings. These
4 | #' markdown leaf blocks can be rendered as the `` through `` HTML tags.
5 | #' See [md_setext()] to create setext (underlined) headings.
6 | #'
7 | #' @details
8 | #' An ATX heading consists of a string of characters, parsed as inline content,
9 | #' between an opening sequence of 1–6 unescaped `#` characters and an optional
10 | #' closing sequence of any number of unescaped `#` characters. The opening
11 | #' sequence of `#` characters must be followed by a space or by the end of line.
12 | #' The optional closing sequence of `#`s must be preceded by a space and may be
13 | #' followed by spaces only. The opening # character may be indented 0-3 spaces.
14 | #' The raw contents of the heading are stripped of leading and trailing spaces
15 | #' before being parsed as inline content. The heading level is equal to the
16 | #' number of `#` characters in the opening sequence.
17 | #' @param x A character vector of heading text.
18 | #' @param level A numeric vector of use to determine the number of heading hash
19 | #' characters to preceed each element of `x`. The heading level is equal to
20 | #' the number of `#` characters in the opening sequence.
21 | #' @return A `glue` vector of headings with length equal to `x`.
22 | #' @family leaf block functions
23 | #' @examples
24 | #' md_heading("Overview")
25 | #' md_heading(x = c("One", "Two"), level = 1:2)
26 | #' md_heading(x = c("Installation", "Usage"), level = 2)
27 | #' @importFrom glue glue
28 | #' @export
29 | md_heading <- function(x, level = 1) {
30 | if (max(level) > 6 | min(level) < 1) {
31 | stop("ATX headings only support levels 1 through 6.")
32 | }
33 | glue::glue("{strrep('#', level)} {x}")
34 | }
35 |
36 | #' Markdown Setext headings (4.3)
37 | #'
38 | #' Turn a character vector into a vector of valid markdown Setext headings.
39 | #' These markdown leaf blocks can be rendered as the `` and `` tags
40 | #' _only_.
41 | #'
42 | #' @details
43 | #' A setext heading consists of one or more lines of text, each containing at
44 | #' least one non-whitespace character, with no more than 3 spaces indentation,
45 | #' followed by a setext heading underline. The lines of text must be such that,
46 | #' were they not followed by the setext heading underline, they would be
47 | #' interpreted as a paragraph: they cannot be interpretable as a
48 | #' [code fence](https://github.github.com/gfm/#code-fence),
49 | #' [ATX heading](https://github.github.com/gfm/#atx-headings),
50 | #' [block quote](https://github.github.com/gfm/#block-quotes),
51 | #' [thematic break](https://github.github.com/gfm/#thematic-breaks),
52 | #' [list item](https://github.github.com/gfm/#list-items), or
53 | #' [HTML block.](https://github.github.com/gfm/#html-blocks)
54 | #'
55 | #' A setext heading underline is a sequence of `=` characters or a sequence of
56 | #' `-` characters, with no more than 3 spaces indentation and any number of
57 | #' trailing spaces. If a line containing a single `-` can be interpreted as an
58 | #' empty list items, it should be interpreted this way and not as a setext
59 | #' heading underline.
60 | #'
61 | #' The heading is a level 1 heading if `=` characters are used in the setext
62 | #' heading underline, and a level 2 heading if `-` characters are used. The
63 | #' contents of the heading are the result of parsing the preceding lines of text
64 | #' as CommonMark inline content.
65 | #'
66 | #' In general, a setext heading need not be preceded or followed by a blank
67 | #' line. However, it cannot interrupt a paragraph, so when a setext heading
68 | #' comes after a paragraph, a blank line is needed between them.
69 | #' @param x A character vector of heading text.
70 | #' @param level An numeric vector of all either 1 or 2 to determine whether
71 | #' level 1 headings are created with `=` or level two with `-`. If less levels
72 | #' are provided than headings, `level` will be repeated via [glue::glue()].
73 | #' @param width logical or integer; if `TRUE` the width will be automatically
74 | #' determined by the width of the longest line in `x`. If an integer, the
75 | #' setext underline will be that wide.
76 | #' @return A `glue` vector of headings with length equal to `x`.
77 | #' @importFrom glue glue glue_collapse
78 | #' @family leaf block functions
79 | #' @examples
80 | #' md_setext("Overview")
81 | #' md_setext("This is a setext\nheading", level = 2)
82 | #' md_setext(c("one", "two", "three", "four"), level = c(1, 2))
83 | #' md_setext("Installation", level = 2, width = 55)
84 | #' @export
85 | md_setext <- function(x, level = 1, width = TRUE) {
86 | if (any(x == "")) {
87 | stop("Setext headings cannot be empty.")
88 | }
89 | char <- if (max(level) > 2 | min(level) < 1) {
90 | stop("Setext headings only support levels 1 and 2.")
91 | } else {
92 | char <- c("=", "-")[level]
93 | }
94 | n <- if ((all(is.logical(width)) & isTRUE(width)) | min(width) < 1) {
95 | vapply(strsplit(x, "\n"), function(y) max(nchar(y)), FUN.VALUE = integer(1))
96 | } else {
97 | width
98 | }
99 | glue::glue("{x}\n{strrep(char, n)}")
100 | }
101 |
--------------------------------------------------------------------------------
/R/md-inlines.R:
--------------------------------------------------------------------------------
1 | #' Markdown code span
2 | #'
3 | #' Take a character vector and wrap each element in backticks to create a glue
4 | #' vector of inline code spans. This inline is rendered as a `` HTML tag.
5 | #'
6 | #' @details
7 | #' A backtick string is a string of one or more backtick characters that is
8 | #' neither preceded nor followed by a backtick.
9 | #'
10 | #' A code span begins with a backtick string and ends with a backtick string
11 | #' of equal length. The contents of the code span are the characters between
12 | #' the two backtick strings, normalized in the following ways: * First, line
13 | #' endings are converted to spaces. * If the resulting string both begins and
14 | #' ends with a space character, but does not consist entirely of space
15 | #' characters, a single space character is removed from the front and back.
16 | #' This allows you to include code that begins or ends with backtick
17 | #' characters, which must be separated by whitespace from the opening or
18 | #' closing backtick strings.
19 | #' @param x The text to be formatted as fixed-width inline code.
20 | #' @return A `glue` vector of length equal to `x`.
21 | #' @family inline functions
22 | #' @examples
23 | #' md_code("ex_var")
24 | #' md_code(state.name[1:3])
25 | #' @importFrom glue glue
26 | #' @export
27 | md_code <- function(x) {
28 | if (any(grepl("`", x))) {
29 | glue::glue("`` {x} ``")
30 | } else {
31 | glue::glue("`{x}`")
32 | }
33 | }
34 |
35 | #' Markdown bold emphasis
36 | #'
37 | #' Take a character vector and wrap each element in double asterisks to create a
38 | #' glue vector of bold emphasis text. This inline is rendered as the ``
39 | #' HTML tag.
40 | #'
41 | #' @details
42 | #' A double `**` or `__` can open or close emphasis... Emphasis begins with a
43 | #' delimiter that can open emphasis and ends with a delimiter that can close
44 | #' emphasis, and that uses the same character (`__` or `**`) as the opening
45 | #' delimiter.
46 | #' @param x The text to be emphasized in bold.
47 | #' @return A `glue` vector of length equal to `x`.
48 | #' @family inline functions
49 | #' @examples
50 | #' md_bold("Example")
51 | #' md_bold(state.name)
52 | #' @importFrom glue glue
53 | #' @export
54 | md_bold <- function(x) {
55 | glue::glue("**{x}**")
56 | }
57 |
58 | #' Markdown italic emphasis
59 | #'
60 | #' Take a character vector and wrap each element in single underscores to create
61 | #' a glue vector of italic emphasis text. This inline is rendered as the ``
62 | #' HTML tag.
63 | #'
64 | #' @details
65 | #' A single `*` or `_` can open or close emphasis... Emphasis begins with a
66 | #' delimiter that can open emphasis and ends with a delimiter that can close
67 | #' emphasis, and that uses the same character (`_` or `*`) as the opening
68 | #' delimiter.
69 | #' @param x The text to be emphasized in italics.
70 | #' @return A `glue` vector of length equal to `x`.
71 | #' @family inline functions
72 | #' @examples
73 | #' md_italic("Example")
74 | #' md_italic(state.name)
75 | #' @importFrom glue glue
76 | #' @export
77 | md_italic <- function(x) {
78 | glue::glue("_{x}_")
79 | }
80 |
81 | #' Markdown strikethrough (extension)
82 | #'
83 | #' Take a character vector and wrap each element in tildes to create a glue
84 | #' vector of strikethrough text. This inline is rendered as the `` HTML
85 | #' tag.
86 | #'
87 | #' @details
88 | #' GFM enables the strikethrough extension, where an additional emphasis type is
89 | #' available. Strikethrough text is any text wrapped in two tildes (`~`).
90 | #' @param x A character vector of text to be striked through.
91 | #' @return A `glue` vector of length equal to `x`.
92 | #' @family inline functions
93 | #' @family markdown extensions
94 | #' @examples
95 | #' md_strike("Example")
96 | #' md_strike(state.name[1:3])
97 | #' @importFrom glue glue
98 | #' @export
99 | md_strike <- function(x) {
100 | glue::glue("~~{x}~~")
101 | }
102 |
--------------------------------------------------------------------------------
/R/md-issue.R:
--------------------------------------------------------------------------------
1 | #' Markdown GitHub issue
2 | #'
3 | #' Take a character vector and numeric vector and concatenate them into a glue
4 | #' vector of valid GitHub issue autolinks (username/repo#issue).
5 | #'
6 | #' @details
7 | #' Within conversations on GitHub, references to issues and pull requests are
8 | #' [automatically converted to shortened links](https://git.io/Jvtb9).
9 | #' @param repo A character vector in the format `"user/rep"`.
10 | #' @param num The issue or pull number _without_ hash symbol.
11 | #' @return A character vector which GitHub can automatically hyperlink.
12 | #' @family inline functions
13 | #' @family markdown extensions
14 | #' @examples
15 | #' md_issue("k5cents/gluedown", 1:5)
16 | #' @export
17 | md_issue <- function(repo, num) {
18 | if (suppressWarnings(any(is.na(as.numeric(num))))) {
19 | stop("The num must be coercible to numeric.")
20 | }
21 | if (!grepl("/", repo)) {
22 | warning("use the \"user/repo\" format")
23 | }
24 | glue::glue("{repo}#{num}")
25 | }
26 |
--------------------------------------------------------------------------------
/R/md-lines.R:
--------------------------------------------------------------------------------
1 | #' Markdown soft line breaks
2 | #'
3 | #' Take a character vector and return a glue vector of separated by a single
4 | #' newline. This inline is rendered as single `` HTML tags.
5 | #'
6 | #' @details
7 | #' A regular line break (not in a code span or HTML tag) that is not preceded by
8 | #' two or more spaces or a backslash is parsed as a softbreak. (A softbreak may
9 | #' be rendered in HTML either as a line ending or as a space. The result will be
10 | #' the same in browsers. In the examples here, a line ending will be used.)
11 | #' @param ... Any number of character vectors.
12 | #' @return A `glue` vector with elements of `...` separated by a single newline.
13 | #' @family inline functions
14 | #' @examples
15 | #' # compare the following
16 | #' md_bold(c("One", "Two"))
17 | #'
18 | #' md_softline(md_bold(c("One", "Two")))
19 | #' @importFrom glue glue_collapse
20 | #' @export
21 | md_softline <- function(...) {
22 | dots <- unlist(list(...))
23 | glue::glue("{dots}\n")
24 | }
25 |
26 | #' Markdown hard line breaks
27 | #'
28 | #' Take a character vector and return a collapsed glue vector with each original
29 | #' element separated by two spaces and a newline. This inline is rendered with a
30 | #' `
` HTML tag.
31 | #'
32 | #' @details
33 | #' A line break (not in a code span or HTML tag) that is preceded by two or more
34 | #' spaces and does not occur at the end of a block is parsed as a hard line
35 | #' break (rendered in HTML as a `
` tag)
36 | #' @param ... Any number of character vectors.
37 | #' @return A `glue` vector with elements of `...` separated by two trailing
38 | #' spaces and a single newline.
39 | #' @family inline functions
40 | #' @examples
41 | #' # compare the following
42 | #' md_bold(c("One", "Two"))
43 | #' md_hardline(md_bold(c("One", "Two")), md_italic("Three"))
44 | #' @importFrom glue glue_collapse
45 | #' @export
46 | md_hardline <- function(...) {
47 | dots <- unlist(list(...))
48 | glue::glue("{dots} \n")
49 | }
50 |
51 | #' Markdown paragraphs breaks
52 | #'
53 | #' Take a character vector and return a glue vector of paragraphs separated by
54 | #' double newlines. This leaf block is rendered as distinct `
` HTML tags.
55 | #'
56 | #' @details
57 | #' A sequence of non-blank lines that cannot be interpreted as other kinds of
58 | #' blocks forms a paragraph. The contents of the paragraph are the result of
59 | #' parsing the paragraph’s raw content as inlines. The paragraph’s raw content
60 | #' is formed by concatenating the lines and removing initial and final
61 | #' whitespace... Paragraphs can contain multiple lines, but no blank lines.
62 | #' @param ... Any number of character vectors.
63 | #' @return A `glue` vector with elements of `...` separated by two newlines.
64 | #' @family leaf block functions
65 | #' @examples
66 | #' md_paragraph(stringr::sentences[1:3])
67 | #' @importFrom glue glue
68 | #' @export
69 | md_paragraph <- function(...) {
70 | dots <- unlist(list(...))
71 | glue::glue("{dots}\n\n")
72 | }
73 |
74 | #' Markdown blank line
75 | #'
76 | #' Create a blank line between other markdown block-level elements.
77 | #'
78 | #' @details
79 | #' Blank lines between block-level elements are ignored, except for the role
80 | #' they play in determining whether a list is tight or loose.
81 | #'
82 | #' Blank lines at the beginning and end of the document are also ignored.
83 | #' @return A `glue` vector of length one containing two newline characters.
84 | #' @family leaf block functions
85 | #' @examples
86 | #' md_blank
87 | #' @importFrom glue glue
88 | #' @export
89 | md_blank <- function() {
90 | glue::glue("\n")
91 | }
92 |
--------------------------------------------------------------------------------
/R/md-link.R:
--------------------------------------------------------------------------------
1 | #' Markdown inline link (6.6)
2 | #'
3 | #' Take character vectors of link texts, link destinations, and optional titles
4 | #' and return single glue vector of valid markdown inline links. This inline is
5 | #' rendered as the `` HTML tag.
6 | #'
7 | #' @details
8 | #' A link contains link text (the visible text), a link destination (the URI
9 | #' that is the link destination), and optionally a link title. There are two
10 | #' basic kinds of links in Markdown. In inline links the destination and title
11 | #' are given immediately after the link text.
12 | #'
13 | #' A link text consists of a sequence of zero or more inline elements enclosed
14 | #' by square brackets (`[` and `]`)...
15 | #'
16 | #' An inline link consists of a link text followed immediately by a left
17 | #' parenthesis `(`, optional whitespace, an optional link destination, an
18 | #' optional link title separated from the link destination by whitespace,
19 | #' optional whitespace, and a right parenthesis `)`. The link’s text consists of
20 | #' the inlines contained in the link text (excluding the enclosing square
21 | #' brackets). The link’s URI consists of the link destination, excluding
22 | #' enclosing `<...>` if present, with backslash-escapes in effect as described
23 | #' above. The link’s title consists of the link title, excluding its enclosing
24 | #' delimiters, with backslash-escapes in effect as described above.
25 | #' @param text A character vector of text with another vector of URLs passed to
26 | #' the `url` argument.
27 | #' @param url A character vector of URLs.
28 | #' @param title The optional title of the link.
29 | #' @param ... A sequence of `text = "/url"` named vector pairs. If any such
30 | #' pairs are provided, `.name` will be considered `TRUE`.
31 | #' @param .name logical; if `TRUE`, the pairs in `...` will be used instead of
32 | #' any values supplied to `x` and `url`.
33 | #' @return A `glue` vector of collapsed display text and associated URLs.
34 | #' @family inline functions
35 | #' @examples
36 | #' md_link(1:5, glue::glue("https://{state.abb[1:5]}.gov"), state.name[1:5])
37 | #' md_link(CRAN = "https://cran.r-project.org/")
38 | #' @importFrom glue glue
39 | #' @export
40 | md_link <- function(text, url, title = NULL, ..., .name = FALSE) {
41 | x <- unlist(list(...))
42 | if (!is.null(x) | .name) {
43 | glue::glue("[{names(x)}]({unlist(x)})")
44 | } else if (!is.null(title)) {
45 | glue::glue("[{text}]({url} \"{title}\")")
46 | } else {
47 | glue::glue("[{text}]({url})")
48 | }
49 | }
50 |
51 |
52 | #' Markdown image links
53 | #'
54 | #' Take character vectors of alternative text, image link destinations, and
55 | #' optional titles and return single glue vector of valid markdown inline image
56 | #' links. This inline is rendered as the `![]()
` HTML tag. Note that the
57 | #' expected arguments of `md_image()` are reversed from `md_link()`
58 | #'
59 | #' @details
60 | #' Syntax for images is like the syntax for links, with one difference. Instead
61 | #' of link text, we have an image description. The rules for this are the same
62 | #' as for link text, except that (a) an image description starts with `})")
89 | } else {
90 | glue::glue("})")
91 | }
92 | } else if (!is.null(title)) {
93 | glue::glue("![{alt}]({url} \"{title}\")")
94 | } else {
95 | glue::glue("")
96 | }
97 | }
98 |
99 | #' Markdown link label
100 | #'
101 | #' Create the link labels that can latter be referred to with a link reference
102 | #' from [md_reference()].
103 | #'
104 | #' @details
105 | #' A link label begins with a left bracket and ends with the first right bracket
106 | #' that is not backslash-escaped. Between these brackets there must be at least
107 | #' one non-whitespace character.
108 | #' @param text The text in the document to be hyperlinked.
109 | #' @param label A link label that is referenced elsewhere in the document.
110 | #' @param ... A sequence of `label = "text"` named vector pairs. If any such
111 | #' pairs are provided, `.name` will be considered `TRUE`.
112 | #' @param .name logical; if `TRUE`, the pairs in `...` will be used instead of
113 | #' any values supplied to `x` and `url`.
114 | #' @return A single `glue` vector of length equal to that of `label` and `url`,
115 | #' with elements the concatenated arguments.
116 | #' @family leaf block functions
117 | #' @examples
118 | #' md_label(CRAN = "The CRAN website")
119 | #' md_label(text = c("one", "two"), label = 1:2)
120 | #' @export
121 | md_label <- function(text, label, ..., .name = FALSE) {
122 | x <- unlist(list(...))
123 | if (!is.null(x) | .name) {
124 | glue::glue("[{unlist(x)}][{names(x)}]")
125 | } else {
126 | glue::glue("[{text}][{label}]")
127 | }
128 | }
129 |
130 | #' Markdown link reference
131 | #'
132 | #' Take character vectors of link texts, link destinations, and optional titles
133 | #' and return single glue vector of valid markdown link references. This
134 | #' markdown leaf block then uses the `label` placed _elsewhere_ in a markdown
135 | #' document to render `` HTML tags.
136 | #'
137 | #' @details
138 | #' A full reference link (6.6) consists of a link text immediately followed by a
139 | #' link label that matches a link reference definition elsewhere in the
140 | #' document...
141 | #'
142 | #' A link reference definition consists of a link label, indented up to three
143 | #' spaces, followed by a colon (`:`), optional whitespace (including up to one
144 | #' line ending), a link destination, optional whitespace (including up to one
145 | #' line ending), and an optional link title, which if it is present must be
146 | #' separated from the link destination by whitespace. No further non-whitespace
147 | #' characters may occur on the line.
148 | #'
149 | #' A link reference definition does not correspond to a structural element of a
150 | #' document. Instead, it defines a label which can be used in reference links
151 | #' and reference-style images elsewhere in the document. Link reference
152 | #' definitions can come either before or after the links that use them.
153 | #' @param label A link label that is referenced elsewhere in the document.
154 | #' @param url The URL to hyperlink the referenced text with.
155 | #' @param title An _optional_ link title; defaults to `NULL`.
156 | #' @param ... A sequence of `label = "/url"` named vector pairs. If any such
157 | #' pairs are provided, `.name` will be considered `TRUE`.
158 | #' @param .name logical; if `TRUE`, the pairs in `...` will be used instead of
159 | #' any values supplied to `x` and `url`.
160 | #' @return A single `glue` vector of length equal to that of `label` and `url`,
161 | #' with elements the concatenated arguments.
162 | #' @family leaf block functions
163 | #' @examples
164 | #' md_reference(CRAN = "https://cran.r-project.org/")
165 | #' md_reference(label = 1:2, url = c("https://one.org", "https://two.com"))
166 | #' md_reference("tv", "https://www.tidyverse.org/", title = "tidyverse")
167 | #' @export
168 | md_reference <- function(label, url, title = NULL, ..., .name = FALSE) {
169 | x <- unlist(list(...))
170 | if (!is.null(x) | .name) {
171 | glue::glue("[{names(x)}]: {unlist(x)}")
172 | } else if (!is.null(title)) {
173 | glue::glue("[{label}]: {url} \"{title}\"")
174 | } else {
175 | glue::glue("[{label}]: {url}")
176 | }
177 | }
178 |
--------------------------------------------------------------------------------
/R/md-list.R:
--------------------------------------------------------------------------------
1 | #' Markdown generic list
2 | #'
3 | #' Turn a character vector into a valid markdown list block. This is a generic
4 | #' function that calls [md_bullet()], [md_order()], or [md_task()] depending on
5 | #' what string is provided in the `type` argument.
6 | #'
7 | #' @param x A character vector of list items.
8 | #' @param type The type of list to create; either bullet, ordered, or task.
9 | #' @param ... Arguments passed to the appropriate list type function.
10 | #' @return A `glue` vector with length equal to `x`.
11 | #' @family container block functions
12 | #' @examples
13 | #' md_list(state.name[1:5], type = "bullet", marker = "+")
14 | #' md_list(state.name[6:10], type = "ordered", marker = ")")
15 | #' md_list(state.name[11:15], type = "task", check = 3:5)
16 | #' @export
17 | md_list <- function(x, type = c("bullet", "ordered", "task"), ...) {
18 | type <- match.arg(type)
19 | if (type == "bullet") {
20 | md_bullet(x, ...)
21 | } else {
22 | if (type == "ordered") {
23 | md_order(x, ...)
24 | } else {
25 | md_task(x, ...)
26 | }
27 | }
28 | }
29 |
30 | #' Markdown bullet list
31 | #'
32 | #' take a character vector and return a glue vector of valid bullet list items.
33 | #' When printed together, these bullet list items create a bullet list. This
34 | #' container block is rendered as the `` HTML tag, with each element of the
35 | #' vector creating a separate `- ` tag.
36 | #'
37 | #' @details
38 | #' A list is a sequence of one or more list items of the same type. The list
39 | #' items may be separated by any number of blank lines.
40 | #'
41 | #' Two list items are of the same type if they begin with a list marker of the
42 | #' same type. Two list markers are of the same type if (a) they are bullet list
43 | #' markers using the same character (`-`, `+`, or `*`)...
44 | #' @param x The vector of bullet point list items.
45 | #' @param marker The bullet list marker to use; one of `-`, `+`, or `*`.
46 | #' @return A `glue` vector with length equal to `x`.
47 | #' @family container block functions
48 | #' @examples
49 | #' md_bullet(state.name[1:5])
50 | #' md_bullet(sample(state.name, 5), marker = "+")
51 | #' @importFrom glue glue
52 | #' @export
53 | md_bullet <- function(x, marker = c("*", "-", "+")) {
54 | marker <- match.arg(marker)
55 | glue::glue("{marker} {x}")
56 | }
57 |
58 | #' Markdown ordered list
59 | #'
60 | #' take a character vector and return a glue vector of valid ordered list items.
61 | #' When printed together, these ordered list items create a ordered list. This
62 | #' container block is rendered as the `
` HTML tag, with each element of the
63 | #' vector creating a separate `- ` tag.
64 | #'
65 | #' @details
66 | #' A list is a sequence of one or more list items of the same type. The list
67 | #' items may be separated by any number of blank lines.
68 | #'
69 | #' Two list items are of the same type if they begin with a list marker of the
70 | #' same type. Two list markers are of the same type if (b) they are ordered list
71 | #' numbers with the same delimiter (either `.` or `)`).
72 | #'
73 | #' A list is an ordered list if its constituent list items begin with ordered
74 | #' list markers, and a bullet list if its constituent list items begin with
75 | #' bullet list markers.
76 | #'
77 | #' The start number of an ordered list is determined by the list number of its
78 | #' initial list item. The numbers of subsequent list items are disregarded.
79 | #' @param x The vector of numbered list items.
80 | #' @param seq logical; Should sequential numbers be used? Defaults to `TRUE`. If
81 | #' `FALSE`, each element will be preceded by the number one; many markdown
82 | #' engines will automatically render repeated ones as a sequential list.
83 | #' @param pad logical; If sequential numbers are used, should they be padded
84 | #' with zeroes on the left to match the width of the greatest number? Defaults
85 | #' to `TRUE`.
86 | #' @param marker The ordered list marker following each arabic digits; either
87 | #' `.` or `)`.
88 | #' @return A `glue` vector with length equal to `x`.
89 | #' @family container block functions
90 | #' @examples
91 | #' md_order(state.name[1:5])
92 | #' md_order(sample(state.name, 5), marker = ")")
93 | #' md_order(sample(state.name, 5), seq = FALSE)
94 | #' @importFrom glue glue
95 | #' @export
96 | md_order <- function(x, marker = c(".", ")"), seq = TRUE, pad = TRUE) {
97 | marker <- match.arg(marker)
98 | if (seq) {
99 | nums <- seq_along(x)
100 | if (pad) {
101 | width <- max(nchar(nums))
102 | nums <- sprintf(glue::glue("%0{width}d"), nums)
103 | }
104 | } else {
105 | nums <- 1
106 | }
107 | glue::glue("{nums}{marker} {x}")
108 | }
109 |
110 | #' Markdown task list (extension)
111 | #'
112 | #' take a character vector and return a glue vector of valid bullet list items.
113 | #' When printed together, these bullet list items create a bullet list. This
114 | #' container block is rendered as the `
` HTML tag, with each element of the
115 | #' vector creating a separate `- ` tag. On venues supporting GitHub Flavored
116 | #' Markdown, this list will be specially rendered with the list item market
117 | #' replaces with a `` HTML tag.
118 | #'
119 | #' @details
120 | #' GFM enables the tasklist extension, where an additional processing step is
121 | #' performed on list items.
122 | #'
123 | #' A task list item is a list item where the first block in it is a paragraph
124 | #' which begins with a task list item marker and at least one whitespace
125 | #' character before any other content.
126 | #'
127 | #' A task list item marker consists of an optional number of spaces, a left
128 | #' bracket, either a whitespace character or the letter `x` in either
129 | #' lowercase or uppercase, and then a right bracket.
130 | #'
131 | #' When rendered, the task list item marker is replaced with a semantic checkbox
132 | #' element; in an HTML output, this would be an ``
133 | #' element.
134 | #'
135 | #' If the character between the brackets is a whitespace character, the checkbox
136 | #' is unchecked. Otherwise, the checkbox is checked.
137 | #'
138 | #' This spec does not define how the checkbox elements are interacted with: in
139 | #' practice, implementors are free to render the checkboxes as disabled or
140 | #' inmutable elements, or they may dynamically handle dynamic interactions (i.e.
141 | #' checking, unchecking) in the final rendered document.
142 | #' @param x A character vector of task list items.
143 | #' @param check A optional numeric vector of list elements which should be
144 | #' checked off.
145 | #' @return A `glue` vector with length equal to `x`.
146 | #' @family container block functions
147 | #' @examples
148 | #' md_task(c("Wake up", "Eat Breakfast", "Brush Teeth"), check = c(1, 3))
149 | #' @importFrom glue glue
150 | #' @export
151 | md_task <- function(x, check = NULL) {
152 | boxes <- rep("* [ ]", length(x))
153 | if (!is.null(check)) {
154 | boxes[check] <- "* [x]"
155 | }
156 | glue::glue("{boxes} {x}")
157 | }
158 |
--------------------------------------------------------------------------------
/R/md-quote.R:
--------------------------------------------------------------------------------
1 | #' Markdown block quotes
2 | #'
3 | #' Take a character vector and prepend each element in a greater-than symbol to
4 | #' create a glue vector of block quote markdown text. This inline is rendered as
5 | #' a `
` HTML tag.
6 | #'
7 | #' @details
8 | #' A block quote marker consists of 0-3 spaces of initial indent, plus (a) the
9 | #' character `>` together with a following space, or (b) a single character `>`
10 | #' not followed by a space.
11 | #'
12 | #' The following rules define block quotes:
13 | #' 1. **Basic case.** If a string of lines _Ls_ constitute a sequence of blocks
14 | #' _Bs_, then the result of prepending a block quote marker to the beginning of
15 | #' each line in _Ls_ is a block quote containing _Bs_.
16 | #' 2. **Laziness.** If a string of lines _Ls_ constitute a block quote with
17 | #' contents _Bs_, then the result of deleting the initial block quote marker
18 | #' from one or more lines in which the next non-whitespace character after the
19 | #' block quote marker is paragraph continuation text is a block quote with _Bs_
20 | #' as its content. Paragraph continuation text is text that will be parsed as
21 | #' part of the content of a paragraph, but does not occur at the beginning of
22 | #' the paragraph.
23 | #' 3. **Consecutiveness.** A document cannot contain two block quotes in a row
24 | #' unless there is a blank line between them.
25 | #'
26 | #' Nothing else counts as a block quote.
27 | #' @param x The character vector of quotes.
28 | #' @return A character vector with a greater-than symbol (`>`) prepended to each
29 | #' element.
30 | #' @family container block functions
31 | #' @examples
32 | #' md_quote("Give me liberty, or give me death!")
33 | #' md_quote(stringr::sentences[1:3])
34 | #' @export
35 | md_quote <- function(x) {
36 | glue::glue("> {x}")
37 | }
38 |
--------------------------------------------------------------------------------
/R/md-rule.R:
--------------------------------------------------------------------------------
1 | #' Markdown horizontal rule (4.1)
2 | #'
3 | #' Create a glue vector of characters used to represent a _thematic break_. This
4 | #' markdown leaf block is rendered as the `
` HTML tag.
5 | #'
6 | #' @details
7 | #' A line consisting of 0-3 spaces of indentation, followed by a sequence of
8 | #' three or more matching `-`, `_`, or `*` characters, each followed optionally
9 | #' by any number of spaces or tabs, forms a thematic break.
10 | #' @param char The type of rule; either: `-`, `_`, or `*`. Defaults to `*`.
11 | #' @param n The width of the rule; an integer indicating number of times to
12 | #' repeat each character. Defaults to the minimum of 3.
13 | #' @param space logical or numeric; How many spaces to place between each
14 | #' `char`. Defaults to `FALSE`, which places 0 spaces.
15 | #' @return A repeated-character `glue` vector with length 1.
16 | #' @family leaf block functions
17 | #' @examples
18 | #' md_rule()
19 | #' md_rule("_")
20 | #' md_rule(n = 10)
21 | #' md_rule(space = TRUE)
22 | #' @importFrom glue glue_collapse
23 | #' @export
24 | md_rule <- function(char = c("*", "-", "_"), n = 3, space = FALSE) {
25 | if (n < 3) {
26 | stop("At least 3 characters must be used")
27 | }
28 | char <- match.arg(char)
29 | spaces <- glue::glue_collapse(rep(" ", as.numeric(space)))
30 | if (length(spaces) == 0) {
31 | sep <- ""
32 | } else {
33 | sep <- spaces
34 | }
35 | glue::glue_collapse(rep(char, n), sep = sep)
36 | }
37 |
38 |
--------------------------------------------------------------------------------
/R/md-table.R:
--------------------------------------------------------------------------------
1 | #' Markdown tables (4.10 extension)
2 | #'
3 | #' Take a list of data frames or matrices and pass them to [knitr::kable()] to
4 | #' create a glue vector containing valid markdown tables.
5 | #'
6 | #' @details
7 | #' FM enables the `table` extension, where an additional leaf block type is
8 | #' available.
9 | #'
10 | #' A table is an arrangement of data with rows and columns, consisting of a
11 | #' single header row, a delimiter row separating the header from the data, and
12 | #' zero or more data rows.
13 | #'
14 | #' Each row consists of cells containing arbitrary text, in which
15 | #' [inlines](https://github.github.com/gfm/#inline) are parsed, separated by
16 | #' pipes (`|`). A leading and trailing pipe is also recommended for clarity of
17 | #' reading, and if there’s otherwise parsing ambiguity. Spaces between pipes and
18 | #' cell content are trimmed. Block-level elements cannot be inserted in a table.
19 | #'
20 | #' The delimiter row consists of cells whose only content are hyphens (`-`), and
21 | #' optionally, a leading or trailing colon (`:`), or both, to indicate left,
22 | #' right, or center alignment respectively (see `align` in [knitr::kable()]).
23 | #' @param x An `R` object to be formatted as a table.
24 | #' @param ... Arguments passed to [knitr::kable()]
25 | #' @return A `glue` vector of length one, with each element or row of `x`
26 | #' separated by a newline.
27 | #' @family leaf block functions
28 | #' @family markdown extensions
29 | #' @examples
30 | #' md_table(mtcars)
31 | #' md_table(data.frame(x = LETTERS[1:3], y = 1:3), align = c("cc"))
32 | #' @importFrom glue glue_collapse
33 | #' @export
34 | md_table <- function(x, ...) {
35 | if (has_knitr()) {
36 | table <- knitr::kable(x, format = "markdown", ...)
37 | } else {
38 | x <- as.matrix(x)
39 | x <- rbind(colnames(x), x)
40 | x <- cbind(rownames(x), x)
41 | x[is.na(x)] <- "NA"
42 | if (nrow(x) >= 2) {
43 | x <- apply(x, 2, function(z) sprintf(glue::glue("%-{max(nchar(z))}s"), z))
44 | }
45 | s <- strrep("-", apply(x, 2, function(z) max(nchar(z))))
46 | num_cols <- vapply(x, is.numeric, logical(1))
47 | s <- gsub("^-", ":", s)
48 | if (nrow(x) >= 2) {
49 | x <- rbind(x[1, ], unname(s), x[2:nrow(x), ])
50 | } else {
51 | x <- rbind(x[1, ], s)
52 | }
53 | x <- cbind("", x, "")
54 | table <- trimws(apply(x, 1, paste, collapse = " | "))
55 | }
56 | glue::glue_collapse(table, sep = "\n")
57 | }
58 |
--------------------------------------------------------------------------------
/R/md-text.R:
--------------------------------------------------------------------------------
1 | #' Markdown textual content
2 | #'
3 | #' Simple wrapper around [glue::as_glue()]. Take a character vector and return a
4 | #' glue vector.
5 | #'
6 | #' @details
7 | #' Any characters not given an interpretation by the \[other\] rules will be
8 | #' parsed as plain textual content.
9 | #' @param x A character vector.
10 | #' @return A `glue` vector.
11 | #' @family inline functions
12 | #' @examples
13 | #' md_text("foo")
14 | #' @importFrom glue as_glue
15 | #' @export
16 | md_text <- function(x) {
17 | glue::as_glue(x)
18 | }
19 |
--------------------------------------------------------------------------------
/R/utils.R:
--------------------------------------------------------------------------------
1 | #' Pipe operator
2 | #'
3 | #' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
4 | #'
5 | #' @name %>%
6 | #' @rdname pipe
7 | #' @keywords internal
8 | #' @export
9 | #' @importFrom magrittr %>%
10 | #' @usage lhs \%>\% rhs
11 | NULL
12 |
13 | is_installed <- function(pkg) {
14 | isTRUE(requireNamespace(pkg, quietly = TRUE))
15 | }
16 |
17 | #' Check if the user has the 'knitr' package installed
18 | #' @export
19 | has_knitr <- function() {
20 | is_installed(pkg = "knitr")
21 | }
22 |
23 | #' @rdname has_knitr
24 | #' @export
25 | has_markdown <- function() {
26 | is_installed(pkg = "markdown")
27 | }
28 |
29 | find_nodes <- function(md, node) {
30 | rvest::html_nodes(xml2::read_html(md_convert(md)), node)
31 | }
32 |
33 | expect_empty <- function(object) {
34 | testthat::expect_true(length(object) == 0)
35 | }
36 |
37 | expect_full <- function(object) {
38 | testthat::expect_true(length(object) != 0)
39 | }
40 |
41 | expect_nchar <- function(object, n) {
42 | testthat::expect_true(nchar(object) == n)
43 | }
44 |
45 | expect_missing <- function(object) {
46 | testthat::expect_true(is.na(object))
47 | }
48 |
--------------------------------------------------------------------------------
/README.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | output: github_document
3 | ---
4 |
5 |
6 |
7 | ```{r, include = FALSE}
8 | knitr::opts_chunk$set(
9 | collapse = TRUE,
10 | comment = "#>",
11 | fig.path = "man/figures/README-",
12 | out.width = "100%"
13 | )
14 | ```
15 |
16 | # gluedown 
17 |
18 |
19 | [![Lifecycle: experimental][life_badge]][life_link]
20 | [![CRAN status][cran_badge]][cran_link]
21 | ![Downloads][dl_badge]
22 | [![Codecov test coverage][cov_badge]][cov_link]
23 | [![R build status][ga_badge]][ga_link]
24 |
25 |
26 | The goal of `gluedown` is to ease the transition from R's powerful vectors to
27 | formatted markdown text. The package uses [`glue()`][glue] to wrap character
28 | vectors in markdown syntax. With the [`knitr`][knitr] package, users can print
29 | the formatted vectors directly to the body of a markdown document.
30 |
31 | ## Installation
32 |
33 | Install the release version from [CRAN][cran]:
34 |
35 | ```{r release, eval=FALSE}
36 | install.packages("gluedown")
37 | ```
38 |
39 | The development version can be installed from [GitHub][gh]:
40 |
41 | ```{r develop, eval=FALSE}
42 | # install.packages("remotes")
43 | remotes::install_github("k5cents/gluedown")
44 | ```
45 |
46 | ## Usage
47 |
48 | ```{r prepare, warning=FALSE, message=FALSE}
49 | library(gluedown)
50 | library(stringr)
51 | library(rvest)
52 | ```
53 |
54 | Use the `results='asis'` chunk option to print the formatted output to the body
55 | of a document.
56 |
57 | ````markdown
58 | `r ''````{r results='asis'}
59 | md_order(x = c("Legislative", "Executive", "Judicial"))
60 | ```
61 | ````
62 |
63 | ```{r asis, results='asis', echo=FALSE}
64 | md_order(x = c("Legislative", "Executive", "Judicial"))
65 | ```
66 |
67 | ### Lists
68 |
69 | Printing vectors as markdown lists was the initial inspiration for the package.
70 | Here, we use five different functions to create five elements of a new vector.
71 |
72 | ```{r vector}
73 | inlines <- c(
74 | md_bold("Alabama"),
75 | md_code("Alaska"),
76 | md_link("Arizona" = "https://az.gov"),
77 | md_italic("Arkansas"),
78 | md_strike("California")
79 | )
80 | print(inlines)
81 | ```
82 |
83 | Then we can print that new vector as a list, including the inline formatting.
84 |
85 | ```{r bullets, results='asis'}
86 | md_bullet(inlines)
87 | ```
88 |
89 | ### Inline
90 |
91 | You can also use `gluedown` to format R [inline code results][inline].
92 |
93 | ```{r inline}
94 | name <- sample(state.name, size = 1)
95 | abb <- state.abb[match(name, state.name)]
96 | # `r md_bold(name)`
97 | # `r md_italic(abb)`
98 | ```
99 |
100 | In this case, our randomly selected state is `r md_bold(name)`, which has the
101 | abbreviation `r md_italic(abb)`.
102 |
103 | ### Pipes
104 |
105 | All functions are designed to fit within the tidyverse ecosystem and work with
106 | [pipes][pipe].
107 |
108 | ```{r pipe, results='asis'}
109 | read_html("https://w.wiki/A58") %>%
110 | html_node("blockquote") %>%
111 | html_text(trim = TRUE) %>%
112 | str_remove("\\[.*\\]") %>%
113 | md_quote()
114 | ```
115 |
116 | ### Extensions
117 |
118 | The package primarily uses [GitHub Flavored Markdown][gfm], with support
119 | for useful extensions like [task lists][task].
120 |
121 | ```{r extension, results='asis'}
122 | legislation <- c("Houses passes", "Senate concurs", "President signs")
123 | md_task(legislation, check = 1:2)
124 | ```
125 |
126 | ## Contribute
127 |
128 | Please note that the `gluedown` project is released with a
129 | [Contributor Code of Conduct][coc]. By contributing to this project, you agree
130 | to abide by its terms.
131 |
132 |
133 | [life_badge]: https://img.shields.io/badge/lifecycle-maturing-blue.svg
134 | [life_link]: https://lifecycle.r-lib.org/articles/stages.html#maturing
135 | [cran_badge]: https://www.r-pkg.org/badges/version/gluedown
136 | [cran_link]: https://CRAN.R-project.org/package=gluedown
137 | [ga_badge]: https://github.com/k5cents/gluedown/workflows/R-CMD-check/badge.svg
138 | [ga_link]: https://github.com/k5cents/gluedown/actions
139 | [cov_badge]: https://codecov.io/gh/k5cents/gluedown/graph/badge.svg?token=Ln4HFpOH2P
140 | [cov_link]: https://app.codecov.io/gh/k5cents/gluedown?branch=master
141 | [dl_badge]: https://cranlogs.r-pkg.org/badges/grand-total/gluedown
142 | [coc]: https://k5cents.github.io/gluedown/CODE_OF_CONDUCT.html
143 | [cran]: https://cran.r-project.org/package=gluedown
144 | [gfm]: https://github.github.com/gfm/
145 | [gh]: https://github.com/k5cents/gluedown
146 | [glue]: https://github.com/tidyverse/glue
147 | [inline]: https://rmarkdown.rstudio.com/lesson-4.html
148 | [knitr]: https://github.com/yihui/knitr
149 | [pipe]: https://magrittr.tidyverse.org/reference/pipe.html
150 | [rmd]: https://github.com/rstudio/rmarkdown
151 | [task]: https://help.github.com/en/articles/about-task-lists
152 |
153 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | # gluedown
5 |
6 |
7 |
8 | [](https://lifecycle.r-lib.org/articles/stages.html#maturing)
10 | [](https://CRAN.R-project.org/package=gluedown)
12 | 
13 | [](https://app.codecov.io/gh/k5cents/gluedown?branch=master)
15 | [](https://github.com/k5cents/gluedown/actions)
17 |
18 |
19 | The goal of `gluedown` is to ease the transition from R’s powerful
20 | vectors to formatted markdown text. The package uses
21 | [`glue()`](https://github.com/tidyverse/glue) to wrap character vectors
22 | in markdown syntax. With the [`knitr`](https://github.com/yihui/knitr)
23 | package, users can print the formatted vectors directly to the body of a
24 | markdown document.
25 |
26 | ## Installation
27 |
28 | Install the release version from
29 | [CRAN](https://cran.r-project.org/package=gluedown):
30 |
31 | ``` r
32 | install.packages("gluedown")
33 | ```
34 |
35 | The development version can be installed from
36 | [GitHub](https://github.com/k5cents/gluedown):
37 |
38 | ``` r
39 | # install.packages("remotes")
40 | remotes::install_github("k5cents/gluedown")
41 | ```
42 |
43 | ## Usage
44 |
45 | ``` r
46 | library(gluedown)
47 | library(stringr)
48 | library(rvest)
49 | ```
50 |
51 | Use the `results='asis'` chunk option to print the formatted output to
52 | the body of a document.
53 |
54 | ```` markdown
55 | ```{r results='asis'}
56 | md_order(x = c("Legislative", "Executive", "Judicial"))
57 | ```
58 | ````
59 |
60 | 1. Legislative
61 | 2. Executive
62 | 3. Judicial
63 |
64 | ### Lists
65 |
66 | Printing vectors as markdown lists was the initial inspiration for the
67 | package. Here, we use five different functions to create five elements
68 | of a new vector.
69 |
70 | ``` r
71 | inlines <- c(
72 | md_bold("Alabama"),
73 | md_code("Alaska"),
74 | md_link("Arizona" = "https://az.gov"),
75 | md_italic("Arkansas"),
76 | md_strike("California")
77 | )
78 | print(inlines)
79 | #> [1] "**Alabama**" "`Alaska`"
80 | #> [3] "[Arizona](https://az.gov)" "_Arkansas_"
81 | #> [5] "~~California~~"
82 | ```
83 |
84 | Then we can print that new vector as a list, including the inline
85 | formatting.
86 |
87 | ``` r
88 | md_bullet(inlines)
89 | ```
90 |
91 | - **Alabama**
92 | - `Alaska`
93 | - [Arizona](https://az.gov)
94 | - *Arkansas*
95 | - ~~California~~
96 |
97 | ### Inline
98 |
99 | You can also use `gluedown` to format R [inline code
100 | results](https://rmarkdown.rstudio.com/lesson-4.html).
101 |
102 | ``` r
103 | name <- sample(state.name, size = 1)
104 | abb <- state.abb[match(name, state.name)]
105 | # `r md_bold(name)`
106 | # `r md_italic(abb)`
107 | ```
108 |
109 | In this case, our randomly selected state is **New Hampshire**, which
110 | has the abbreviation *NH*.
111 |
112 | ### Pipes
113 |
114 | All functions are designed to fit within the tidyverse ecosystem and
115 | work with [pipes](https://magrittr.tidyverse.org/reference/pipe.html).
116 |
117 | ``` r
118 | read_html("https://w.wiki/A58") %>%
119 | html_node("blockquote") %>%
120 | html_text(trim = TRUE) %>%
121 | str_remove("\\[.*\\]") %>%
122 | md_quote()
123 | ```
124 |
125 | > We the People of the United States, in Order to form a more perfect
126 | > Union, establish Justice, insure domestic Tranquility, provide for the
127 | > common defence, promote the general Welfare, and secure the Blessings
128 | > of Liberty to ourselves and our Posterity, do ordain and establish
129 | > this Constitution for the United States of America.
130 |
131 | ### Extensions
132 |
133 | The package primarily uses [GitHub Flavored
134 | Markdown](https://github.github.com/gfm/), with support for useful
135 | extensions like [task
136 | lists](https://help.github.com/en/articles/about-task-lists).
137 |
138 | ``` r
139 | legislation <- c("Houses passes", "Senate concurs", "President signs")
140 | md_task(legislation, check = 1:2)
141 | ```
142 |
143 | - [x] Houses passes
144 | - [x] Senate concurs
145 | - [ ] President signs
146 |
147 | ## Contribute
148 |
149 | Please note that the `gluedown` project is released with a [Contributor
150 | Code of
151 | Conduct](https://k5cents.github.io/gluedown/CODE_OF_CONDUCT.html). By
152 | contributing to this project, you agree to abide by its terms.
153 |
154 |
155 |
156 |
--------------------------------------------------------------------------------
/_pkgdown.yml:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/_pkgdown.yml
--------------------------------------------------------------------------------
/codecov.yml:
--------------------------------------------------------------------------------
1 | comment: false
2 |
3 | coverage:
4 | status:
5 | project:
6 | default:
7 | target: auto
8 | threshold: 1%
9 | patch:
10 | default:
11 | target: auto
12 | threshold: 1%
13 |
--------------------------------------------------------------------------------
/cran-comments.md:
--------------------------------------------------------------------------------
1 | ## Test environments
2 |
3 | * local: ubuntu 22.04.4, R 4.1.2
4 | * [github-actions][gh_act]:
5 | * windows-latest
6 | * macOS-latest
7 | * ubuntu-20.04 (release)
8 | * ubuntu-20.04 (devel)
9 | * r-hub:
10 | * [windows-x86_64-devel][rhub_win]
11 | * [ubuntu-gcc-release][rhub_ubu]
12 | * [fedora-clang-devel][rhub_fed]
13 | * win-builder: windows-x86_64-devel
14 |
15 | ## R CMD check results
16 |
17 | 0 errors | 0 warnings | 0 notes
18 |
19 | ## Submission
20 |
21 | * Update email from kiernann@pronmail.com to k5cents@gmail.com
22 | * Update URLs from kiernann.com to k5cents.com
23 | * Update Github from @kiernann to @k5cents
24 |
25 |
26 | [gh_act]: https://github.com/k5cents/gluedown/actions
27 | [rhub_win]: https://builder.r-hub.io/status/k5_0.0.5.tar.gz-fe4507f92e784b6daebe78ca907525be
28 | [rhub_ubu]: https://builder.r-hub.io/status/k5_0.0.5.tar.gz-3169c9c34dd94873b98969f409166dfb
29 | [rhub_fed]: https://builder.r-hub.io/status/k5_0.0.5.tar.gz-79dfff34324542c5a3b041e92dd40759
30 |
31 |
--------------------------------------------------------------------------------
/gluedown.Rproj:
--------------------------------------------------------------------------------
1 | Version: 1.0
2 |
3 | RestoreWorkspace: No
4 | SaveWorkspace: No
5 | AlwaysSaveHistory: Default
6 |
7 | EnableCodeIndexing: Yes
8 | UseSpacesForTab: Yes
9 | NumSpacesForTab: 2
10 | Encoding: UTF-8
11 |
12 | RnwWeave: Sweave
13 | LaTeX: pdfLaTeX
14 |
15 | AutoAppendNewline: Yes
16 | StripTrailingWhitespace: Yes
17 |
18 | BuildType: Package
19 | PackageUseDevtools: Yes
20 | PackageInstallArgs: --no-multiarch --with-keep.source
21 | PackageRoxygenize: rd,collate,namespace
22 |
--------------------------------------------------------------------------------
/inst/WORDLIST:
--------------------------------------------------------------------------------
1 | ATX
2 | Autolinks
3 | Bs
4 | Codecov
5 | CommonMark
6 | Consecutiveness
7 | GFM
8 | Gruber
9 | Gruber's
10 | Lifecycle
11 | MacFarlane
12 | ORCID
13 | Reddit
14 | Setext
15 | Strikethrough
16 | URI
17 | URIs
18 | arabic
19 | autolink
20 | autolinks
21 | backtick
22 | bookended
23 | defence
24 | implementors
25 | inmutable
26 | interactable
27 | interpretable
28 | knitr
29 | magrittr
30 | pandoc
31 | pre
32 | preceed
33 | prepending
34 | programmatically
35 | repo
36 | reproducibility
37 | rmarkdown
38 | rvest
39 | setext
40 | softbreak
41 | standardly
42 | striked
43 | strikethrough
44 | tagfilter
45 | tasklist
46 | tibble
47 | tidyverse
48 | unchecking
49 | undesireable
50 | unescaped
51 | yihui
52 |
--------------------------------------------------------------------------------
/man/figures/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/man/figures/logo.png
--------------------------------------------------------------------------------
/man/gluedown-package.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/gluedown-package.R
3 | \docType{package}
4 | \name{gluedown-package}
5 | \alias{gluedown}
6 | \alias{gluedown-package}
7 | \title{gluedown: A package to format character vectors with markdown.}
8 | \description{
9 | The \code{gluedown} package helps transition from R's powerful
10 | vectors to formatted markdown text. The functions use \code{\link[glue:glue]{glue::glue()}} to
11 | wrap character vectors in valid markdown syntax. In combination with the
12 | \code{knitr} package, this allows users to directly print R vectors as formatted
13 | text for improved clarity and readability.
14 | }
15 | \section{Glue wrappers}{
16 |
17 | The \verb{md_*()} functions return \code{glue} objects, which are returned using
18 | \code{\link[=cat]{cat()}} by default. This allows users to both manipulate the formatted
19 | strings as they would with any character vector and still present the
20 | string to the user when an \code{knitr} chunk option is set to return code
21 | results \code{'asis'}.
22 | }
23 |
24 | \section{Other wrappers}{
25 |
26 | The \code{\link[=md_table]{md_table()}} and \code{\link[=md_convert]{md_convert()}} functions wrap around \code{\link[knitr:kable]{knitr::kable()}}
27 | and \code{\link[markdown:renderMarkdown]{markdown::markdownToHTML()}} respectively. The later allows users to
28 | convert \verb{md_*()} outputs to HTML fragments.
29 | }
30 |
31 | \seealso{
32 | Useful links:
33 | \itemize{
34 | \item \url{https://k5cents.github.io/gluedown/}
35 | \item \url{https://github.com/k5cents/gluedown/}
36 | \item Report bugs at \url{https://github.com/k5cents/gluedown/issues}
37 | }
38 |
39 | }
40 | \author{
41 | \strong{Maintainer}: Kiernan Nicholls \email{k5cents@gmail.com} (\href{https://orcid.org/0000-0002-9229-7897}{ORCID}) [copyright holder]
42 |
43 | }
44 | \keyword{internal}
45 |
--------------------------------------------------------------------------------
/man/has_knitr.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/utils.R
3 | \name{has_knitr}
4 | \alias{has_knitr}
5 | \alias{has_markdown}
6 | \title{Check if the user has the 'knitr' package installed}
7 | \usage{
8 | has_knitr()
9 |
10 | has_markdown()
11 | }
12 | \description{
13 | Check if the user has the 'knitr' package installed
14 | }
15 |
--------------------------------------------------------------------------------
/man/md_autolink.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-autolink.R
3 | \name{md_autolink}
4 | \alias{md_autolink}
5 | \title{Markdown autolink}
6 | \usage{
7 | md_autolink(url)
8 | }
9 | \arguments{
10 | \item{url}{A character vector of absolute URLs.}
11 | }
12 | \value{
13 | A \code{glue} vector of length equal to \code{x}.
14 | }
15 | \description{
16 | Take a character vector and wrap each element in \code{<} and \code{>} to return a glue
17 | vector of autolink text. This inline is rendered as the \verb{} HTML tag.
18 | }
19 | \details{
20 | Autolinks are absolute URIs and email addresses inside \code{<} and \code{>}. They are
21 | parsed as links, with the URL or email address as the link label.
22 |
23 | A URI autolink consists of \code{<}, followed by an absolute URI followed by \code{>}.
24 | It is parsed as a link to the URI, with the URI as the link’s label.
25 |
26 | An absolute URI, for these purposes, consists of a scheme followed by a colon
27 | (\code{:}) followed by zero or more characters other than ASCII whitespace and
28 | control characters, \code{<}, and \code{>}. If the URI includes these characters, they
29 | must be percent-encoded (e.g. \verb{\%20} for a space).
30 |
31 | For purposes of this spec, a scheme is any sequence of 2–32 characters
32 | beginning with an ASCII letter and followed by any combination of ASCII
33 | letters, digits, or the symbols plus (”+”), period (”.”), or hyphen (”-”).
34 | }
35 | \examples{
36 | md_autolink("http://foo.bar.baz")
37 | }
38 | \seealso{
39 | Other inline functions:
40 | \code{\link{md_bold}()},
41 | \code{\link{md_code}()},
42 | \code{\link{md_convert}()},
43 | \code{\link{md_disallow}()},
44 | \code{\link{md_escape}()},
45 | \code{\link{md_hardline}()},
46 | \code{\link{md_image}()},
47 | \code{\link{md_issue}()},
48 | \code{\link{md_italic}()},
49 | \code{\link{md_link}()},
50 | \code{\link{md_softline}()},
51 | \code{\link{md_strike}()},
52 | \code{\link{md_text}()}
53 | }
54 | \concept{inline functions}
55 |
--------------------------------------------------------------------------------
/man/md_blank.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-lines.R
3 | \name{md_blank}
4 | \alias{md_blank}
5 | \title{Markdown blank line}
6 | \usage{
7 | md_blank()
8 | }
9 | \value{
10 | A \code{glue} vector of length one containing two newline characters.
11 | }
12 | \description{
13 | Create a blank line between other markdown block-level elements.
14 | }
15 | \details{
16 | Blank lines between block-level elements are ignored, except for the role
17 | they play in determining whether a list is tight or loose.
18 |
19 | Blank lines at the beginning and end of the document are also ignored.
20 | }
21 | \examples{
22 | md_blank
23 | }
24 | \seealso{
25 | Other leaf block functions:
26 | \code{\link{md_chunk}()},
27 | \code{\link{md_fence}()},
28 | \code{\link{md_heading}()},
29 | \code{\link{md_indent}()},
30 | \code{\link{md_label}()},
31 | \code{\link{md_paragraph}()},
32 | \code{\link{md_reference}()},
33 | \code{\link{md_rule}()},
34 | \code{\link{md_setext}()},
35 | \code{\link{md_table}()}
36 | }
37 | \concept{leaf block functions}
38 |
--------------------------------------------------------------------------------
/man/md_bold.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-inlines.R
3 | \name{md_bold}
4 | \alias{md_bold}
5 | \title{Markdown bold emphasis}
6 | \usage{
7 | md_bold(x)
8 | }
9 | \arguments{
10 | \item{x}{The text to be emphasized in bold.}
11 | }
12 | \value{
13 | A \code{glue} vector of length equal to \code{x}.
14 | }
15 | \description{
16 | Take a character vector and wrap each element in double asterisks to create a
17 | glue vector of bold emphasis text. This inline is rendered as the \verb{}
18 | HTML tag.
19 | }
20 | \details{
21 | A double \verb{**} or \verb{__} can open or close emphasis... Emphasis begins with a
22 | delimiter that can open emphasis and ends with a delimiter that can close
23 | emphasis, and that uses the same character (\verb{__} or \verb{**}) as the opening
24 | delimiter.
25 | }
26 | \examples{
27 | md_bold("Example")
28 | md_bold(state.name)
29 | }
30 | \seealso{
31 | Other inline functions:
32 | \code{\link{md_autolink}()},
33 | \code{\link{md_code}()},
34 | \code{\link{md_convert}()},
35 | \code{\link{md_disallow}()},
36 | \code{\link{md_escape}()},
37 | \code{\link{md_hardline}()},
38 | \code{\link{md_image}()},
39 | \code{\link{md_issue}()},
40 | \code{\link{md_italic}()},
41 | \code{\link{md_link}()},
42 | \code{\link{md_softline}()},
43 | \code{\link{md_strike}()},
44 | \code{\link{md_text}()}
45 | }
46 | \concept{inline functions}
47 |
--------------------------------------------------------------------------------
/man/md_bullet.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-list.R
3 | \name{md_bullet}
4 | \alias{md_bullet}
5 | \title{Markdown bullet list}
6 | \usage{
7 | md_bullet(x, marker = c("*", "-", "+"))
8 | }
9 | \arguments{
10 | \item{x}{The vector of bullet point list items.}
11 |
12 | \item{marker}{The bullet list marker to use; one of \code{-}, \code{+}, or \code{*}.}
13 | }
14 | \value{
15 | A \code{glue} vector with length equal to \code{x}.
16 | }
17 | \description{
18 | take a character vector and return a glue vector of valid bullet list items.
19 | When printed together, these bullet list items create a bullet list. This
20 | container block is rendered as the \verb{} HTML tag, with each element of the
21 | vector creating a separate \verb{- } tag.
22 | }
23 | \details{
24 | A list is a sequence of one or more list items of the same type. The list
25 | items may be separated by any number of blank lines.
26 |
27 | Two list items are of the same type if they begin with a list marker of the
28 | same type. Two list markers are of the same type if (a) they are bullet list
29 | markers using the same character (\code{-}, \code{+}, or \code{*})...
30 | }
31 | \examples{
32 | md_bullet(state.name[1:5])
33 | md_bullet(sample(state.name, 5), marker = "+")
34 | }
35 | \seealso{
36 | Other container block functions:
37 | \code{\link{md_list}()},
38 | \code{\link{md_order}()},
39 | \code{\link{md_quote}()},
40 | \code{\link{md_task}()}
41 | }
42 | \concept{container block functions}
43 |
--------------------------------------------------------------------------------
/man/md_chunk.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-chunk.R
3 | \name{md_chunk}
4 | \alias{md_chunk}
5 | \title{Markdown code block}
6 | \usage{
7 | md_chunk(x, type = c("tick", "tilde", "indent"), ...)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of lines to be wrapped concatenated into a single
11 | block, possibly created by \code{\link[=readLines]{readLines()}} or \code{\link[=deparse]{deparse()}}.}
12 |
13 | \item{type}{The type of code block to be created. Either "tick", "tilde"
14 | (which call \code{\link[=md_fence]{md_fence()}}) or "indent" (which calls \code{\link[=md_indent]{md_indent()}}).}
15 |
16 | \item{...}{Arguments to be passed to \code{\link[=md_fence]{md_fence()}} or \code{\link[=md_indent]{md_indent()}}.}
17 | }
18 | \value{
19 | A \code{glue} object of length 1, with elements of \code{x} formatted via
20 | \code{\link[=md_fence]{md_fence()}} or \code{\link[=md_indent]{md_indent()}}.
21 | }
22 | \description{
23 | Take a character vector of lines and return a glue vector
24 | }
25 | \details{
26 | Turn a character vector of lines into a single code block either indented or
27 | fenced in tildes or backticks. This markdown leaf block can be rendered as
28 | nested HTML \verb{
} and \verb{} tags. This function either calls
29 | \code{\link[=md_fence]{md_fence()}} or \code{\link[=md_indent]{md_indent()}} based on the \code{type} argument.
30 | }
31 | \examples{
32 | md_chunk("$ sudo apt install r-base-dev", info = "bash")
33 | md_indent(
34 | n = c(4, 4, 6),
35 | x = c(
36 | "library(dplyr)",
37 | "starwars \%>\%",
38 | "filter(species == 'Droid')"
39 | )
40 | )
41 | }
42 | \seealso{
43 | Other leaf block functions:
44 | \code{\link{md_blank}()},
45 | \code{\link{md_fence}()},
46 | \code{\link{md_heading}()},
47 | \code{\link{md_indent}()},
48 | \code{\link{md_label}()},
49 | \code{\link{md_paragraph}()},
50 | \code{\link{md_reference}()},
51 | \code{\link{md_rule}()},
52 | \code{\link{md_setext}()},
53 | \code{\link{md_table}()}
54 | }
55 | \concept{leaf block functions}
56 |
--------------------------------------------------------------------------------
/man/md_code.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-inlines.R
3 | \name{md_code}
4 | \alias{md_code}
5 | \title{Markdown code span}
6 | \usage{
7 | md_code(x)
8 | }
9 | \arguments{
10 | \item{x}{The text to be formatted as fixed-width inline code.}
11 | }
12 | \value{
13 | A \code{glue} vector of length equal to \code{x}.
14 | }
15 | \description{
16 | Take a character vector and wrap each element in backticks to create a glue
17 | vector of inline code spans. This inline is rendered as a \verb{} HTML tag.
18 | }
19 | \details{
20 | A backtick string is a string of one or more backtick characters that is
21 | neither preceded nor followed by a backtick.
22 |
23 | A code span begins with a backtick string and ends with a backtick string
24 | of equal length. The contents of the code span are the characters between
25 | the two backtick strings, normalized in the following ways: * First, line
26 | endings are converted to spaces. * If the resulting string both begins and
27 | ends with a space character, but does not consist entirely of space
28 | characters, a single space character is removed from the front and back.
29 | This allows you to include code that begins or ends with backtick
30 | characters, which must be separated by whitespace from the opening or
31 | closing backtick strings.
32 | }
33 | \examples{
34 | md_code("ex_var")
35 | md_code(state.name[1:3])
36 | }
37 | \seealso{
38 | Other inline functions:
39 | \code{\link{md_autolink}()},
40 | \code{\link{md_bold}()},
41 | \code{\link{md_convert}()},
42 | \code{\link{md_disallow}()},
43 | \code{\link{md_escape}()},
44 | \code{\link{md_hardline}()},
45 | \code{\link{md_image}()},
46 | \code{\link{md_issue}()},
47 | \code{\link{md_italic}()},
48 | \code{\link{md_link}()},
49 | \code{\link{md_softline}()},
50 | \code{\link{md_strike}()},
51 | \code{\link{md_text}()}
52 | }
53 | \concept{inline functions}
54 |
--------------------------------------------------------------------------------
/man/md_convert.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-convert.R
3 | \name{md_convert}
4 | \alias{md_convert}
5 | \title{Convert markdown to HTML}
6 | \usage{
7 | md_convert(x, frag = TRUE, disallow = TRUE)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of \emph{markdown} text to be converted.}
11 |
12 | \item{frag}{logical; Whether only a single HTML fragment should be returned.
13 | \code{TRUE} by default.}
14 |
15 | \item{disallow}{logical; Should \code{\link[=md_disallow]{md_disallow()}} be called on the converted
16 | output?}
17 | }
18 | \value{
19 | A \code{glue} vector of length 1 containing HTML tags.
20 | }
21 | \description{
22 | Take a character vector of valid markdown text and pass it to
23 | \code{\link[markdown:renderMarkdown]{markdown::markdownToHTML()}} to create a glue vector of HTML fragments.
24 | Primarily used to test that \verb{md_*()} functions create vectors that meet the
25 | GFM spec and can be rendered as HTML.
26 | }
27 | \details{
28 | GFM enables the \code{tagfilter} extension, where the following HTML tags will be
29 | filtered when rendering HTML output...
30 | }
31 | \examples{
32 | md_convert(x = md_bold("test"))
33 | }
34 | \seealso{
35 | Other inline functions:
36 | \code{\link{md_autolink}()},
37 | \code{\link{md_bold}()},
38 | \code{\link{md_code}()},
39 | \code{\link{md_disallow}()},
40 | \code{\link{md_escape}()},
41 | \code{\link{md_hardline}()},
42 | \code{\link{md_image}()},
43 | \code{\link{md_issue}()},
44 | \code{\link{md_italic}()},
45 | \code{\link{md_link}()},
46 | \code{\link{md_softline}()},
47 | \code{\link{md_strike}()},
48 | \code{\link{md_text}()}
49 | }
50 | \concept{inline functions}
51 |
--------------------------------------------------------------------------------
/man/md_disallow.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-convert.R
3 | \name{md_disallow}
4 | \alias{md_disallow}
5 | \title{Disallow certain raw HTML}
6 | \usage{
7 | md_disallow(html)
8 | }
9 | \arguments{
10 | \item{html}{A character vector of \emph{markdown} text to be converted.}
11 | }
12 | \value{
13 | A \code{glue} vector of length 1 containing HTML tags.
14 | }
15 | \description{
16 | Take a character vector of raw HTML text (possibly via \code{\link[=md_convert]{md_convert()}}) and
17 | disallow certain tags by replacing \code{<} with \verb{<}.
18 | }
19 | \details{
20 | GFM enables the tagfilter extension, where the following HTML tags will be
21 | filtered when rendering HTML output:
22 | \itemize{
23 | \item \verb{}
24 | \item \verb{<textarea>}
25 | \item \verb{<style>}
26 | \item \verb{<xmp>}
27 | \item \verb{<iframe>}
28 | \item \verb{<noembed>}
29 | \item \verb{<noframes>}
30 | \item \verb{<script>}
31 | \item \verb{<plaintext>}
32 | }
33 |
34 | Filtering is done by replacing the leading \code{<} with the entity \verb{<}. These
35 | tags are chosen in particular as they change how HTML is interpreted in a way
36 | unique to them (i.e. nested HTML is interpreted differently), and this is
37 | usually undesireable (sic) in the context of other rendered Markdown content.
38 |
39 | All other HTML tags are left untouched.
40 | }
41 | \examples{
42 | md_disallow("<title>GitHub Flavored Markdown Spec ")
43 | }
44 | \seealso{
45 | Other inline functions:
46 | \code{\link{md_autolink}()},
47 | \code{\link{md_bold}()},
48 | \code{\link{md_code}()},
49 | \code{\link{md_convert}()},
50 | \code{\link{md_escape}()},
51 | \code{\link{md_hardline}()},
52 | \code{\link{md_image}()},
53 | \code{\link{md_issue}()},
54 | \code{\link{md_italic}()},
55 | \code{\link{md_link}()},
56 | \code{\link{md_softline}()},
57 | \code{\link{md_strike}()},
58 | \code{\link{md_text}()}
59 | }
60 | \concept{inline functions}
61 |
--------------------------------------------------------------------------------
/man/md_escape.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-escape.R
3 | \name{md_escape}
4 | \alias{md_escape}
5 | \title{Backslash escape all punctuation}
6 | \usage{
7 | md_escape(x)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of strings containing punctuation that might
11 | accidentally be considered markdown syntax.}
12 | }
13 | \value{
14 | A character string with all \verb{[:punct:]} properly escaped with
15 | prepended backslashes.
16 | }
17 | \description{
18 | Take a character vector containing punctuation and return a glue vector with
19 | every punctuation mark prepended with double escape backslashes.
20 | }
21 | \details{
22 | When trying to format text containing markdown syntax characters, it's
23 | necessary to "escape" those characters so that they are ignored by
24 | formatting.
25 |
26 | Any ASCII punctuation character may be backslash-escaped... Escaped
27 | characters are treated as regular characters and do not have their usual
28 | Markdown meanings.
29 | }
30 | \examples{
31 | md_escape("# six seasons and a movie")
32 | }
33 | \seealso{
34 | Other inline functions:
35 | \code{\link{md_autolink}()},
36 | \code{\link{md_bold}()},
37 | \code{\link{md_code}()},
38 | \code{\link{md_convert}()},
39 | \code{\link{md_disallow}()},
40 | \code{\link{md_hardline}()},
41 | \code{\link{md_image}()},
42 | \code{\link{md_issue}()},
43 | \code{\link{md_italic}()},
44 | \code{\link{md_link}()},
45 | \code{\link{md_softline}()},
46 | \code{\link{md_strike}()},
47 | \code{\link{md_text}()}
48 | }
49 | \concept{inline functions}
50 |
--------------------------------------------------------------------------------
/man/md_fence.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-chunk.R
3 | \name{md_fence}
4 | \alias{md_fence}
5 | \title{Markdown fenced code block}
6 | \usage{
7 | md_fence(x, char = c("`", "~"), info = "r")
8 | }
9 | \arguments{
10 | \item{x}{A character vector of lines to be wrapped concatenated into a single
11 | block, possibly created by possibly created by \code{\link[=readLines]{readLines()}} or
12 | \code{\link[=deparse]{deparse()}}.}
13 |
14 | \item{char}{The character to use in the code fence; either backtick
15 | characters... or tildes (\code{~}). Defaults to backticks.}
16 |
17 | \item{info}{The info string text to follow the initial code fence, typically
18 | a code for the language of the lines of \code{x}. Defaults to \code{r}.}
19 | }
20 | \value{
21 | A character vector wrapped on either side by code fences.
22 | }
23 | \description{
24 | Turn a character vector of lines into a single code block with lines
25 | bookended with a code fence of backticks or tildes. This markdown leaf block
26 | can be rendered as HTML \verb{} tags inside \verb{} tags.
27 | }
28 | \details{
29 | A code fence is a sequence of at least three consecutive backtick characters
30 | ... or tildes (\code{~}). (Tildes and backticks cannot be mixed.) A fenced code
31 | block begins with a code fence, indented no more than three spaces.
32 |
33 | The line with the opening code fence may optionally contain some text
34 | following the code fence; this is trimmed of leading and trailing whitespace
35 | and called the info string...
36 |
37 | The content of the code block consists of all subsequent lines, until a
38 | closing code fence of the same type as the code block began with (backticks
39 | or tildes), and with at least as many backticks or tildes as the opening code
40 | fence...
41 |
42 | A fenced code block may interrupt a paragraph, and does not require a blank
43 | line either before or after.
44 |
45 | The content of a code fence is treated as literal text, not parsed as
46 | inlines. The first word of the info string is typically used to specify the
47 | language of the code sample, and rendered in the class attribute of the code
48 | tag. However, this spec does not mandate any particular treatment of the info
49 | string (see the \code{info} argument).
50 | }
51 | \examples{
52 | md_fence(deparse(sd))
53 | md_fence(c("library(dplyr)", "starwars \%>\%", " filter(species == 'Droid')"))
54 | }
55 | \seealso{
56 | Other leaf block functions:
57 | \code{\link{md_blank}()},
58 | \code{\link{md_chunk}()},
59 | \code{\link{md_heading}()},
60 | \code{\link{md_indent}()},
61 | \code{\link{md_label}()},
62 | \code{\link{md_paragraph}()},
63 | \code{\link{md_reference}()},
64 | \code{\link{md_rule}()},
65 | \code{\link{md_setext}()},
66 | \code{\link{md_table}()}
67 | }
68 | \concept{leaf block functions}
69 |
--------------------------------------------------------------------------------
/man/md_hardline.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-lines.R
3 | \name{md_hardline}
4 | \alias{md_hardline}
5 | \title{Markdown hard line breaks}
6 | \usage{
7 | md_hardline(...)
8 | }
9 | \arguments{
10 | \item{...}{Any number of character vectors.}
11 | }
12 | \value{
13 | A \code{glue} vector with elements of \code{...} separated by two trailing
14 | spaces and a single newline.
15 | }
16 | \description{
17 | Take a character vector and return a collapsed glue vector with each original
18 | element separated by two spaces and a newline. This inline is rendered with a
19 | \verb{
} HTML tag.
20 | }
21 | \details{
22 | A line break (not in a code span or HTML tag) that is preceded by two or more
23 | spaces and does not occur at the end of a block is parsed as a hard line
24 | break (rendered in HTML as a \verb{
} tag)
25 | }
26 | \examples{
27 | # compare the following
28 | md_bold(c("One", "Two"))
29 | md_hardline(md_bold(c("One", "Two")), md_italic("Three"))
30 | }
31 | \seealso{
32 | Other inline functions:
33 | \code{\link{md_autolink}()},
34 | \code{\link{md_bold}()},
35 | \code{\link{md_code}()},
36 | \code{\link{md_convert}()},
37 | \code{\link{md_disallow}()},
38 | \code{\link{md_escape}()},
39 | \code{\link{md_image}()},
40 | \code{\link{md_issue}()},
41 | \code{\link{md_italic}()},
42 | \code{\link{md_link}()},
43 | \code{\link{md_softline}()},
44 | \code{\link{md_strike}()},
45 | \code{\link{md_text}()}
46 | }
47 | \concept{inline functions}
48 |
--------------------------------------------------------------------------------
/man/md_heading.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-heading.R
3 | \name{md_heading}
4 | \alias{md_heading}
5 | \title{Markdown ATX headings}
6 | \usage{
7 | md_heading(x, level = 1)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of heading text.}
11 |
12 | \item{level}{A numeric vector of use to determine the number of heading hash
13 | characters to preceed each element of \code{x}. The heading level is equal to
14 | the number of \verb{#} characters in the opening sequence.}
15 | }
16 | \value{
17 | A \code{glue} vector of headings with length equal to \code{x}.
18 | }
19 | \description{
20 | Turn a character vector into a vector of valid markdown ATX headings. These
21 | markdown leaf blocks can be rendered as the \verb{} through \verb{} HTML tags.
22 | See \code{\link[=md_setext]{md_setext()}} to create setext (underlined) headings.
23 | }
24 | \details{
25 | An ATX heading consists of a string of characters, parsed as inline content,
26 | between an opening sequence of 1–6 unescaped \verb{#} characters and an optional
27 | closing sequence of any number of unescaped \verb{#} characters. The opening
28 | sequence of \verb{#} characters must be followed by a space or by the end of line.
29 | The optional closing sequence of \verb{#}s must be preceded by a space and may be
30 | followed by spaces only. The opening # character may be indented 0-3 spaces.
31 | The raw contents of the heading are stripped of leading and trailing spaces
32 | before being parsed as inline content. The heading level is equal to the
33 | number of \verb{#} characters in the opening sequence.
34 | }
35 | \examples{
36 | md_heading("Overview")
37 | md_heading(x = c("One", "Two"), level = 1:2)
38 | md_heading(x = c("Installation", "Usage"), level = 2)
39 | }
40 | \seealso{
41 | Other leaf block functions:
42 | \code{\link{md_blank}()},
43 | \code{\link{md_chunk}()},
44 | \code{\link{md_fence}()},
45 | \code{\link{md_indent}()},
46 | \code{\link{md_label}()},
47 | \code{\link{md_paragraph}()},
48 | \code{\link{md_reference}()},
49 | \code{\link{md_rule}()},
50 | \code{\link{md_setext}()},
51 | \code{\link{md_table}()}
52 | }
53 | \concept{leaf block functions}
54 |
--------------------------------------------------------------------------------
/man/md_image.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-link.R
3 | \name{md_image}
4 | \alias{md_image}
5 | \title{Markdown image links}
6 | \usage{
7 | md_image(url, alt = "", title = NULL, ..., .name = FALSE)
8 | }
9 | \arguments{
10 | \item{url}{A character vector of link destination (URL) strings.}
11 |
12 | \item{alt}{A character vector of alternative text that can be used to refer
13 | to an image.}
14 |
15 | \item{title}{The optional title of the link.}
16 |
17 | \item{...}{A sequence of \code{alt = "/url"} named vector pairs. If any such
18 | pairs are provided, \code{.name} will be considered \code{TRUE}.}
19 |
20 | \item{.name}{logical; if \code{TRUE}, the pairs in \code{...} will be used instead of
21 | any values supplied to \code{x} and \code{url}.}
22 | }
23 | \value{
24 | A \code{glue} vector of collapsed display text and associated URLs.
25 |
26 | A \code{glue} vector of collapsed alternative text and associated URLs.
27 | }
28 | \description{
29 | Take character vectors of alternative text, image link destinations, and
30 | optional titles and return single glue vector of valid markdown inline image
31 | links. This inline is rendered as the \verb{![]()
} HTML tag. Note that the
32 | expected arguments of \code{md_image()} are reversed from \code{md_link()}
33 | }
34 | \details{
35 | Syntax for images is like the syntax for links, with one difference. Instead
36 | of link text, we have an image description. The rules for this are the same
37 | as for link text, except that (a) an image description starts with \verb{![}
38 | rather than \code{[}, and (b) an image description may contain links. An image
39 | description has inline elements as its contents. When an image is rendered to
40 | HTML, this is standardly used as the image’s \code{alt} attribute.
41 | }
42 | \examples{
43 | if (file.exists("man/figures/logo.png")) md_image("man/figures/logo.png")
44 | md_image("http://hexb.in/hexagons/eff.png")
45 | md_image(EFF = "http://hexb.in/hexagons/eff.png")
46 | md_image("http://hexb.in/hexagons/eff.png", "EFF Hex Sticker", "Logo")
47 | }
48 | \seealso{
49 | Other inline functions:
50 | \code{\link{md_autolink}()},
51 | \code{\link{md_bold}()},
52 | \code{\link{md_code}()},
53 | \code{\link{md_convert}()},
54 | \code{\link{md_disallow}()},
55 | \code{\link{md_escape}()},
56 | \code{\link{md_hardline}()},
57 | \code{\link{md_issue}()},
58 | \code{\link{md_italic}()},
59 | \code{\link{md_link}()},
60 | \code{\link{md_softline}()},
61 | \code{\link{md_strike}()},
62 | \code{\link{md_text}()}
63 | }
64 | \concept{inline functions}
65 |
--------------------------------------------------------------------------------
/man/md_indent.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-chunk.R
3 | \name{md_indent}
4 | \alias{md_indent}
5 | \title{Markdown indented code block}
6 | \usage{
7 | md_indent(x, n = 4)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of lines to be wrapped concatenated into a
11 | single block, possibly created by \code{\link[=readLines]{readLines()}} or \code{\link[=deparse]{deparse()}}.}
12 |
13 | \item{n}{A numeric vector}
14 | }
15 | \value{
16 | A \code{glue} object of length 1, with the elements of \code{x} preceded with
17 | 4 spaces and separated by a newline.
18 | }
19 | \description{
20 | Turn a character vector of lines into a single code block with each line
21 | indented four spaces. This markdown leaf block can be rendered as nested HTML
22 | \verb{} and \verb{} tags. This is the code block format required by legacy
23 | Reddit-flavored Markdown.
24 | }
25 | \details{
26 | An indented code block is composed of one or more indented chunks separated
27 | by blank lines. An indented chunk is a sequence of non-blank lines, each
28 | indented four or more spaces. The contents of the code block are the literal
29 | contents of the lines, including trailing line endings, minus four spaces of
30 | indentation. An indented code block has no info string.
31 | }
32 | \examples{
33 | md_indent(deparse(md_bold))
34 | }
35 | \seealso{
36 | Other leaf block functions:
37 | \code{\link{md_blank}()},
38 | \code{\link{md_chunk}()},
39 | \code{\link{md_fence}()},
40 | \code{\link{md_heading}()},
41 | \code{\link{md_label}()},
42 | \code{\link{md_paragraph}()},
43 | \code{\link{md_reference}()},
44 | \code{\link{md_rule}()},
45 | \code{\link{md_setext}()},
46 | \code{\link{md_table}()}
47 | }
48 | \concept{leaf block functions}
49 |
--------------------------------------------------------------------------------
/man/md_issue.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-issue.R
3 | \name{md_issue}
4 | \alias{md_issue}
5 | \title{Markdown GitHub issue}
6 | \usage{
7 | md_issue(repo, num)
8 | }
9 | \arguments{
10 | \item{repo}{A character vector in the format \code{"user/rep"}.}
11 |
12 | \item{num}{The issue or pull number \emph{without} hash symbol.}
13 | }
14 | \value{
15 | A character vector which GitHub can automatically hyperlink.
16 | }
17 | \description{
18 | Take a character vector and numeric vector and concatenate them into a glue
19 | vector of valid GitHub issue autolinks (username/repo#issue).
20 | }
21 | \details{
22 | Within conversations on GitHub, references to issues and pull requests are
23 | \href{https://git.io/Jvtb9}{automatically converted to shortened links}.
24 | }
25 | \examples{
26 | md_issue("k5cents/gluedown", 1:5)
27 | }
28 | \seealso{
29 | Other inline functions:
30 | \code{\link{md_autolink}()},
31 | \code{\link{md_bold}()},
32 | \code{\link{md_code}()},
33 | \code{\link{md_convert}()},
34 | \code{\link{md_disallow}()},
35 | \code{\link{md_escape}()},
36 | \code{\link{md_hardline}()},
37 | \code{\link{md_image}()},
38 | \code{\link{md_italic}()},
39 | \code{\link{md_link}()},
40 | \code{\link{md_softline}()},
41 | \code{\link{md_strike}()},
42 | \code{\link{md_text}()}
43 |
44 | Other markdown extensions:
45 | \code{\link{md_strike}()},
46 | \code{\link{md_table}()}
47 | }
48 | \concept{inline functions}
49 | \concept{markdown extensions}
50 |
--------------------------------------------------------------------------------
/man/md_italic.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-inlines.R
3 | \name{md_italic}
4 | \alias{md_italic}
5 | \title{Markdown italic emphasis}
6 | \usage{
7 | md_italic(x)
8 | }
9 | \arguments{
10 | \item{x}{The text to be emphasized in italics.}
11 | }
12 | \value{
13 | A \code{glue} vector of length equal to \code{x}.
14 | }
15 | \description{
16 | Take a character vector and wrap each element in single underscores to create
17 | a glue vector of italic emphasis text. This inline is rendered as the \verb{}
18 | HTML tag.
19 | }
20 | \details{
21 | A single \code{*} or \verb{_} can open or close emphasis... Emphasis begins with a
22 | delimiter that can open emphasis and ends with a delimiter that can close
23 | emphasis, and that uses the same character (\verb{_} or \code{*}) as the opening
24 | delimiter.
25 | }
26 | \examples{
27 | md_italic("Example")
28 | md_italic(state.name)
29 | }
30 | \seealso{
31 | Other inline functions:
32 | \code{\link{md_autolink}()},
33 | \code{\link{md_bold}()},
34 | \code{\link{md_code}()},
35 | \code{\link{md_convert}()},
36 | \code{\link{md_disallow}()},
37 | \code{\link{md_escape}()},
38 | \code{\link{md_hardline}()},
39 | \code{\link{md_image}()},
40 | \code{\link{md_issue}()},
41 | \code{\link{md_link}()},
42 | \code{\link{md_softline}()},
43 | \code{\link{md_strike}()},
44 | \code{\link{md_text}()}
45 | }
46 | \concept{inline functions}
47 |
--------------------------------------------------------------------------------
/man/md_label.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-link.R
3 | \name{md_label}
4 | \alias{md_label}
5 | \title{Markdown link label}
6 | \usage{
7 | md_label(text, label, ..., .name = FALSE)
8 | }
9 | \arguments{
10 | \item{text}{The text in the document to be hyperlinked.}
11 |
12 | \item{label}{A link label that is referenced elsewhere in the document.}
13 |
14 | \item{...}{A sequence of \code{label = "text"} named vector pairs. If any such
15 | pairs are provided, \code{.name} will be considered \code{TRUE}.}
16 |
17 | \item{.name}{logical; if \code{TRUE}, the pairs in \code{...} will be used instead of
18 | any values supplied to \code{x} and \code{url}.}
19 | }
20 | \value{
21 | A single \code{glue} vector of length equal to that of \code{label} and \code{url},
22 | with elements the concatenated arguments.
23 | }
24 | \description{
25 | Create the link labels that can latter be referred to with a link reference
26 | from \code{\link[=md_reference]{md_reference()}}.
27 | }
28 | \details{
29 | A link label begins with a left bracket and ends with the first right bracket
30 | that is not backslash-escaped. Between these brackets there must be at least
31 | one non-whitespace character.
32 | }
33 | \examples{
34 | md_label(CRAN = "The CRAN website")
35 | md_label(text = c("one", "two"), label = 1:2)
36 | }
37 | \seealso{
38 | Other leaf block functions:
39 | \code{\link{md_blank}()},
40 | \code{\link{md_chunk}()},
41 | \code{\link{md_fence}()},
42 | \code{\link{md_heading}()},
43 | \code{\link{md_indent}()},
44 | \code{\link{md_paragraph}()},
45 | \code{\link{md_reference}()},
46 | \code{\link{md_rule}()},
47 | \code{\link{md_setext}()},
48 | \code{\link{md_table}()}
49 | }
50 | \concept{leaf block functions}
51 |
--------------------------------------------------------------------------------
/man/md_link.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-link.R
3 | \name{md_link}
4 | \alias{md_link}
5 | \title{Markdown inline link (6.6)}
6 | \usage{
7 | md_link(text, url, title = NULL, ..., .name = FALSE)
8 | }
9 | \arguments{
10 | \item{text}{A character vector of text with another vector of URLs passed to
11 | the \code{url} argument.}
12 |
13 | \item{url}{A character vector of URLs.}
14 |
15 | \item{title}{The optional title of the link.}
16 |
17 | \item{...}{A sequence of \code{text = "/url"} named vector pairs. If any such
18 | pairs are provided, \code{.name} will be considered \code{TRUE}.}
19 |
20 | \item{.name}{logical; if \code{TRUE}, the pairs in \code{...} will be used instead of
21 | any values supplied to \code{x} and \code{url}.}
22 | }
23 | \value{
24 | A \code{glue} vector of collapsed display text and associated URLs.
25 | }
26 | \description{
27 | Take character vectors of link texts, link destinations, and optional titles
28 | and return single glue vector of valid markdown inline links. This inline is
29 | rendered as the \verb{} HTML tag.
30 | }
31 | \details{
32 | A link contains link text (the visible text), a link destination (the URI
33 | that is the link destination), and optionally a link title. There are two
34 | basic kinds of links in Markdown. In inline links the destination and title
35 | are given immediately after the link text.
36 |
37 | A link text consists of a sequence of zero or more inline elements enclosed
38 | by square brackets (\code{[} and \verb{]})...
39 |
40 | An inline link consists of a link text followed immediately by a left
41 | parenthesis \code{(}, optional whitespace, an optional link destination, an
42 | optional link title separated from the link destination by whitespace,
43 | optional whitespace, and a right parenthesis \verb{)}. The link’s text consists of
44 | the inlines contained in the link text (excluding the enclosing square
45 | brackets). The link’s URI consists of the link destination, excluding
46 | enclosing \verb{<...>} if present, with backslash-escapes in effect as described
47 | above. The link’s title consists of the link title, excluding its enclosing
48 | delimiters, with backslash-escapes in effect as described above.
49 | }
50 | \examples{
51 | md_link(1:5, glue::glue("https://{state.abb[1:5]}.gov"), state.name[1:5])
52 | md_link(CRAN = "https://cran.r-project.org/")
53 | }
54 | \seealso{
55 | Other inline functions:
56 | \code{\link{md_autolink}()},
57 | \code{\link{md_bold}()},
58 | \code{\link{md_code}()},
59 | \code{\link{md_convert}()},
60 | \code{\link{md_disallow}()},
61 | \code{\link{md_escape}()},
62 | \code{\link{md_hardline}()},
63 | \code{\link{md_image}()},
64 | \code{\link{md_issue}()},
65 | \code{\link{md_italic}()},
66 | \code{\link{md_softline}()},
67 | \code{\link{md_strike}()},
68 | \code{\link{md_text}()}
69 | }
70 | \concept{inline functions}
71 |
--------------------------------------------------------------------------------
/man/md_list.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-list.R
3 | \name{md_list}
4 | \alias{md_list}
5 | \title{Markdown generic list}
6 | \usage{
7 | md_list(x, type = c("bullet", "ordered", "task"), ...)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of list items.}
11 |
12 | \item{type}{The type of list to create; either bullet, ordered, or task.}
13 |
14 | \item{...}{Arguments passed to the appropriate list type function.}
15 | }
16 | \value{
17 | A \code{glue} vector with length equal to \code{x}.
18 | }
19 | \description{
20 | Turn a character vector into a valid markdown list block. This is a generic
21 | function that calls \code{\link[=md_bullet]{md_bullet()}}, \code{\link[=md_order]{md_order()}}, or \code{\link[=md_task]{md_task()}} depending on
22 | what string is provided in the \code{type} argument.
23 | }
24 | \examples{
25 | md_list(state.name[1:5], type = "bullet", marker = "+")
26 | md_list(state.name[6:10], type = "ordered", marker = ")")
27 | md_list(state.name[11:15], type = "task", check = 3:5)
28 | }
29 | \seealso{
30 | Other container block functions:
31 | \code{\link{md_bullet}()},
32 | \code{\link{md_order}()},
33 | \code{\link{md_quote}()},
34 | \code{\link{md_task}()}
35 | }
36 | \concept{container block functions}
37 |
--------------------------------------------------------------------------------
/man/md_order.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-list.R
3 | \name{md_order}
4 | \alias{md_order}
5 | \title{Markdown ordered list}
6 | \usage{
7 | md_order(x, marker = c(".", ")"), seq = TRUE, pad = TRUE)
8 | }
9 | \arguments{
10 | \item{x}{The vector of numbered list items.}
11 |
12 | \item{marker}{The ordered list marker following each arabic digits; either
13 | \code{.} or \verb{)}.}
14 |
15 | \item{seq}{logical; Should sequential numbers be used? Defaults to \code{TRUE}. If
16 | \code{FALSE}, each element will be preceded by the number one; many markdown
17 | engines will automatically render repeated ones as a sequential list.}
18 |
19 | \item{pad}{logical; If sequential numbers are used, should they be padded
20 | with zeroes on the left to match the width of the greatest number? Defaults
21 | to \code{TRUE}.}
22 | }
23 | \value{
24 | A \code{glue} vector with length equal to \code{x}.
25 | }
26 | \description{
27 | take a character vector and return a glue vector of valid ordered list items.
28 | When printed together, these ordered list items create a ordered list. This
29 | container block is rendered as the \verb{} HTML tag, with each element of the
30 | vector creating a separate \verb{- } tag.
31 | }
32 | \details{
33 | A list is a sequence of one or more list items of the same type. The list
34 | items may be separated by any number of blank lines.
35 |
36 | Two list items are of the same type if they begin with a list marker of the
37 | same type. Two list markers are of the same type if (b) they are ordered list
38 | numbers with the same delimiter (either \code{.} or \verb{)}).
39 |
40 | A list is an ordered list if its constituent list items begin with ordered
41 | list markers, and a bullet list if its constituent list items begin with
42 | bullet list markers.
43 |
44 | The start number of an ordered list is determined by the list number of its
45 | initial list item. The numbers of subsequent list items are disregarded.
46 | }
47 | \examples{
48 | md_order(state.name[1:5])
49 | md_order(sample(state.name, 5), marker = ")")
50 | md_order(sample(state.name, 5), seq = FALSE)
51 | }
52 | \seealso{
53 | Other container block functions:
54 | \code{\link{md_bullet}()},
55 | \code{\link{md_list}()},
56 | \code{\link{md_quote}()},
57 | \code{\link{md_task}()}
58 | }
59 | \concept{container block functions}
60 |
--------------------------------------------------------------------------------
/man/md_paragraph.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-lines.R
3 | \name{md_paragraph}
4 | \alias{md_paragraph}
5 | \title{Markdown paragraphs breaks}
6 | \usage{
7 | md_paragraph(...)
8 | }
9 | \arguments{
10 | \item{...}{Any number of character vectors.}
11 | }
12 | \value{
13 | A \code{glue} vector with elements of \code{...} separated by two newlines.
14 | }
15 | \description{
16 | Take a character vector and return a glue vector of paragraphs separated by
17 | double newlines. This leaf block is rendered as distinct \verb{
} HTML tags.
18 | }
19 | \details{
20 | A sequence of non-blank lines that cannot be interpreted as other kinds of
21 | blocks forms a paragraph. The contents of the paragraph are the result of
22 | parsing the paragraph’s raw content as inlines. The paragraph’s raw content
23 | is formed by concatenating the lines and removing initial and final
24 | whitespace... Paragraphs can contain multiple lines, but no blank lines.
25 | }
26 | \examples{
27 | md_paragraph(stringr::sentences[1:3])
28 | }
29 | \seealso{
30 | Other leaf block functions:
31 | \code{\link{md_blank}()},
32 | \code{\link{md_chunk}()},
33 | \code{\link{md_fence}()},
34 | \code{\link{md_heading}()},
35 | \code{\link{md_indent}()},
36 | \code{\link{md_label}()},
37 | \code{\link{md_reference}()},
38 | \code{\link{md_rule}()},
39 | \code{\link{md_setext}()},
40 | \code{\link{md_table}()}
41 | }
42 | \concept{leaf block functions}
43 |
--------------------------------------------------------------------------------
/man/md_quote.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-quote.R
3 | \name{md_quote}
4 | \alias{md_quote}
5 | \title{Markdown block quotes}
6 | \usage{
7 | md_quote(x)
8 | }
9 | \arguments{
10 | \item{x}{The character vector of quotes.}
11 | }
12 | \value{
13 | A character vector with a greater-than symbol (\code{>}) prepended to each
14 | element.
15 | }
16 | \description{
17 | Take a character vector and prepend each element in a greater-than symbol to
18 | create a glue vector of block quote markdown text. This inline is rendered as
19 | a \verb{
} HTML tag.
20 | }
21 | \details{
22 | A block quote marker consists of 0-3 spaces of initial indent, plus (a) the
23 | character \code{>} together with a following space, or (b) a single character \code{>}
24 | not followed by a space.
25 |
26 | The following rules define block quotes:
27 | \enumerate{
28 | \item \strong{Basic case.} If a string of lines \emph{Ls} constitute a sequence of blocks
29 | \emph{Bs}, then the result of prepending a block quote marker to the beginning of
30 | each line in \emph{Ls} is a block quote containing \emph{Bs}.
31 | \item \strong{Laziness.} If a string of lines \emph{Ls} constitute a block quote with
32 | contents \emph{Bs}, then the result of deleting the initial block quote marker
33 | from one or more lines in which the next non-whitespace character after the
34 | block quote marker is paragraph continuation text is a block quote with \emph{Bs}
35 | as its content. Paragraph continuation text is text that will be parsed as
36 | part of the content of a paragraph, but does not occur at the beginning of
37 | the paragraph.
38 | \item \strong{Consecutiveness.} A document cannot contain two block quotes in a row
39 | unless there is a blank line between them.
40 | }
41 |
42 | Nothing else counts as a block quote.
43 | }
44 | \examples{
45 | md_quote("Give me liberty, or give me death!")
46 | md_quote(stringr::sentences[1:3])
47 | }
48 | \seealso{
49 | Other container block functions:
50 | \code{\link{md_bullet}()},
51 | \code{\link{md_list}()},
52 | \code{\link{md_order}()},
53 | \code{\link{md_task}()}
54 | }
55 | \concept{container block functions}
56 |
--------------------------------------------------------------------------------
/man/md_reference.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-link.R
3 | \name{md_reference}
4 | \alias{md_reference}
5 | \title{Markdown link reference}
6 | \usage{
7 | md_reference(label, url, title = NULL, ..., .name = FALSE)
8 | }
9 | \arguments{
10 | \item{label}{A link label that is referenced elsewhere in the document.}
11 |
12 | \item{url}{The URL to hyperlink the referenced text with.}
13 |
14 | \item{title}{An \emph{optional} link title; defaults to \code{NULL}.}
15 |
16 | \item{...}{A sequence of \code{label = "/url"} named vector pairs. If any such
17 | pairs are provided, \code{.name} will be considered \code{TRUE}.}
18 |
19 | \item{.name}{logical; if \code{TRUE}, the pairs in \code{...} will be used instead of
20 | any values supplied to \code{x} and \code{url}.}
21 | }
22 | \value{
23 | A single \code{glue} vector of length equal to that of \code{label} and \code{url},
24 | with elements the concatenated arguments.
25 | }
26 | \description{
27 | Take character vectors of link texts, link destinations, and optional titles
28 | and return single glue vector of valid markdown link references. This
29 | markdown leaf block then uses the \code{label} placed \emph{elsewhere} in a markdown
30 | document to render \verb{} HTML tags.
31 | }
32 | \details{
33 | A full reference link (6.6) consists of a link text immediately followed by a
34 | link label that matches a link reference definition elsewhere in the
35 | document...
36 |
37 | A link reference definition consists of a link label, indented up to three
38 | spaces, followed by a colon (\code{:}), optional whitespace (including up to one
39 | line ending), a link destination, optional whitespace (including up to one
40 | line ending), and an optional link title, which if it is present must be
41 | separated from the link destination by whitespace. No further non-whitespace
42 | characters may occur on the line.
43 |
44 | A link reference definition does not correspond to a structural element of a
45 | document. Instead, it defines a label which can be used in reference links
46 | and reference-style images elsewhere in the document. Link reference
47 | definitions can come either before or after the links that use them.
48 | }
49 | \examples{
50 | md_reference(CRAN = "https://cran.r-project.org/")
51 | md_reference(label = 1:2, url = c("https://one.org", "https://two.com"))
52 | md_reference("tv", "https://www.tidyverse.org/", title = "tidyverse")
53 | }
54 | \seealso{
55 | Other leaf block functions:
56 | \code{\link{md_blank}()},
57 | \code{\link{md_chunk}()},
58 | \code{\link{md_fence}()},
59 | \code{\link{md_heading}()},
60 | \code{\link{md_indent}()},
61 | \code{\link{md_label}()},
62 | \code{\link{md_paragraph}()},
63 | \code{\link{md_rule}()},
64 | \code{\link{md_setext}()},
65 | \code{\link{md_table}()}
66 | }
67 | \concept{leaf block functions}
68 |
--------------------------------------------------------------------------------
/man/md_rule.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-rule.R
3 | \name{md_rule}
4 | \alias{md_rule}
5 | \title{Markdown horizontal rule (4.1)}
6 | \usage{
7 | md_rule(char = c("*", "-", "_"), n = 3, space = FALSE)
8 | }
9 | \arguments{
10 | \item{char}{The type of rule; either: \code{-}, \verb{_}, or \code{*}. Defaults to \code{*}.}
11 |
12 | \item{n}{The width of the rule; an integer indicating number of times to
13 | repeat each character. Defaults to the minimum of 3.}
14 |
15 | \item{space}{logical or numeric; How many spaces to place between each
16 | \code{char}. Defaults to \code{FALSE}, which places 0 spaces.}
17 | }
18 | \value{
19 | A repeated-character \code{glue} vector with length 1.
20 | }
21 | \description{
22 | Create a glue vector of characters used to represent a \emph{thematic break}. This
23 | markdown leaf block is rendered as the \verb{
} HTML tag.
24 | }
25 | \details{
26 | A line consisting of 0-3 spaces of indentation, followed by a sequence of
27 | three or more matching \code{-}, \verb{_}, or \code{*} characters, each followed optionally
28 | by any number of spaces or tabs, forms a thematic break.
29 | }
30 | \examples{
31 | md_rule()
32 | md_rule("_")
33 | md_rule(n = 10)
34 | md_rule(space = TRUE)
35 | }
36 | \seealso{
37 | Other leaf block functions:
38 | \code{\link{md_blank}()},
39 | \code{\link{md_chunk}()},
40 | \code{\link{md_fence}()},
41 | \code{\link{md_heading}()},
42 | \code{\link{md_indent}()},
43 | \code{\link{md_label}()},
44 | \code{\link{md_paragraph}()},
45 | \code{\link{md_reference}()},
46 | \code{\link{md_setext}()},
47 | \code{\link{md_table}()}
48 | }
49 | \concept{leaf block functions}
50 |
--------------------------------------------------------------------------------
/man/md_setext.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-heading.R
3 | \name{md_setext}
4 | \alias{md_setext}
5 | \title{Markdown Setext headings (4.3)}
6 | \usage{
7 | md_setext(x, level = 1, width = TRUE)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of heading text.}
11 |
12 | \item{level}{An numeric vector of all either 1 or 2 to determine whether
13 | level 1 headings are created with \code{=} or level two with \code{-}. If less levels
14 | are provided than headings, \code{level} will be repeated via \code{\link[glue:glue]{glue::glue()}}.}
15 |
16 | \item{width}{logical or integer; if \code{TRUE} the width will be automatically
17 | determined by the width of the longest line in \code{x}. If an integer, the
18 | setext underline will be that wide.}
19 | }
20 | \value{
21 | A \code{glue} vector of headings with length equal to \code{x}.
22 | }
23 | \description{
24 | Turn a character vector into a vector of valid markdown Setext headings.
25 | These markdown leaf blocks can be rendered as the \verb{} and \verb{} tags
26 | \emph{only}.
27 | }
28 | \details{
29 | A setext heading consists of one or more lines of text, each containing at
30 | least one non-whitespace character, with no more than 3 spaces indentation,
31 | followed by a setext heading underline. The lines of text must be such that,
32 | were they not followed by the setext heading underline, they would be
33 | interpreted as a paragraph: they cannot be interpretable as a
34 | \href{https://github.github.com/gfm/#code-fence}{code fence},
35 | \href{https://github.github.com/gfm/#atx-headings}{ATX heading},
36 | \href{https://github.github.com/gfm/#block-quotes}{block quote},
37 | \href{https://github.github.com/gfm/#thematic-breaks}{thematic break},
38 | \href{https://github.github.com/gfm/#list-items}{list item}, or
39 | \href{https://github.github.com/gfm/#html-blocks}{HTML block.}
40 |
41 | A setext heading underline is a sequence of \code{=} characters or a sequence of
42 | \code{-} characters, with no more than 3 spaces indentation and any number of
43 | trailing spaces. If a line containing a single \code{-} can be interpreted as an
44 | empty list items, it should be interpreted this way and not as a setext
45 | heading underline.
46 |
47 | The heading is a level 1 heading if \code{=} characters are used in the setext
48 | heading underline, and a level 2 heading if \code{-} characters are used. The
49 | contents of the heading are the result of parsing the preceding lines of text
50 | as CommonMark inline content.
51 |
52 | In general, a setext heading need not be preceded or followed by a blank
53 | line. However, it cannot interrupt a paragraph, so when a setext heading
54 | comes after a paragraph, a blank line is needed between them.
55 | }
56 | \examples{
57 | md_setext("Overview")
58 | md_setext("This is a setext\nheading", level = 2)
59 | md_setext(c("one", "two", "three", "four"), level = c(1, 2))
60 | md_setext("Installation", level = 2, width = 55)
61 | }
62 | \seealso{
63 | Other leaf block functions:
64 | \code{\link{md_blank}()},
65 | \code{\link{md_chunk}()},
66 | \code{\link{md_fence}()},
67 | \code{\link{md_heading}()},
68 | \code{\link{md_indent}()},
69 | \code{\link{md_label}()},
70 | \code{\link{md_paragraph}()},
71 | \code{\link{md_reference}()},
72 | \code{\link{md_rule}()},
73 | \code{\link{md_table}()}
74 | }
75 | \concept{leaf block functions}
76 |
--------------------------------------------------------------------------------
/man/md_softline.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-lines.R
3 | \name{md_softline}
4 | \alias{md_softline}
5 | \title{Markdown soft line breaks}
6 | \usage{
7 | md_softline(...)
8 | }
9 | \arguments{
10 | \item{...}{Any number of character vectors.}
11 | }
12 | \value{
13 | A \code{glue} vector with elements of \code{...} separated by a single newline.
14 | }
15 | \description{
16 | Take a character vector and return a glue vector of separated by a single
17 | newline. This inline is rendered as single \verb{
} HTML tags.
18 | }
19 | \details{
20 | A regular line break (not in a code span or HTML tag) that is not preceded by
21 | two or more spaces or a backslash is parsed as a softbreak. (A softbreak may
22 | be rendered in HTML either as a line ending or as a space. The result will be
23 | the same in browsers. In the examples here, a line ending will be used.)
24 | }
25 | \examples{
26 | # compare the following
27 | md_bold(c("One", "Two"))
28 |
29 | md_softline(md_bold(c("One", "Two")))
30 | }
31 | \seealso{
32 | Other inline functions:
33 | \code{\link{md_autolink}()},
34 | \code{\link{md_bold}()},
35 | \code{\link{md_code}()},
36 | \code{\link{md_convert}()},
37 | \code{\link{md_disallow}()},
38 | \code{\link{md_escape}()},
39 | \code{\link{md_hardline}()},
40 | \code{\link{md_image}()},
41 | \code{\link{md_issue}()},
42 | \code{\link{md_italic}()},
43 | \code{\link{md_link}()},
44 | \code{\link{md_strike}()},
45 | \code{\link{md_text}()}
46 | }
47 | \concept{inline functions}
48 |
--------------------------------------------------------------------------------
/man/md_strike.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-inlines.R
3 | \name{md_strike}
4 | \alias{md_strike}
5 | \title{Markdown strikethrough (extension)}
6 | \usage{
7 | md_strike(x)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of text to be striked through.}
11 | }
12 | \value{
13 | A \code{glue} vector of length equal to \code{x}.
14 | }
15 | \description{
16 | Take a character vector and wrap each element in tildes to create a glue
17 | vector of strikethrough text. This inline is rendered as the \verb{} HTML
18 | tag.
19 | }
20 | \details{
21 | GFM enables the strikethrough extension, where an additional emphasis type is
22 | available. Strikethrough text is any text wrapped in two tildes (\code{~}).
23 | }
24 | \examples{
25 | md_strike("Example")
26 | md_strike(state.name[1:3])
27 | }
28 | \seealso{
29 | Other inline functions:
30 | \code{\link{md_autolink}()},
31 | \code{\link{md_bold}()},
32 | \code{\link{md_code}()},
33 | \code{\link{md_convert}()},
34 | \code{\link{md_disallow}()},
35 | \code{\link{md_escape}()},
36 | \code{\link{md_hardline}()},
37 | \code{\link{md_image}()},
38 | \code{\link{md_issue}()},
39 | \code{\link{md_italic}()},
40 | \code{\link{md_link}()},
41 | \code{\link{md_softline}()},
42 | \code{\link{md_text}()}
43 |
44 | Other markdown extensions:
45 | \code{\link{md_issue}()},
46 | \code{\link{md_table}()}
47 | }
48 | \concept{inline functions}
49 | \concept{markdown extensions}
50 |
--------------------------------------------------------------------------------
/man/md_table.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-table.R
3 | \name{md_table}
4 | \alias{md_table}
5 | \title{Markdown tables (4.10 extension)}
6 | \usage{
7 | md_table(x, ...)
8 | }
9 | \arguments{
10 | \item{x}{An \code{R} object to be formatted as a table.}
11 |
12 | \item{...}{Arguments passed to \code{\link[knitr:kable]{knitr::kable()}}}
13 | }
14 | \value{
15 | A \code{glue} vector of length one, with each element or row of \code{x}
16 | separated by a newline.
17 | }
18 | \description{
19 | Take a list of data frames or matrices and pass them to \code{\link[knitr:kable]{knitr::kable()}} to
20 | create a glue vector containing valid markdown tables.
21 | }
22 | \details{
23 | FM enables the \code{table} extension, where an additional leaf block type is
24 | available.
25 |
26 | A table is an arrangement of data with rows and columns, consisting of a
27 | single header row, a delimiter row separating the header from the data, and
28 | zero or more data rows.
29 |
30 | Each row consists of cells containing arbitrary text, in which
31 | \href{https://github.github.com/gfm/#inline}{inlines} are parsed, separated by
32 | pipes (\code{|}). A leading and trailing pipe is also recommended for clarity of
33 | reading, and if there’s otherwise parsing ambiguity. Spaces between pipes and
34 | cell content are trimmed. Block-level elements cannot be inserted in a table.
35 |
36 | The delimiter row consists of cells whose only content are hyphens (\code{-}), and
37 | optionally, a leading or trailing colon (\code{:}), or both, to indicate left,
38 | right, or center alignment respectively (see \code{align} in \code{\link[knitr:kable]{knitr::kable()}}).
39 | }
40 | \examples{
41 | md_table(mtcars)
42 | md_table(data.frame(x = LETTERS[1:3], y = 1:3), align = c("cc"))
43 | }
44 | \seealso{
45 | Other leaf block functions:
46 | \code{\link{md_blank}()},
47 | \code{\link{md_chunk}()},
48 | \code{\link{md_fence}()},
49 | \code{\link{md_heading}()},
50 | \code{\link{md_indent}()},
51 | \code{\link{md_label}()},
52 | \code{\link{md_paragraph}()},
53 | \code{\link{md_reference}()},
54 | \code{\link{md_rule}()},
55 | \code{\link{md_setext}()}
56 |
57 | Other markdown extensions:
58 | \code{\link{md_issue}()},
59 | \code{\link{md_strike}()}
60 | }
61 | \concept{leaf block functions}
62 | \concept{markdown extensions}
63 |
--------------------------------------------------------------------------------
/man/md_task.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-list.R
3 | \name{md_task}
4 | \alias{md_task}
5 | \title{Markdown task list (extension)}
6 | \usage{
7 | md_task(x, check = NULL)
8 | }
9 | \arguments{
10 | \item{x}{A character vector of task list items.}
11 |
12 | \item{check}{A optional numeric vector of list elements which should be
13 | checked off.}
14 | }
15 | \value{
16 | A \code{glue} vector with length equal to \code{x}.
17 | }
18 | \description{
19 | take a character vector and return a glue vector of valid bullet list items.
20 | When printed together, these bullet list items create a bullet list. This
21 | container block is rendered as the \verb{} HTML tag, with each element of the
22 | vector creating a separate \verb{- } tag. On venues supporting GitHub Flavored
23 | Markdown, this list will be specially rendered with the list item market
24 | replaces with a \verb{} HTML tag.
25 | }
26 | \details{
27 | GFM enables the tasklist extension, where an additional processing step is
28 | performed on list items.
29 |
30 | A task list item is a list item where the first block in it is a paragraph
31 | which begins with a task list item marker and at least one whitespace
32 | character before any other content.
33 |
34 | A task list item marker consists of an optional number of spaces, a left
35 | bracket, either a whitespace character or the letter \code{x} in either
36 | lowercase or uppercase, and then a right bracket.
37 |
38 | When rendered, the task list item marker is replaced with a semantic checkbox
39 | element; in an HTML output, this would be an \verb{}
40 | element.
41 |
42 | If the character between the brackets is a whitespace character, the checkbox
43 | is unchecked. Otherwise, the checkbox is checked.
44 |
45 | This spec does not define how the checkbox elements are interacted with: in
46 | practice, implementors are free to render the checkboxes as disabled or
47 | inmutable elements, or they may dynamically handle dynamic interactions (i.e.
48 | checking, unchecking) in the final rendered document.
49 | }
50 | \examples{
51 | md_task(c("Wake up", "Eat Breakfast", "Brush Teeth"), check = c(1, 3))
52 | }
53 | \seealso{
54 | Other container block functions:
55 | \code{\link{md_bullet}()},
56 | \code{\link{md_list}()},
57 | \code{\link{md_order}()},
58 | \code{\link{md_quote}()}
59 | }
60 | \concept{container block functions}
61 |
--------------------------------------------------------------------------------
/man/md_text.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/md-text.R
3 | \name{md_text}
4 | \alias{md_text}
5 | \title{Markdown textual content}
6 | \usage{
7 | md_text(x)
8 | }
9 | \arguments{
10 | \item{x}{A character vector.}
11 | }
12 | \value{
13 | A \code{glue} vector.
14 | }
15 | \description{
16 | Simple wrapper around \code{\link[glue:as_glue]{glue::as_glue()}}. Take a character vector and return a
17 | glue vector.
18 | }
19 | \details{
20 | Any characters not given an interpretation by the [other] rules will be
21 | parsed as plain textual content.
22 | }
23 | \examples{
24 | md_text("foo")
25 | }
26 | \seealso{
27 | Other inline functions:
28 | \code{\link{md_autolink}()},
29 | \code{\link{md_bold}()},
30 | \code{\link{md_code}()},
31 | \code{\link{md_convert}()},
32 | \code{\link{md_disallow}()},
33 | \code{\link{md_escape}()},
34 | \code{\link{md_hardline}()},
35 | \code{\link{md_image}()},
36 | \code{\link{md_issue}()},
37 | \code{\link{md_italic}()},
38 | \code{\link{md_link}()},
39 | \code{\link{md_softline}()},
40 | \code{\link{md_strike}()}
41 | }
42 | \concept{inline functions}
43 |
--------------------------------------------------------------------------------
/man/pipe.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/utils.R
3 | \name{\%>\%}
4 | \alias{\%>\%}
5 | \title{Pipe operator}
6 | \usage{
7 | lhs \%>\% rhs
8 | }
9 | \description{
10 | See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
11 | }
12 | \keyword{internal}
13 |
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon-120x120.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon-120x120.png
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon-152x152.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon-152x152.png
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon-180x180.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon-180x180.png
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon-60x60.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon-60x60.png
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon-76x76.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon-76x76.png
--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/apple-touch-icon.png
--------------------------------------------------------------------------------
/pkgdown/favicon/favicon-16x16.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/favicon-16x16.png
--------------------------------------------------------------------------------
/pkgdown/favicon/favicon-32x32.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/favicon-32x32.png
--------------------------------------------------------------------------------
/pkgdown/favicon/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/k5cents/gluedown/0f48b8079100f71f3a26f843038e3f7530690bc2/pkgdown/favicon/favicon.ico
--------------------------------------------------------------------------------
/tests/spelling.R:
--------------------------------------------------------------------------------
1 | if(requireNamespace('spelling', quietly = TRUE))
2 | spelling::spell_check_test(vignettes = TRUE, error = FALSE,
3 | skip_on_cran = TRUE)
4 |
--------------------------------------------------------------------------------
/tests/testthat.R:
--------------------------------------------------------------------------------
1 | library(testthat)
2 | library(gluedown)
3 |
4 | test_check("gluedown")
5 |
--------------------------------------------------------------------------------
/tests/testthat/test-4.1-thematic-breaks.R:
--------------------------------------------------------------------------------
1 | library(testthat)
2 | library(gluedown)
3 | library(glue)
4 | library(rvest)
5 |
6 | test_that("md_rule creates
tags (ex. 13)", {
7 | # https://github.github.com/gfm/#example-13
8 | node1 <- md_rule("*", 3) %>% find_nodes("hr")
9 | node2 <- md_rule("-", 3) %>% find_nodes("hr")
10 | node3 <- md_rule("_", 3) %>% find_nodes("hr")
11 | expect_false(is.na(node1))
12 | expect_false(is.na(node2))
13 | expect_false(is.na(node3))
14 | })
15 |
16 | test_that("md_rule doesn't allow invalid characters (ex. 14-15)", {
17 | # https://github.github.com/gfm/#example-14
18 | expect_error(md_rule("+"))
19 | # https://github.github.com/gfm/#example-15
20 | expect_error(md_rule("="))
21 | })
22 |
23 | test_that("md_rule doesn't too few characters (ex. 16)", {
24 | # https://github.github.com/gfm/#example-16
25 | expect_error(md_rule("-", 2))
26 | expect_error(md_rule("*", 2))
27 | expect_error(md_rule("_", 2))
28 | })
29 |
30 | test_that("md_rule allows more than 3 characters (ex. 20)", {
31 | # https://github.github.com/gfm/#example-20
32 | node <- md_rule("-", 37) %>% find_nodes("hr")
33 | expect_false(is.na(node))
34 | })
35 |
36 | test_that("md_rule do not need blank lines (ex. 27", {
37 | skip("This seems to be an error with conversion via pandoc, etc")
38 | # https://github.github.com/gfm/#example-27
39 | lines <- md_softline(
40 | md_bullet("foo", "-"),
41 | md_rule(),
42 | md_bullet("bar", "-")
43 | )
44 | md_convert(lines)
45 | })
46 |
47 | test_that("md_rule can interupt a paragraph (ex. 28", {
48 | # https://github.github.com/gfm/#example-28
49 | lines <- md_softline("Foo", md_rule("*"), "Bar")
50 | node <- md_convert(lines) %>% find_nodes("hr")
51 | expect_false(is.na(node))
52 | })
53 |
54 | test_that("md_rule with hyphens creates tag not
(ex. 29)", {
55 | # https://github.github.com/gfm/#example-29
56 | lines <- md_softline("Foo", md_rule("-"), "Bar")
57 | node1 <- md_convert(lines) %>% find_nodes("hr")
58 | node2 <- md_convert(lines) %>% find_nodes("h2")
59 | expect_empty(node1)
60 | expect_full(node2)
61 | })
62 |
63 | test_that("md_rule takes precedence over list item (ex. 30)", {
64 | skip("This seems to be an error with conversion via pandoc, etc")
65 | # https://github.github.com/gfm/#example-30
66 | lines <- md_softline(
67 | md_bullet("Foo"),
68 | md_rule(space = TRUE),
69 | md_bullet("Bar")
70 | )
71 | node <- md_convert(lines)
72 | })
73 |
74 | test_that("md_rule can creat a withing a hypeh bullet list (ex. 31)", {
75 | skip("This seems to be an error with conversion via pandoc, etc")
76 | # https://github.github.com/gfm/#example-31
77 | lines <- c("Foo", md_rule(space = TRUE)) %>% md_bullet("-")
78 | node <- md_convert(lines) %>%
79 | find_nodes("li") %>%
80 | html_node("hr")
81 | expect_false(is.na(node[2]))
82 | })
83 |
84 | test_that("md_rule works with sep of any length", {
85 | md_rule(space = 0) %>% find_nodes("hr") %>% expect_full()
86 | md_rule(space = 1) %>% find_nodes("hr") %>% expect_full()
87 | md_rule(space = 10) %>% find_nodes("hr") %>% expect_full()
88 | md_rule(space = TRUE) %>% find_nodes("hr") %>% expect_full()
89 | md_rule(space = FALSE) %>% find_nodes("hr") %>% expect_full()
90 | })
91 |
--------------------------------------------------------------------------------
/tests/testthat/test-4.10-tables.R:
--------------------------------------------------------------------------------
1 | library(testthat)
2 | library(gluedown)
3 | library(stringr)
4 | library(rvest)
5 | library(glue)
6 |
7 | test_that("md_table creates a single