forked from r-lib/pkgdown
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
99 lines (71 loc) · 3.7 KB
/
README.Rmd
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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
# pkgdown <img src="man/figures/logo.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://cran.r-project.org/package=pkgdown){.pkgdown-release}
[](https://github.com/r-lib/pkgdown/actions/workflows/R-CMD-check.yaml){.pkgdown-devel}
[](https://app.codecov.io/gh/r-lib/pkgdown?branch=main)
<!-- badges: end -->
pkgdown is designed to make it quick and easy to build a website for your package. You can see pkgdown in action at <https://pkgdown.r-lib.org>: this is the output of pkgdown applied to the latest version of pkgdown. Learn more in `vignette("pkgdown")` or `?build_site`.
## Installation
::: .pkgdown-release
```{r, eval = FALSE}
# Install released version from CRAN
install.packages("pkgdown")
```
:::
::: .pkgdown-devel
```{r, eval = FALSE}
# Install development version from GitHub
# install.packages("pak")
pak::pak("r-lib/pkgdown")
```
:::
## Usage
Get started with [usethis](https://usethis.r-lib.org/):
```{r, eval = FALSE}
# Run once to configure your package to use and deploy pkgdown
usethis::use_pkgdown_github_pages()
```
```{r, eval = FALSE}
# Preview your site locally before publishing
pkgdown::build_site()
```
This adds the necessary components and sets up GitHub Actions[^1] for automatic site building when deploying.
Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`.
[^1]: If you don't use GitHub, you can use `usethis::use_pkgdown()` + `pkgdown::build_site()` to create a website.
### pkgdown 2.0.0 and Bootstrap 5
pkgdown 2.0.0 includes an upgrade from Bootstrap 3 to Bootstrap 5, which is accompanied by a whole bunch of minor UI improvements. If you've heavily customised your site, there's a small chance that this will break your site, so everyone needs to explicitly opt-in to the upgrade by adding the following to `_pkgdown.yml`:
```yaml
template:
bootstrap: 5
```
Then learn about the many new ways to customise your site in `vignette("customise")`.
## In the wild
At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples:
* [bayesplot](http://mc-stan.org/bayesplot/index.html)
([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)):
plotting functions for posterior analysis, model checking, and MCMC
diagnostics.
* [valr](https://rnabioco.github.io/valr/)
([source](https://github.com/rnabioco/valr)):
read and manipulate genome intervals and signals.
* [mkin](https://pkgdown.jrwb.de/mkin/)
([source](https://github.com/jranke/mkin)):
calculation routines based on the FOCUS Kinetics Report
* [NMF](http://renozao.github.io/NMF/master/index.html)
([source](https://github.com/renozao/NMF)):
a framework to perform non-negative matrix factorization (NMF).
* [tidyverse and r-lib packages source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code)
Comparing the source and output of these sites is a great way to learn new pkgdown techniques.
## Code of conduct
Please note that this project is released with a [Contributor Code of Conduct](https://pkgdown.r-lib.org/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.