File: markdownHTMLOptions.Rd

package info (click to toggle)
r-cran-markdown 1.1%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 552 kB
  • sloc: ansic: 4,618; sh: 32; makefile: 7
file content (155 lines) | stat: -rw-r--r-- 5,509 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/renderMarkdown.R
\name{markdownHTMLOptions}
\alias{markdownHTMLOptions}
\title{Markdown HTML rendering options}
\usage{
markdownHTMLOptions(defaults = FALSE)
}
\arguments{
\item{defaults}{If \code{TRUE}, then only the default options are returned.
Otherwise all options are returned.}
}
\value{
A \code{character} vector listing either all available options or
  just the default options.
}
\description{
\code{markdownHTMLOptions} returns a character vector listing all the options
that are available for the HTML renderer in the \pkg{markdown} package. As a
convenience, the package default options were chosen to render well-formed
stand-alone HTML pages when using \code{\link{markdownToHTML}()}. The default
options are \code{'use_xhtml'}, \code{'smartypants'}, \code{'base64_images'},
\code{'mathjax'}, and \code{'highlight_code'}.
}
\details{
The HTML renderer provides several options described below. To turn these on
globally in the \pkg{markdown} package, simply place some or all of them in a
character vector and assign to the global option \code{markdown.HTML.options}
like so:

\code{options(markdown.HTML.options = markdownHTMLOptions())}

To reset the options to package default, use:

\code{options(markdown.HTML.options = markdownHTMLOptions(default = TRUE))}

To override the global option, pass the \code{options} as an argument:

\code{markdownToHTML(..., options = c('skip_images'))}

Description of all options:

\describe{

\item{\code{'skip_html'}}{ suppress output of all HTML tags in the document.}

\item{\code{'skip_style'}}{ suppress output of HTML style tags.}

\item{\code{'skip_images'}}{ suppress output of HTML image tags.}

\item{\code{'skip_links'}}{ suppress output of HTML anchor tags.}

\item{\code{'safelink'}}{ only create links for known url types, e.g. http,
ftp, http, etc.}

\item{\code{'toc'}}{ assigns an HTML id to each header of the form 'toc_%d'
where '%d' is replaced with the position of the header within the document
(starting at 0), and creates the table of contents.}

\item{\code{'hard_wrap'}}{ adds an HTML br tag for every newline (excluding
trailing) found within a paragraph.}

\item{\code{'use_xhtml'}}{ create XHMTL 1.0 compliant HTML tags.}

\item{\code{'escape'}}{ escape all HTML found within the \emph{markdown}.
Overrides all of the \code{'skip_*'} options mentioned above.}

\item{\code{'smartypants'}}{ translates plain ASCII punctuation characters
into \emph{smart} typographic punctuation HTML entities. }

\item{\code{'fragment_only'}}{ eliminates the inclusion of any HTML header or
body tags, CSS, or Javascript components. }

\item{\code{'base64_images'}}{ Any local images linked with the
\code{'<img>'} tag to the output HTML will automatically be converted to
base64 and included along with output. }

\item{\code{'mathjax'}}{ includes appropriate Javascript libraries to render
math markup.}

\item{\code{'highlight_code'}}{ includes appropriate Javascript libraries to
highlight code chunks.}

}

See the EXAMPLES section to see the output of each option turned on or off.
}
\examples{
# List all available extensions:
markdownHTMLOptions()

# To turn on all HTML options globally:
options(markdown.HTML.options = markdownHTMLOptions())

# To turn off all HTML options globally:
options(markdown.HTML.options = NULL)

# To turn on package default HTML options globally:
options(markdown.HTML.options = markdownHTMLOptions(default = TRUE))

# HTML OPTIONS

# The following examples are short, so we allways add the HTML option 'fragment_only'
tOpt <- "fragment_only"

# skip_html example
mkd = '<style></style><img src="http://cran.rstudio.com/Rlogo.jpg"><a href="#">Hello</a>'
cat(markdownToHTML(text = mkd, options = c(tOpt)))
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_html")))

# skip_style example
cat(markdownToHTML(text = mkd, options = c(tOpt)))
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_style")))

# skip_images example
cat(markdownToHTML(text = mkd, options = c(tOpt)))
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_images")))

# skip_links example
cat(markdownToHTML(text = mkd, options = c(tOpt)))
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_links")))

# safelink example
cat(markdownToHTML(text = '[foo](http://google.com "baz")', options = c(tOpt)))
cat(markdownToHTML(text = '[foo](http://google.com "baz")', options = c(tOpt, "safelink")))

# toc example
mkd <- paste(c("# Header 1", "p1", "## Header 2", "p2"), collapse = "\\n")

cat(markdownToHTML(text = mkd, options = c(tOpt)))
cat(markdownToHTML(text = mkd, options = c(tOpt, "toc")))

# hard_wrap example
cat(markdownToHTML(text = "foo\\nbar\\n", options = c(tOpt)))
cat(markdownToHTML(text = "foo\\nbar\\n", options = c(tOpt, "hard_wrap")))

# use_xhtml example
cat(markdownToHTML(text = "foo\\nbar\\n", options = c(tOpt, "hard_wrap")))
cat(markdownToHTML(text = "foo\\nbar\\n", options = c(tOpt, "hard_wrap", "use_xhtml")))

# escape example
mkd = '<style></style><img src="http://cran.rstudio.com/Rlogo.jpg"><a href="#">Hello</a>'
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_html")))
# overrides all 'skip_*' options
cat(markdownToHTML(text = mkd, options = c(tOpt, "skip_html", "escape")))

# smartypants example
cat(markdownToHTML(text = "1/2 (c)", options = c(tOpt)))
cat(markdownToHTML(text = "1/2 (c)", options = c(tOpt, "smartypants")))

cat(smartypants(text = "1/2 (c)\\n"))
}
\seealso{
\link{markdownToHTML}
}