build_site: Build pkgdown website
In Laurae2/pkgdown: Make Static HTML Documentation for a Package
Description
Usage
Arguments
Custom CSS/JS
YAML config
YAML config - navbar
YAML config - template
Examples
Description
build_site() is a convenient wrapper around five functions:
-
init_site()
-
build_articles()
-
build_home()
-
build_reference()
-
build_news()
See the documentation for the each function to learn how to control
that aspect of the site.
Usage
1
2
3
4
5
build_site(pkg = ".", path = "docs", examples = TRUE,
run_dont_run = FALSE, mathjax = TRUE, preview = interactive(),
seed = 1014, encoding = "UTF-8")
init_site(pkg = ".", path = "docs")
Arguments
pkg
Path to source package. If R working directory is not
set to the source directory, then pkg must be a fully qualified
path to the source directory (not a relative path).
path
Location in which to save website, relative to package
path.
examples
Run examples?
run_dont_run
Run examples that are surrounded in \dontrun?
mathjax
Use mathjax to render math symbols?
preview
If TRUE, will preview freshly generated site
seed
Seed used to initialize so that random examples are
reproducible.
encoding
The encoding of the input files.
Custom CSS/JS
If you want to do minor customisation of your pkgdown site, the easiest
way is to add pkgdown/extra.css and pkgdown/extra.js. These
will be automatically copied to docs/ and inserted into the
<HEAD> after the default pkgdown CSS and JSS.
YAML config
There are four top-level YAML settings that affect the entire site:
url, title, template, and navbar.
url optionally specifies the url where the site will be published.
If you supply this, other pkgdown sites will link to your site when needed,
rather than using generic links to rdocumentation.org.
title overrides the default site title, which is the package name.
It's used in the page title and default navbar.
You can also provided information to override the default display of
the authors. Provided a list named with the name of each author,
including href to add a link, or html to override the
text:
1
2
3
4
5
6
authors:
Hadley Wickham:
href: http://hadley.nz
RStudio:
href: https://www.rstudio.com
html: <img src="http://tidyverse.org/rstudio-logo.svg" height="24" />
YAML config - navbar
navbar controls the navbar at the top of the page. It uses the same
syntax as RMarkdown.
The following YAML snippet illustrates some of the most important features.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
navbar:
type: inverse
left:
- text: "Home"
href: index.html
- text: "Reference"
href: reference/index.html
- text: "Articles"
menu:
- text: "Heading 1"
- text: "Article A"
href: articles/page_a.html
- text: "Article B"
href: articles/page_b.html
- text: "---------"
- text: "Heading 2"
- text: "Article C"
href: articles/page_c.html
- text: "Article D"
href: articles/page_d.html
right:
- icon: fa-github fa-lg
href: https://example.com
Use type to choose between "default" and "inverse" themes.
You position elements by placing under either left or right.
Components can contain sub-menus with headings (indicated by missing
href) and separators. Currently pkgdown only supports fontawesome
icons. You can see a full list of options at
http://fontawesome.io/icons/.
Any missing components (type, left, or right)
will be automatically filled in from the default navbar: you can see
those values by running template_navbar().
YAML config - template
You can get complete control over the appearance of the site using the
template component. There are two components to the template:
the HTML templates used to layout each page, and the css/js assets
used to render the page in the browser.
The easiest way to tweak the default style is to use a bootswatch template,
by passing on the bootswatch template parameter to the built-in
template:
1
2
3
template:
params:
bootswatch: cerulean
See a complete list of themes and preview how they look at
https://gallery.shinyapps.io/117-shinythemes/:
Optionally provide the ganalytics template parameter to enable
https://www.google.com/analytics/. It should
correspond to your
https://support.google.com/analytics/answer/1032385.
1
2
3
template:
params:
ganalytics: UA-000000-01
You can also override the default templates and provide additional
assets. You can do so by either storing in a package with
directories inst/pkgdown/assets and inst/pkgdown/templates,
or by supplying path and asset_path. To suppress inclusion
of the default assets, set default_assets to false.
1
2
3
4
5
6
7
8
9
template:
package: mycustompackage
# OR:
template:
path: path/to/templates
assets: path/to/assets
default_assets: false
These settings are currently recommended for advanced users only. There
is little documentation, and you'll need to read the existing source
for pkgdown templates to ensure that you use the correct components.
Examples
1
2
3
4
## Not run:
build_site()
## End(Not run)
Laurae2/pkgdown documentation built on May 27, 2019, 12:17 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Custom CSS/JS YAML config YAML config - navbar YAML config - template Examples
Description
build_site() is a convenient wrapper around five functions:
-
init_site() -
build_articles() -
build_home() -
build_reference() -
build_news()
See the documentation for the each function to learn how to control that aspect of the site.
Usage
1 2 3 4 5 | build_site(pkg = ".", path = "docs", examples = TRUE,
run_dont_run = FALSE, mathjax = TRUE, preview = interactive(),
seed = 1014, encoding = "UTF-8")
init_site(pkg = ".", path = "docs")
|
Arguments
pkg |
Path to source package. If R working directory is not set to the source directory, then pkg must be a fully qualified path to the source directory (not a relative path). |
path |
Location in which to save website, relative to package path. |
examples |
Run examples? |
run_dont_run |
Run examples that are surrounded in \dontrun? |
mathjax |
Use mathjax to render math symbols? |
preview |
If |
seed |
Seed used to initialize so that random examples are reproducible. |
encoding |
The encoding of the input files. |
Custom CSS/JS
If you want to do minor customisation of your pkgdown site, the easiest
way is to add pkgdown/extra.css and pkgdown/extra.js. These
will be automatically copied to docs/ and inserted into the
<HEAD> after the default pkgdown CSS and JSS.
YAML config
There are four top-level YAML settings that affect the entire site:
url, title, template, and navbar.
url optionally specifies the url where the site will be published.
If you supply this, other pkgdown sites will link to your site when needed,
rather than using generic links to rdocumentation.org.
title overrides the default site title, which is the package name.
It's used in the page title and default navbar.
You can also provided information to override the default display of
the authors. Provided a list named with the name of each author,
including href to add a link, or html to override the
text:
1 2 3 4 5 6 | authors:
Hadley Wickham:
href: http://hadley.nz
RStudio:
href: https://www.rstudio.com
html: <img src="http://tidyverse.org/rstudio-logo.svg" height="24" />
|
YAML config - navbar
navbar controls the navbar at the top of the page. It uses the same
syntax as RMarkdown.
The following YAML snippet illustrates some of the most important features.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | navbar:
type: inverse
left:
- text: "Home"
href: index.html
- text: "Reference"
href: reference/index.html
- text: "Articles"
menu:
- text: "Heading 1"
- text: "Article A"
href: articles/page_a.html
- text: "Article B"
href: articles/page_b.html
- text: "---------"
- text: "Heading 2"
- text: "Article C"
href: articles/page_c.html
- text: "Article D"
href: articles/page_d.html
right:
- icon: fa-github fa-lg
href: https://example.com
|
Use type to choose between "default" and "inverse" themes.
You position elements by placing under either left or right.
Components can contain sub-menus with headings (indicated by missing
href) and separators. Currently pkgdown only supports fontawesome
icons. You can see a full list of options at
http://fontawesome.io/icons/.
Any missing components (type, left, or right)
will be automatically filled in from the default navbar: you can see
those values by running template_navbar().
YAML config - template
You can get complete control over the appearance of the site using the
template component. There are two components to the template:
the HTML templates used to layout each page, and the css/js assets
used to render the page in the browser.
The easiest way to tweak the default style is to use a bootswatch template,
by passing on the bootswatch template parameter to the built-in
template:
1 2 3 | template:
params:
bootswatch: cerulean
|
See a complete list of themes and preview how they look at https://gallery.shinyapps.io/117-shinythemes/:
Optionally provide the ganalytics template parameter to enable
https://www.google.com/analytics/. It should
correspond to your
https://support.google.com/analytics/answer/1032385.
1 2 3 | template:
params:
ganalytics: UA-000000-01
|
You can also override the default templates and provide additional
assets. You can do so by either storing in a package with
directories inst/pkgdown/assets and inst/pkgdown/templates,
or by supplying path and asset_path. To suppress inclusion
of the default assets, set default_assets to false.
1 2 3 4 5 6 7 8 9 | template:
package: mycustompackage
# OR:
template:
path: path/to/templates
assets: path/to/assets
default_assets: false
|
These settings are currently recommended for advanced users only. There is little documentation, and you'll need to read the existing source for pkgdown templates to ensure that you use the correct components.
Examples
1 2 3 4 | ## Not run:
build_site()
## End(Not run)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.