You can control additinal aspects of the authors display via the authors
+
You can control additional aspects of the authors display via the authors
YAML field:
display of each author in the footer, sidebar and authors page,
which authors (by role) are displayed in the sidebar and footer,
text before authors in the footer,
diff --git a/dev/search.json b/dev/search.json
index 3033383cb..255a838a3 100644
--- a/dev/search.json
+++ b/dev/search.json
@@ -1 +1 @@
-[{"path":"https://pkgdown.r-lib.org/dev/CODE_OF_CONDUCT.html","id":null,"dir":"","previous_headings":"","what":"Contributor Code of Conduct","title":"Contributor Code of Conduct","text":"contributors maintainers project, pledge respect people contribute reporting issues, posting feature requests, updating documentation, submitting pull requests patches, activities. committed making participation project harassment-free experience everyone, regardless level experience, gender, gender identity expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion. Examples unacceptable behavior participants include use sexual language imagery, derogatory comments personal attacks, trolling, public private harassment, insults, unprofessional conduct. Project maintainers right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct. Project maintainers follow Code Conduct may removed project team. Instances abusive, harassing, otherwise unacceptable behavior may reported opening issue contacting one project maintainers. Code Conduct adapted Contributor Covenant (http://contributor-covenant.org), version 1.0.0, available http://contributor-covenant.org/version/1/0/0/","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing to pkgdown","title":"Contributing to pkgdown","text":"document outlines propose change pkgdown. detailed info contributing tidyverse packages, please see tidyverse contribution guide.","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"pkgdown-and-pandoc-versions","dir":"","previous_headings":"","what":"pkgdown and Pandoc versions","title":"Contributing to pkgdown","text":"versions pkgdown Pandoc used build website stored public facing pkgdown.yml file, e.g. https://dplyr.tidyverse.org/pkgdown.yml.","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"package-reprexes","dir":"","previous_headings":"","what":"Package reprexes","title":"Contributing to pkgdown","text":"encounter unexpected errors running pkgdown::build_site(), try build minimal package recreates error. ideal minimal package dependencies, making easy install quickly reproduce error. example minimal package issue, minimal package containing single .R file two lines reproduce error. quickest way set minimal example package usethis::create_package(): built minimal package recreates error, create GitHub repository package (e.g. usethis::use_git() + usethis::use_github()), file issue link repository.","code":"usethis::create_package(\"~/desktop/testpackage\") # ... edit files ... pkgdown::build_site(tmp, new_process = FALSE, preview = FALSE)"},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"rd-translation","dir":"","previous_headings":"","what":"Rd translation","title":"Contributing to pkgdown","text":"encounter problems Rd tags, please use rd2html() create reprexes:","code":"library(pkgdown) rd2html(\"a\\n%b\\nc\") rd2html(\"a & b\")"},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"pull-request-process","dir":"","previous_headings":"","what":"Pull request process","title":"Contributing to pkgdown","text":"recommend create Git branch pull request (PR). Look Travis AppVeyor build status making changes. README contain badges continuous integration services used package. New code follow tidyverse style guide. can use styler package apply styles, please don’t restyle code nothing PR. use roxygen2, Markdown syntax, documentation. use testthat. Contributions test cases included easier accept. user-facing changes, add bullet top NEWS.md current development version header describing changes made followed GitHub username, links relevant issue(s)/PR(s).","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"netlify","dir":"","previous_headings":"Pull request process","what":"Netlify","title":"Contributing to pkgdown","text":"might ask Netlify preview changes .e. local changes affect pkgdown website? Build install amended package, re-build website (clean_site() build_site()) update docs/ folder. Log Netlify https://app.netlify.com/sites/, scroll bottom. ’ll see box dashed outline says “Want deploy new site without connecting Git?”. Open file browser, navigate docs/, drag docs/ folder dashed box, copy files temporary netlify site. file transfer completes, netlify generate temporary URL new page can copy/paste PR discussion.","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"fixing-typos","dir":"","previous_headings":"","what":"Fixing typos","title":"Contributing to pkgdown","text":"Small typos grammatical errors documentation may edited directly using GitHub web interface, long changes made source file. YES: edit roxygen comment .R file R/. : edit .Rd file man/.","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"prerequisites","dir":"","previous_headings":"","what":"Prerequisites","title":"Contributing to pkgdown","text":"make substantial pull request, always file issue make sure someone team agrees ’s problem. ’ve found bug, create associated issue illustrate bug minimal reprex.","code":""},{"path":"https://pkgdown.r-lib.org/dev/CONTRIBUTING.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Contributing to pkgdown","text":"Please note pkgdown project released Contributor Code Conduct. contributing project agree abide terms.","code":""},{"path":"https://pkgdown.r-lib.org/dev/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 pkgdown authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/accessibility.html","id":"theming","dir":"Articles","previous_headings":"","what":"Theming","title":"Accessibility","text":"adjust colours default theme (including syntax highlighting theme), double check contrast background foreground doesn’t make text difficult read. good place start running representative page site https://wave.webaim.org. default colour development version label makes slightly low contrast pale grey background navbar. colour comes bootstrap “danger” colour, can fix overriding variable _pkgdown.yml: use custom navbar entries display icon, make sure also use aria-label field provide accessible label describes icon.","code":"template: bootstrap: 5 bslib: danger: \"#A6081A\" cran: icon: fab fa-r-project href: https://cloud.r-project.org/package=pkgdown aria-label: View on CRAN"},{"path":"https://pkgdown.r-lib.org/dev/articles/accessibility.html","id":"images","dir":"Articles","previous_headings":"","what":"Images","title":"Accessibility","text":"make site fully accessible, place likely need work adding alternative text images create. Unfortunately, ’s currently way plots generate examples, can add alternative text plots vignettes using fig.alt chunk option: forget add alt text vignettes, pkgdown automatically remind .","code":"```{r} #| fig.alt: > #| Histogram of time between eruptions for Old Faithful. #| It is a bimodal distribution with peaks at 50-55 and #| 80-90 minutes. hist(faithful$waiting) ```"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"getting-started","dir":"Articles","previous_headings":"","what":"Getting started","title":"Customise your site","text":"theming features work Bootstrap 5, first update site adding following lines _pkgdown.yml: Overall, site look pretty similar, notice number small improvements. importantly, default font much bigger, making considerably easier read. Upgrading Bootstrap 5 low chance breaking site unless using pkgdown templates custom CSS.","code":"template: bootstrap: 5"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"theming","dir":"Articles","previous_headings":"","what":"Theming","title":"Customise your site","text":"two ways change visual style site _pkgdown.yml: using pre-packaged bootswatch theme customising theme variables bslib. following sections show . Please note pkgdown’s default theme carefully optimised accessible, make changes, make sure also read vignette(\"accessibility\") learn potential accessibility pitfalls.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"light-switch","dir":"Articles","previous_headings":"Theming","what":"Light switch","title":"Customise your site","text":"can provide “light switch” allow users switch dark light themes setting light-switch template option true: add lightswitch component navbar, default appears far right. allows user select light mode, dark mode, auto mode (follows system setting). modes applied using Bootstrap 5.3’s colours modes separate themes, thin layer colour customisation applied via CSS.","code":"template: light-switch: true"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"bootswatch-themes","dir":"Articles","previous_headings":"Theming","what":"Bootswatch themes","title":"Customise your site","text":"easiest way change entire appearance website use Bootswatch theme: (Themes unlikely work light switch, can try see.) Changing bootswatch theme affects HTML (via navbar, ) CSS, ’ll need re-build complete site build_site() fully appreciate changes. ’re experimenting, can speed things just rebuilding home page CSS running build_home_index(); init_site() (refreshing browser). Bootswatch templates tall navbars (e.g. lux, pulse) also require set pkgdown-nav-height bslib variable. Bootswatch themes provided bslib R package, can also nest bootswatch field bslib field. can find correct height running $(\".navbar\").outerHeight() javascript console.","code":"template: bootstrap: 5 bootswatch: materia template: bootstrap: 5 bslib: bootswatch: lux pkgdown-nav-height: 100px"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"bslib-variables","dir":"Articles","previous_headings":"Theming","what":"bslib variables","title":"Customise your site","text":"Instead picking complete theme, can tweak fonts colours individually using bslib variables. bslib R package wraps sass, tool Boostrap uses produce CSS special language called scss. primary advantage scss CSS ’s programmable, can key bslib variables affect appearance many HTML elements. three key variables affect colour: bg (background) determines page background. fg (foreground) determines text colour. bg fg mixed yield gray-100, gray-200, …, grey-900, used style elements match overall colour scheme. primary sets link colour (translucent) hover colour navbar sidebar. can customise components setting specific bslib variables, taking advantage inheritance possible. example, table-border-color defaults border-color defaults gray-300. want change colour borders, can set border-color just want change colour table borders, can set table-border-color. can find full list variables bslib docs. ’re using light switch, many colours available customisation specifically dark theme. Theming bslib powered bslib::bs_theme() bslib field direct translation arguments function. result, can fully specify bslib theme using template.bslib field, making easy share YAML output.html_document.theme field R Markdown document. iterating colours variables need rerun init_site() refresh browser see changes.","code":"template: bootstrap: 5 bslib: bg: \"#202123\" fg: \"#B8BCC2\" primary: \"#306cc9\" template: bslib: version: 5 bg: \"#202123\" fg: \"#B8BCC2\" primary: \"#306cc9\""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"fonts","dir":"Articles","previous_headings":"Theming","what":"Fonts","title":"Customise your site","text":"can also override default fonts used majority text (base_font), headings (heading_font) code (code_font). easiest way supply name Google font following syntax: want use non-Google font, ’ll need bit work. two steps: need first configure font CSS use _pkgdown.yml. two ways might get CSS: block CSS put pkgdown/extra.scss pkgdown/extra.css. CSS look something like : link style file, ’ll need add using syntax: _pkgdown.yml can use name font just specified: Depending font (purchased ), may need take additional steps ensure can used site, /make sure can still used ’re previewing locally. ’re problems getting custom font work, looking errors browser developer console good place start. iterating fonts, ’ll need run build_home_index(); init_site() refresh browser see update.","code":"template: bootstrap: 5 bslib: base_font: {google: \"Roboto\"} heading_font: {google: \"Roboto Slab\"} code_font: {google: \"JetBrains Mono\"} @font-face { font-family: \"proxima-nova\"; src: local(\"Proxima Nova Regular\"), local(\"ProximaNova-Regular\"), url(\"https://example.com/ProximaNova-Regular.eot?#iefix\") format(\"embedded-opentype\"), url(\"https://example.com/fonts/proxima/ProximaNova-Regular.woff2\") format(\"woff2\"), url(\"https://example.com/fonts/proxima/ProximaNova-Regular.woff\") format(\"woff\"), url(\"https://example.com/fonts/proxima/ProximaNova-Regular.ttf\") format(\"truetype\"); font-weight: normal; font-style: normal; font-display: fallback; } template: includes: in_header: template: bslib: base_font: proxima-nova"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"syntax-highlighting","dir":"Articles","previous_headings":"Theming","what":"Syntax highlighting","title":"Customise your site","text":"colours used syntax highlighting code blocks controlled theme setting: can choose following options: a11y-dark, a11y-light, arrow-dark, arrow-light, atom-one-dark, atom-one-light, ayu-dark, ayu-light, ayu-mirage, breeze-dark, breeze-light, breezedark, dracula, espresso, github-dark, github-light, gruvbox-dark, gruvbox-light, haddock, kate, monochrome-dark, monochrome-light, monochrome, monokai, nord, oblivion, printing, pygments, radical, solarized-dark, solarized-light, solarized, tango, vim-dark, zenburn. Bootswatch themes dark background (e.g. cyborg, darkly, solar) need dark syntax highlighting theme, e.g. arrow-dark: ’re using light switch, want provide theme theme-dark: foreground background colours used inline code controlled code-color code-bg bslib variables. want inline code match code blocks, ’ll need override variables , e.g.:","code":"template: bootstrap: 5 theme: breeze-light template: bootstrap: 5 bootswatch: cyborg theme: arrow-dark template: light-switch: true theme: gruvbox-light theme-dark: gruvbox-dark template: bootstrap: 5 theme: arrow-dark bslib: code-bg: \"#2b2b2b\""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"math-rendering","dir":"Articles","previous_headings":"Theming","what":"Math rendering","title":"Customise your site","text":"default, pkgdown render math using mathml. mathml official standard rendering math web, requires additional javascript css dependencies. However, browser support complex math always good, including complex equations documentation, may want switch either katex mathjax using template.math-rendering field:","code":"template: math-rendering: katex"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"navbar-style","dir":"Articles","previous_headings":"Theming","what":"Navbar style","title":"Customise your site","text":"primary navbar colours determined HTML classes, CSS, can customized using navbar fields bg type control background foreground colours respectively. Typically bg one light, dark, primary: generally don’t need set bg use bootswatch theme, pkgdown pick bg used Bootswatch preview. Similarly, don’t usually need set type bootstrap guess . guess wrong, can override type: light type: dark depending whether background colour light (need dark text) type: dark background dark (need light text). Unfortunately, defined relative page background, dark site ’ll need flip light dark (little experimentation quickly determine looks best). navbar styled HTML, ’ll need build_home_index(); init_site() see effect changing parameter.","code":"navbar: bg: primary"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"layout","dir":"Articles","previous_headings":"","what":"Layout","title":"Customise your site","text":"can customise contents navbar, footer, using navbar footer fields. See ?build_home customise sidebar homepage. use similar structure separately defines overall structure individual components.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"navbar-heading","dir":"Articles","previous_headings":"Layout","what":"Navbar","title":"Customise your site","text":"can customise navigation bar appears top page navbar field. ’s made two pieces: structure, defines overall layout, components, defines piece looks like. organisation makes easy mix match pkgdown defaults customisations. default structure: makes use following built-components: intro: “Get Started”, links vignette article name package1. reference: .Rd files. articles: vignettes articles. tutorials: tutorials. news: NEWS.md exists. search: search box (see ?build_search details). github: link source repository (icon), can automatically determined DESCRIPTION. lightswitch; “light switch” select light mode, dark mode, auto mode. Note customising navbar like comes downside: pkgdown later changes defaults, ’ll update _pkgdown.yml. can use structure field reorganise navbar without changing default contents: can use components override default content. example, yaml provides custom articles menu: Components uses syntax RMarkdown menus. elements menu can : Linked text (text, href, optional target). linked icon (icon, aria-label, href, optional target). can find list available icons fontawesome. Provide text description icon aria-label field screenreader users. heading (just text). separator (text: ——–). add new component navbar, need modify structure components. example, following yaml adds new “twitter” component appears left github icon. Finally, can add arbitrary HTML three locations navbar: inclusions appear screen sizes, collapsed navbar drop . can also customise colour scheme navbar using type bg parameters. See details.","code":"navbar: structure: left: [intro, reference, articles, tutorials, news] right: [search, github, lightswitch] navbar: structure: left: [search] right: [reference, articles] navbar: components: articles: text: Articles menu: - text: Category A - text: Title A1 href: articles/a1.html - text: Title A2 href: articles/a2.html - text: ------- - text: \"Category B\" - text: Article B1 href: articles/b1.html navbar: structure: right: [search, twitter, github, lightswitch] components: twitter: icon: fa-twitter href: http://twitter.com/hadleywickham aria-label: Twitter template: includes: before_title: after_navbar: "},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"footer","dir":"Articles","previous_headings":"Layout","what":"Footer","title":"Customise your site","text":"can customise footer footer field. ’s made two pieces: structure, defines overall layout, components, defines piece looks like. organisation makes easy mix match pkgdown defaults customisations. default structure: uses two three built-components: developed_by: sentence describing main authors package. (See ?build_home want tweak authors appear footer.) built_with: sentence advertising pkgdown. package: name package. can override defaults footer field. example puts author’s information right along legal disclaimer, puts pkgdown link left. side pasted single string (separated \" \") converted markdown HTML.","code":"footer: structure: left: developed_by right: built_with footer: structure: left: pkgdown right: [developed_by, legal] components: legal: Provided without **any warranty**."},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"additional-html-and-files","dir":"Articles","previous_headings":"","what":"Additional HTML and files","title":"Customise your site","text":"need include additional HTML, can add following locations: can include additional files putting right place: pkgdown/extra.css pkgdown/extra.js copied rendered site linked (pkgdown defaults). pkgdown/extra.scss added scss ruleset used generate site CSS. files pkgdown/assets copied website root directory. expert users: template files pkgdown/templates override layout templates provided pkgdown template packages. Use init_site() update rendered website making changes files.","code":"template: includes: in_header: before_body: after_body: before_title: after_navbar: "},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"template-packages","dir":"Articles","previous_headings":"","what":"Template packages","title":"Customise your site","text":"share pkgdown style across several packages, best workflow create… package! can contain following: configuration file inst/pkgdown/_pkgdown.yml. can used set (e.g.) author definitions, Bootstrap version variables, sidebar, footer, navbar, etc. Templates inst/pkgdown/templates/ override default templates. Assets inst/pkgdown/assets/ copied destination directory. (Note files copied; ’ll need reference stylesheet elsewhere order actually used.) inst/pkgdown/extra.scss added bslib ruleset. (Note extra.css supported templates.) pkgdown defaults overriden template files, turn overridden package specific settings. created template package theverybest, need set site’s theme: also need make sure ’s available site built. Typically, won’t want publish package CRAN, want publish GitHub. ’ve done , assuming ’re using usethis workflow, add following line DESCRIPTION: ensure GitHub action automatically install GitHub building pkgdown site. get sense theming package works, can look : tidytemplate used tidyverse tidymodels packages; quillt used R Markdown packages; rotemplate used rOpenSci packages. please note templates aren’t suitable use package ’re designed give common visual identity specific family packages.","code":"template: package: theverybest Config/Needs/website: myorg/theverybest"},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"porting-a-template-package","dir":"Articles","previous_headings":"Template packages","what":"Porting a template package","title":"Customise your site","text":"updating template package works pkgdown 1.0.0, create directories inst/pkgdown/BS5/templates inst/pkgdown/BS5/assets (don’t templates/assets make sure add dummy file ensure git tracks ). templates assets directories directly inst/pkgdown used pkgdown 1.0.0 pkgdown 2.0.0 boostrap: 3. directories inst/pkgdown/BS5/ used pkgdown 2.0.0 boostrap: 5. lets package support versions Bootstrap pkgdown.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"pr-previews","dir":"Articles","previous_headings":"","what":"PR previews","title":"Customise your site","text":"Lastly, might useful get preview website internal pull requests. , use Netlify GitHub Actions (apply similar logic toolset): Create new Netlify website (either scratch dragging dropping simple index.html, creating site GitHub repository unlinking repository); site settings get ID saved NETLIFY_SITE_ID repo secrets; account developer settings get token saved NETLIFY_AUTH_TOKEN repo secrets. Starting standard pkgdown workflow usethis::use_github_action(\"pkgdown\"), add logic build site deploy Netlify pull requests inside repository, pull requests forks. Example workflow.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/customise.html","id":"conclusion","dir":"Articles","previous_headings":"","what":"Conclusion","title":"Customise your site","text":"vignette explained change theming layout pkgdown websites. work improve user experience involve: Working article (?build_articles) reference indexes (?build_reference). Writing compelling README explains package cool/useful/fun. Improving contents individual articles reference topics 😉.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"process","dir":"Articles","previous_headings":"","what":"Process","title":"How to update a released site","text":"’re speed basic idea just want code follow, . Otherwise, read .","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"setup","dir":"Articles","previous_headings":"Process","what":"Setup","title":"How to update a released site","text":"First, make sure ’re main branch, latest version: Next figure released version ’re updating: use create checkout branch ’ll work :","code":"gert::git_branch_checkout(\"main\") gert::git_pull() ver <- desc::desc_get_version()[1, 1:3] gert::git_branch_create(paste0(\"pkgdown-v\", ver), paste0(\"v\", ver))"},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"backport-changes","dir":"Articles","previous_headings":"Process","what":"Backport changes","title":"How to update a released site","text":"Now need backport changes dev site branch. Run R code generate git code pull changes common locations: backport DESCRIPTION, ’ll also need undo change Version: Now build site locally check looks expected:","code":"files <- c( # overall site config \"_pkgdown.yml\", # the workflow that builds the site \".github/workflows/pkgdown.yaml\", # readme and vignettes \"README.md\", \"vignettes\", # logo and favicon \"man/figures/\", \"pkgdown/\", # Author metadata and Config/Needs/Website \"DESCRIPTION\" ) glue::glue(\"git checkout v{ver} -- {files}\") desc::desc_set_version(ver) pkgdown::build_site()"},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"publish","dir":"Articles","previous_headings":"Process","what":"Publish","title":"How to update a released site","text":"Now need publish site. First push branch GitHub: trigger pkgdown workflow: Go package’s GHA page, e.g. usethis::browse_github_actions()). Select pkgdown workflow. Click Run workflow select branch just pushed. ’s dropdown menu , means pkgdown workflow config current.","code":"usethis:::git_push_first()"},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"context","dir":"Articles","previous_headings":"","what":"Context","title":"How to update a released site","text":"talk update released site, first establish might need . released site? kind pkgdown site ? updating released site take special effort?","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"automatic-development-mode","dir":"Articles","previous_headings":"Context","what":"Automatic development mode","title":"How to update a released site","text":"Every pkgdown site -called development mode, can specified via development field _pkgdown.yml. unspecified, default mode: release, results single pkgdown site. Despite name, single site reflects “current package state”, either released state development state. packages substantial user base, recommended instead specify mode: auto like : directs pkgdown “generate different sites development released versions package.” readr package demonstrates happens automatic development mode: readr.tidyverse.org documents released version, .e. install.packages() deliver.readr.tidyverse.org/dev/ documents dev version, .e. ’d get installing GitHub. mode, pkgdown::build_site(), consults DESCRIPTION learn package’s version number. development version number, rendered site written docs/dev/. released version number, site written docs/. (also signals alert users reading documentation dev version vs. released version.) Automatic development mode recommended packages broad user base maximizes chance user read web-based documentation reflects package version locally installed.","code":"development: mode: auto"},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"publishing","dir":"Articles","previous_headings":"Context","what":"Publishing","title":"How to update a released site","text":"Now ’ve established meaning released (vs dev) site, consider site built (.e. HTML generated) deployed (.e. HTML published website people can see .). recommend usethis::use_pkgdown_github_pages() basic pkgdown setup configure GitHub Actions (GHA) workflow automatically render publish site GitHub Pages. function basically shortcut calling following functions individually: use_pkgdown() use_github_pages() use_github_action(\"pkgdown\") adds pkgdown site’s URL _pkgdown.yml, URL field DESCRIPTION, GitHub repo. result, publishing cadence many pkgdown sites governed workflow maintained r-lib/actions/examples/pkgdown.yaml. (confuse _pkgdown.yml, gives instructions pkgdown package, .github/workflows/pkgdown.yaml, gives instructions GHA.) important bits GHA workflow config: Altogether means : Build deploy pushes main. Build, don’t deploy, pull requests main. reveals pkgdown errors, ensures live site isn’t updated pull request merged (code pushed main). Build deploy publish GitHub release. convention, assume GitHub release coincides CRAN release. primary mechanism building released pkgdown site. pkgdown::build_site_github_pages() consults version DESCRIPTION detect whether ’s building released version dev version. determines dest_dir, e.g. docs/ released docs/dev/ dev. package automatic development mode, means almost pushes trigger update dev site. released site updated push state non-development version number publish GitHub release. tweak things released site releases? brings us workflow_dispatch:. (Yes dangling colon correct.) inclusion workflow_dispatch trigger means pkgdown workflow can run demand, importantly browser.","code":"on: push: branches: [main, master] pull_request: branches: [main, master] release: types: [published] workflow_dispatch: - name: Build site run: Rscript -e 'pkgdown::build_site_github_pages(...)' - name: Deploy to GitHub pages 🚀 if: github.event_name != 'pull_request' uses: JamesIves/github-pages-deploy-action@4.1.4 "},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"construct-a-branch-for-the-update","dir":"Articles","previous_headings":"","what":"Construct a branch for the update","title":"How to update a released site","text":"overall goal create branch combines features released website (e.g. released version) development version (e.g. improvements _pkgdown.yml). easiest way start branch using latest release tag, bring selected changes files development version. example, readr’s latest release 2.1.1: general pattern: Now port innovations development site want apply released site. Files must update: .github/workflows/pkgdown.yaml _pkgdown.yml Config/Needs/website field DESCRIPTION (, probably, field! particular, mess version number.) likely candidates: README.Rmd + README.md, e.g., ’ve updated badges. documentation fixes apply released version. reason touch anything R/ even affect roxygen comments. Don’t forget document() ! new vignettes articles apply released version. tips backporting specific changes branch. lucky, specific commits default branch contain necessary changes. case, can cherry pick commit SHA: doesn’t cover everything file want update, identify Git reference (meaning: SHA, tag, branch) file desired state. Checkout specific file path specific ref: example, readr recently gained new vignette applies released version readr, .e. document dev-features functions. can bring current branch : Commit push new branch GitHub. usethis::pr_push() can handy . Just don’t bother opening pull request (branch still pushed). Now use workflow_dispatch GHA trigger: Go Actions page repo, maybe via usethis::browse_github_actions(). Click pkgdown workflow. Click “Run workflow”. “Use workflow ” dropdown menu, select branch ’ve just made pushed, click “Run workflow”. kick pkgdown build--deploy , specifically, cause updates released site. can keep branch around , case didn’t get everything right first time things crop ’d like backport released site, next CRAN release.","code":"git checkout -b update-pkgdown-2-1-1 v2.1.1 git checkout -b NEW-BRANCH-NAME NAME-OF-RELEASE-TAG git cherry-pick SHA git checkout main -- path/to/the/file git checkout main -- vignettes/column-types.Rmd"},{"path":"https://pkgdown.r-lib.org/dev/articles/how-to-update-released-site.html","id":"problem-solving","dir":"Articles","previous_headings":"","what":"Problem-solving","title":"How to update a released site","text":"Another great problem solving technique get bunch people’s _pkgdown.yml files front eyeballs. two ways : GitHub search Michael Chirico’s r-ci-samples repo. given _pkgdown.yml file, remember History Blame can helpful seeing evolved time.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/linking.html","id":"within-a-package","dir":"Articles","previous_headings":"","what":"Within a package","title":"Auto-linking","text":"pkgdown automatically link documentation articles wherever ’s possible unambiguously. includes: Bare function calls, like build_site(). Calls ?, like ?build_site package?pkgdown. Calls help(), like help(\"pkgdown\"). Calls vignette(), like vignette(\"pkgdown\").","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/linking.html","id":"across-packages","dir":"Articles","previous_headings":"","what":"Across packages","title":"Auto-linking","text":"Linking documentation another package straightforward. Just adapt call usual way: purrr::map(), MASS::addterm(). ?purrr::map, ?MASS::addterm. vignette(\"-langs\", package = \"purrr\"), vignette(\"longintro\", package = \"rpart\") purrr pkgdown can find pkgdown site remote package, link ; otherwise, link https://rdrr.io/ documentation CRAN vignettes. order pkgdown site findable, needs listed two places: URL field DESCRIPTION, dplyr: url field _pkgdown.yml, dplyr field defined, pkgdown generates public facing pkgdown.yml file provides metadata site: Now, build pkgdown site package links dplyr documentation (e.g., dplyr::mutate()), pkgdown looks first dplyr’s DESCRIPTION find website, looks pkgdown.yml, uses metadata generate correct links. allow package linked locally installed packages, even website reachable build time, following option needs set _pkgdown.yml: allows locally installed packages access package index metadata locally installed copy, may useful website require auth, build behind firewall.","code":"URL: https://dplyr.tidyverse.org, https://github.com/tidyverse/dplyr url: https://dplyr.tidyverse.org pandoc: '2.2' pkgdown: 1.3.0 pkgdown_sha: ~ articles: compatibility: compatibility.html dplyr: dplyr.html dplyr_0.8.0: future/dplyr_0.8.0.html dplyr_0.8.0_new_hybrid: future/dplyr_0.8.0_new_hybrid.html programming: programming.html two-table: two-table.html window-functions: window-functions.html urls: reference: https://dplyr.tidyverse.org/reference article: https://dplyr.tidyverse.org/articles deploy: install_metadata: true"},{"path":"https://pkgdown.r-lib.org/dev/articles/metadata.html","id":"necessary-configuration","dir":"Articles","previous_headings":"","what":"Necessary configuration","title":"Metadata","text":"Metadata can produced correctly pkgdown website URL indicated configuration file.","code":"url: https://example.com"},{"path":"https://pkgdown.r-lib.org/dev/articles/metadata.html","id":"site-wide-customization","dir":"Articles","previous_headings":"","what":"Site-wide customization","title":"Metadata","text":"Metadata entire pkgdown website can specified site’s _pkgdown.yml configuration file home template: opengraph sections: home: title home: description fields override Title Description fields package DESCRIPTION. ’s good practice set fields make package documentation easier find via search, rather sticking title description needed CRAN. template: opengraph section allows customize social media card. image: default, pkgdown uses package’s logo card image (one exists). Use image specify alternative image social media cards pages pkgdown site. src: fully qualified URL media card image e.g. src: https://avatars.githubusercontent.com/u/22618716?v=4; relative path image rendered website e.g. src: articles/test/image.jpg; relative path image stored man/figures package e.g. src: man/figures/cards.png. src field required image specified. alt: Alternative text describing image screen readers situations social media card image displayed. twitter: can specify Twitter accounts associated package style social media card Twitter display. creator: Typically, Twitter handle author package article. site: Twitter handle organization affiliated package author sponsoring package development. one either creator site included, provided value used fields. card: style social media card Twitter display. pkgdown sites, relevant options summary_large_image, featuring large image page title description, summary, featuring small square image inline left page title description.","code":"home: title: An R package for pool-noodle discovery description: Discover and add pool-noodles to your growing collection. template: opengraph: image: src: man/figures/card.png alt: \"Pool noodles configured to form the word poolnoodlr\" twitter: creator: \"@hadleywickham\" site: \"@rstudio\" card: summary_large_image"},{"path":"https://pkgdown.r-lib.org/dev/articles/metadata.html","id":"article-metadata","dir":"Articles","previous_headings":"","what":"Article metadata","title":"Metadata","text":"Articles vignettes rendered articles pkgdown can individually customized metadata social media cards. Use title, description, author fields specify title, description, (optional) author vignette article. title field used title article pkgdown site always included. title description used pkgdown page’s social media card. description included article’s YAML front matter, name package used instead. description also displayed articles index. author field used text vignette article. author name displayed depends output format. articles, opengraph section works way site-wide template: opengraph settings, applied article vignette. allows specify social media card preview images individual articles, associate article particular Twitter account. specified, opengraph settings site-wide configuration used.","code":"title: \"Introduction to poolnoodlr\" description: \"A brief introduction to pool noodles in R.\" author: \"Mara Averick\" opengraph: image: src: \"https://example.com/pkg/batpig.png\" twitter: card: summary creator: \"@dataandme\" output: rmarkdown::html_vignette vignette: > %\\VignetteIndexEntry{Introduction to poolnoodlr} %\\VignetteEngine{knitr::rmarkdown} %\\VignetteEncoding{UTF-8}"},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"metadata","dir":"Articles","previous_headings":"","what":"Metadata","title":"Introduction to pkgdown","text":"can override pkgdown’s defaults YAML file called _pkgdown.yml1. important field url, gives final location site: url used throughout site generate absolute urls needed. url also part enables auto-links help topics vignettes sites external package, pkgdown sites Quarto websites. See vignette(\"linking\") . Another important option template, allows control overall appearance site: can learn controlling appearance site vignette(\"customise\").","code":"url: https://pkgdown.r-lib.org template: bootstrap: 5 bootswatch: cerulean"},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"accessibility","dir":"Articles","previous_headings":"","what":"Accessibility","title":"Introduction to pkgdown","text":"pkgdown’s defaults work ensure site accessible many people possible. accessibilty issues human can solve, make sure also read vignette(\"accessibility\") learn .","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"home-page","dir":"Articles","previous_headings":"","what":"Home page","title":"Introduction to pkgdown","text":"contents home page automatically generated index.md README.md. pkgdown tries put order, ’s possible different display GitHub pkgdown providing files. homepage also includes sidebar full useful links (see ?build_home generated can customise ).","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"reference","dir":"Articles","previous_headings":"","what":"Reference","title":"Introduction to pkgdown","text":"pkgdown creates function reference reference/ includes one page .Rd help topic man/. translation individual help topics Rd HTML generally straightforward, couple things bear mind: pkgdown best autolink references help topics articles described vignette(\"linking\"). pkgdown executes examples, inserting rendered results generated HTML files. default, pkgdown generates reference index just alphabetically-ordered list functions. index much useful human curation functions can grouped described categories. override default, provide reference field _pkgdown.yml. entry reference can take one three forms: title, defined title optional desc (description) fields. subtitle, defined subtitle optional desc (description) fields. list topics defined contents field. Note use starts_with() select functions common prefix. can also use ends_with() matches(). See complete details ?build_reference, including topic matching helper functions. iterating reference index might want run pkgdown::build_reference_index(). just re-builds index page, making faster quickly change _pkgdown.yml see affects site.","code":"reference: - title: \"Connecting to Spark\" desc: > Functions for installing Spark components and managing connections to Spark contents: - spark_config - spark_connect - spark_disconnect - spark_install - spark_log - title: \"Reading and Writing Data\" desc: \"Functions for reading and writing Spark DataFrames.\" contents: - starts_with(\"spark_read\") - starts_with(\"spark_write\") - matches(\"saveload\")"},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"articles","dir":"Articles","previous_headings":"","what":"Articles","title":"Introduction to pkgdown","text":"pkgdown automatically build vignettes found vignettes/, translating HTML files articles/. recommended name intro article package name generate “Get Started” page automatically. Due way pkgdown integrate R Markdown generated HTML HTML, relatively little control available output format. can see details ?build_articles. want include article website package (e.g., ’s large), can use usethis::use_article() set .","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"news","dir":"Articles","previous_headings":"","what":"News","title":"Introduction to pkgdown","text":"NEWS.md present, rendered single-page changelog based markdown level headings. pkgdown assumes NEWS.md formatted using level one headings (#) specify package name version number, level two headings (##) provide topical organization release. See suggestions writing news bullets tidyverse style guide. See ?build_news customisation options including : Create one page major version related minor versions. Add release announcements news navbar drop-.","code":"# pkgdown 1.1.0 ## Bug Fixes * Lots of them # pkgdown 1.0.0 * This is the first release of pkgdown."},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"publishing","dir":"Articles","previous_headings":"","what":"Publishing","title":"Introduction to pkgdown","text":"use GitHub, easiest way build publish site via GitHub actions. Using GitHub actions automatically builds publishes site every time make change. easiest way set run usethis::use_pkgdown_github_pages(), need customize action, see README.md r-lib/actions.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/pkgdown.html","id":"promoting","dir":"Articles","previous_headings":"","what":"Promoting","title":"Introduction to pkgdown","text":"finalized site built published web, publicize URL places: URL field package DESCRIPTION, alongside link source: (usethis::use_pkgdown_github_pages() .) repository description GitHub. (usethis::use_pkgdown_github_pages() .) social media (make sure include #rstats).","code":"URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown"},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"operation","dir":"Articles","previous_headings":"","what":"Operation","title":"quarto vignettes","text":"pkgdown turns articles directory quarto project temporarily adding _quarto.yml articles. can also add want control options quarto articles. , mix .qmd .Rmd files, ’ll need include following yaml RMarkdown can continue handle .Rmd files: setup-r-dependencies action automatically install Quarto GitHub Actions .qmd file present repository (see install-quarto parameter details).","code":"project: render: ['*.qmd']"},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"github-actions","dir":"Articles","previous_headings":"","what":"GitHub Actions","title":"quarto vignettes","text":"setup-r-dependencies action automatically install Quarto GitHub Actions .qmd file present repository (see install-quarto parameter details).","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"limitations","dir":"Articles","previous_headings":"","what":"Limitations","title":"quarto vignettes","text":"Callouts currently supported (https://github.com/quarto-dev/quarto-cli/issues/9963). pkgdown assumes ’re using quarto vignette style, generally html format minimal: true. Specifically, HTML vignettes currently supported. can’t customise mermaid styles quarto mermaid themes. want change colours, ’ll need provide custom CSS shown quarto docs. pkgdown pass lang setting quarto, set available language perfectly matched. Learn https://quarto.org/docs/authoring/language.html, including supply translations.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"supported-features","dir":"Articles","previous_headings":"","what":"Supported features","title":"quarto vignettes","text":"following sections demonstrate bunch useful quarto features can make sure work. Small caps footnote reference1 () sketch pitbull puppy (b) sketch sharpei puppy Figure 1: Cute puppies ∂C∂t+12σ2S2∂2C∂C2+rS∂C∂S=rC(1) \\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2} \\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2} + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ = \\mathrm r \\mathrm C \\qquad(1) See Figure 1 two cute puppies. Black-Scholes (Equation 1) mathematical model seeks explain behavior financial derivatives, commonly options.","code":"1 + 1 #> [1] 2 2 + 2 #> [1] 4 plot(1:3)"},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"inline-formatting","dir":"Articles","previous_headings":"","what":"Inline formatting","title":"quarto vignettes","text":"Small caps footnote reference1","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"code","dir":"Articles","previous_headings":"","what":"Code","title":"quarto vignettes","text":"","code":"1 + 1 #> [1] 2 2 + 2 #> [1] 4 plot(1:3)"},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"figures","dir":"Articles","previous_headings":"","what":"Figures","title":"quarto vignettes","text":"() sketch pitbull puppy (b) sketch sharpei puppy Figure 1: Cute puppies","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"equations","dir":"Articles","previous_headings":"","what":"Equations","title":"quarto vignettes","text":"∂C∂t+12σ2S2∂2C∂C2+rS∂C∂S=rC(1) \\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2} \\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2} + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ = \\mathrm r \\mathrm C \\qquad(1)","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"cross-references","dir":"Articles","previous_headings":"","what":"Cross references","title":"quarto vignettes","text":"See Figure 1 two cute puppies. Black-Scholes (Equation 1) mathematical model seeks explain behavior financial derivatives, commonly options.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/quarto.html","id":"to-do","dir":"Articles","previous_headings":"","what":"To do","title":"quarto vignettes","text":"Code annotations Tabsets Citations Task/lists Figures Equations Cross-references Footnotes Callouts","code":""},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/quarto-features.html","id":"citations","dir":"Articles > Test","previous_headings":"","what":"Citations","title":"quarto features","text":"Citation: Wickham (2014)","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/quarto-features.html","id":"code-annotations","dir":"Articles > Test","previous_headings":"","what":"Code annotations","title":"quarto features","text":"1 Take penguins, , 2 add new columns bill ratio bill area.","code":"library(tidyverse) library(palmerpenguins) 1penguins |> 2 mutate( bill_ratio = bill_depth_mm / bill_length_mm, bill_area = bill_depth_mm * bill_length_mm )"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/quarto-features.html","id":"diagrams","dir":"Articles > Test","previous_headings":"","what":"Diagrams","title":"quarto features","text":"","code":"flowchart LR A[Hard edge] --> B(Round edge) B --> C{Decision} C --> D[Result one] C --> E[Result two]"},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/quarto-features.html","id":"keyboard","dir":"Articles > Test","previous_headings":"","what":"Keyboard","title":"quarto features","text":"Keyboard shortcut: Shift-Ctrl-PShift-Ctrl-P","code":""},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"footnotes","dir":"Articles > Test","previous_headings":"","what":"Footnotes","title":"Output Rendering","text":"Yay1","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"figures","dir":"Articles > Test","previous_headings":"","what":"Figures","title":"Output Rendering","text":"","code":"plot(1:10)"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"external-files","dir":"Articles > Test","previous_headings":"","what":"External files","title":"Output Rendering","text":"","code":"x <- readLines(\"test.txt\") x #> [1] \"a\" \"b\" \"c\" \"d\""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"details-tag","dir":"Articles > Test","previous_headings":"","what":"Details tag","title":"Output Rendering","text":"First paragraph","code":"1 + 2 #> [1] 3"},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"math","dir":"Articles > Test","previous_headings":"","what":"Math","title":"Output Rendering","text":"f(x)=12πσ2e−(x−μ2)2σ2f(x) = \\dfrac{1}{\\sqrt{2\\pi\\sigma^2}} e^{-\\frac{(x-\\mu^2)}{2\\sigma^2}} Inline equations: y=x2y=x^2","code":""},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"line-width","dir":"Articles > Test","previous_headings":"Code","what":"Line width","title":"Output Rendering","text":"","code":"pkgdown:::ruler() #> ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 #> 12345678901234567890123456789012345678901234567890123456789012345678901234567890 cat(rep(\"x \", 100), sep = \"\") #> x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x cat(rep(\"xy\", 100), sep = \"\") #> xyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxy"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"should-be-highlighted","dir":"Articles > Test","previous_headings":"Code","what":"Should be highlighted","title":"Output Rendering","text":"Valid R code \\preformatted{}: R code R block: R code r block: Yaml","code":"mean(a + 1) mean(a + 1) mean(a + 1) yaml: [a, 1]"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"shouldnt-be-highlighted","dir":"Articles > Test","previous_headings":"Code","what":"Shouldn’t be highlighted","title":"Output Rendering","text":"Non-R code \\preformatted{}","code":"yaml: [a, b, c]"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"crayon","dir":"Articles > Test","previous_headings":"Code","what":"Crayon","title":"Output Rendering","text":"text text","code":"cat(cli::col_red(\"This is red\"), \"\\n\") #> This is red cat(cli::col_blue(\"This is blue\\n\"), \"\\n\") #> This is blue #> message(cli::col_green(\"This is green\")) #> This is green warning(cli::style_bold(\"This is bold\")) #> Warning: This is bold stop(cli::style_italic(\"This is italic\")) #> Error: This is italic"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"quoted-text","dir":"Articles > Test","previous_headings":"","what":"Quoted text","title":"Output Rendering","text":"Single-line quote something miscellaneous. Flush 1 space indent 2 space indent 3 space indent","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"this-section-is-unnumbered","dir":"Articles > Test","previous_headings":"","what":"This section is unnumbered","title":"Output Rendering","text":"however bug !","code":""},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"tabset-with-pills","dir":"Articles > Test","previous_headings":"Tabsets","what":"Tabset with pills","title":"Output Rendering","text":"Tab 1 Tab 2 blablablabla “cool” heading blop","code":"1 + 1"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"cool","dir":"Articles > Test","previous_headings":"Tabsets > Tabset with pills","what":"cool","title":"Output Rendering","text":"Stuff","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"tabset-without-pills","dir":"Articles > Test","previous_headings":"Tabsets","what":"Tabset without pills","title":"Output Rendering","text":"Tab 1 Tab 2 something nice tab active","code":"plot(1:42)"},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"fading-tabset","dir":"Articles > Test","previous_headings":"Tabsets","what":"Fading tabset","title":"Output Rendering","text":"English French German Hello! Bonjour! Guten tag.","code":""},{"path":[]},{"path":[]},{"path":[]},{"path":[]},{"path":"https://pkgdown.r-lib.org/dev/articles/test/rendering.html","id":"very-long-words","dir":"Articles > Test","previous_headings":"","what":"Very long words","title":"Output Rendering","text":"word broken across multiple lines mobile, rather making page scroll horizontally: Ccccccccccccaaaaaaaaaaaaaaatttttttttttttttttssssssssssssssss","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/test/widgets.html","id":"widgets","dir":"Articles > Test","previous_headings":"","what":"Widgets","title":"HTML widgets","text":"Test spacing widget. Test spacing widget.","code":""},{"path":"https://pkgdown.r-lib.org/dev/articles/translations.html","id":"translations","dir":"Articles","previous_headings":"","what":"Translations","title":"Translations","text":"Translations contributed community members language currently available, one add ! get started, first check pkgdown issues see anyone filed existing issue. , person filed issue might make great collaborator 😀. Next, install potools usethis: ’ll need familiarise basics translations potools creating pull requests usethis. don’t already know , ’ll need look ISO 639-1 abbreviation language. examples , ’ll pretend ’m providing translations Zulu, code zu. Start initialising pull request: create translation file running potools::po_create(\"zu\"), open po/R-zu.po, starting filling translations. access chatGPT similar, can try prepopulating translations, prompt something like thii: R developer fluent English Zulu. love careful, high quality translations spare time. Complete following po file R pkgdown package (creates websites R packages) supplying translations Zulu. Use inclusive gender forms possible. copy paste complete contents .po file . can check work adding lang: zu _pkgdown.yml running: ’re happy work, make sure compile changes: commit changes Git submit pull request review:","code":"install.packages(c(\"potools\", \"usethis\")) usethis::pr_init(\"translation-zu\") potools::po_compile() devtools::load_all() build_site(\"~/path/to/your/site\") potools::po_compile() usethis::pr_push()"},{"path":"https://pkgdown.r-lib.org/dev/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Hadley Wickham. Author, maintainer. Jay Hesselberth. Author. Maëlle Salmon. Author. Olivier Roy. Author. Salim Brüggemann. Author. Posit Software, PBC. Copyright holder, funder.","code":""},{"path":"https://pkgdown.r-lib.org/dev/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Wickham H, Hesselberth J, Salmon M, Roy O, Brüggemann S (2024). pkgdown: Make Static HTML Documentation Package. R package version 2.1.1.9000, https://github.com/r-lib/pkgdown, https://pkgdown.r-lib.org/.","code":"@Manual{, title = {pkgdown: Make Static HTML Documentation for a Package}, author = {Hadley Wickham and Jay Hesselberth and Maëlle Salmon and Olivier Roy and Salim Brüggemann}, year = {2024}, note = {R package version 2.1.1.9000, https://github.com/r-lib/pkgdown}, url = {https://pkgdown.r-lib.org/}, }"},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"pkgdown-","dir":"","previous_headings":"","what":"Build websites for R packages","title":"Build websites for R packages","text":"pkgdown designed make quick easy build website package. can see pkgdown action https://pkgdown.r-lib.org: output pkgdown applied latest version pkgdown. Learn vignette(\"pkgdown\") ?build_site.","code":""},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Build websites for R packages","text":"","code":"# Install development version from GitHub # install.packages(\"pak\") pak::pak(\"r-lib/pkgdown\")"},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"Build websites for R packages","text":"Get started usethis: adds necessary components sets GitHub Actions1 automatic site building deploying. README.md becomes homepage, documentation man/ generates function reference, vignettes rendered articles/.","code":"# Run once to configure your package to use and deploy pkgdown usethis::use_pkgdown_github_pages() # Preview your site locally before publishing pkgdown::build_site()"},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"pkgdown-200-and-bootstrap-5","dir":"","previous_headings":"Usage","what":"pkgdown 2.0.0 and Bootstrap 5","title":"Build websites for R packages","text":"pkgdown 2.0.0 includes upgrade Bootstrap 3 Bootstrap 5, accompanied whole bunch minor UI improvements. ’ve heavily customised site, ’s small chance break site, everyone needs explicitly opt-upgrade adding following _pkgdown.yml: learn many new ways customise site vignette(\"customise\").","code":"template: bootstrap: 5"},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"in-the-wild","dir":"","previous_headings":"","what":"In the wild","title":"Build websites for R packages","text":"last count, pkgdown used 12,000 packages. examples: bayesplot (source): plotting functions posterior analysis, model checking, MCMC diagnostics. valr (source): read manipulate genome intervals signals. mkin (source): calculation routines based FOCUS Kinetics Report NMF (source): framework perform non-negative matrix factorization (NMF). tidyverse r-lib packages source Comparing source output sites great way learn new pkgdown techniques.","code":""},{"path":"https://pkgdown.r-lib.org/dev/index.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of conduct","title":"Build websites for R packages","text":"Please note project released Contributor Code Conduct. participating project agree abide terms.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/as_pkgdown.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate pkgdown data structure — as_pkgdown","title":"Generate pkgdown data structure — as_pkgdown","text":"generally need use unless need custom site design writing equivalent build_site().","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/as_pkgdown.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate pkgdown data structure — as_pkgdown","text":"","code":"as_pkgdown(pkg = \".\", override = list())"},{"path":"https://pkgdown.r-lib.org/dev/reference/as_pkgdown.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate pkgdown data structure — as_pkgdown","text":"pkg Path package. override optional named list used temporarily override values _pkgdown.yml","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/autolink_html.html","id":null,"dir":"Reference","previous_headings":"","what":"Automatically link references and articles in an HTML page — autolink_html","title":"Automatically link references and articles in an HTML page — autolink_html","text":"Please use downlit::downlit_html_path() instead.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/autolink_html.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Automatically link references and articles in an HTML page — autolink_html","text":"","code":"autolink_html(input, output = input, local_packages = character())"},{"path":"https://pkgdown.r-lib.org/dev/reference/autolink_html.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Automatically link references and articles in an HTML page — autolink_html","text":"input, output Input output paths HTML file local_packages named character vector providing relative paths (value) packages (name) can reached relative links target HTML document.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/autolink_html.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Automatically link references and articles in an HTML page — autolink_html","text":"","code":"if (FALSE) { # \\dontrun{ autolink_html(\"path/to/file.html\", local_packages = c( shiny = \"shiny\", shinydashboard = \"shinydashboard\" ) ) } # }"},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":null,"dir":"Reference","previous_headings":"","what":"Build articles section — build_articles","title":"Build articles section — build_articles","text":"build_articles() renders R Markdown file underneath vignettes/ saves articles/. two exceptions: Files start _ (e.g., _index.Rmd) ignored, enabling use child documents. Files vignettes/tutorials handled build_tutorials() Vignettes rendered using special document format reconciles rmarkdown::html_document() pkgdown template. means articles behave slightly differently vignettes, particularly respect external files, custom output formats. See details. Note run build_articles() directly (outside build_site()) vignettes use currently installed version package, current source version. makes iteration quicker primarily working text article.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Build articles section — build_articles","text":"","code":"build_articles( pkg = \".\", quiet = TRUE, lazy = TRUE, seed = 1014L, override = list(), preview = FALSE ) build_article( name, pkg = \".\", lazy = FALSE, seed = 1014L, new_process = TRUE, pandoc_args = character(), override = list(), quiet = TRUE ) build_articles_index(pkg = \".\", override = list())"},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Build articles section — build_articles","text":"pkg Path package. quiet Set FALSE display output knitr pandoc. useful debugging. lazy TRUE, re-build article input file modified recently output file. seed Seed used initialize random number generation order make article output reproducible. integer scalar NULL seed. override optional named list used temporarily override values _pkgdown.yml preview TRUE, .na(preview) && interactive(), preview freshly generated section browser. name Name article render. either path relative vignettes/ without extension, index README. new_process Build article clean R process? default, TRUE, ensures every article build fresh environment, may want set FALSE make debugging easier. pandoc_args Pass additional arguments pandoc. Used testing.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"index-and-navbar","dir":"Reference","previous_headings":"","what":"Index and navbar","title":"Build articles section — build_articles","text":"can control articles index navbar articles field _pkgdown.yml. use , pkgdown check articles included, error missed . articles field defines list sections, can contain four fields: title (required): title section, appears heading articles index. desc (optional): optional markdown description displayed underneath section title. navbar (optional): couple words used label section navbar. omitted, section vignettes appear navbar. contents (required): list article names include section. can either names individual vignettes call starts_with(). name vignette includes path vignettes without extension name vignette found vignettes/pizza/slice.Rmd pizza/slice. title description individual vignettes displayed index comes title description fields YAML header Rmds. example, yaml might used version dplyr: Note use navbar fields. navbar: ~ means \"Main verbs\" appear navbar without heading; absence navbar field developer vignettes means accessible via articles index. navbar include link articles index one vignettes available navbar. vignettes appear navbar drop-list others , list automatically include \"...\" link bottom; vignettes appear navbar, link directly articles index instead providing drop-.","code":"articles: - title: Main verbs navbar: ~ contents: - one-table - two-table - rowwise - colwise - title: Developer desc: Vignettes aimed at package developers contents: - programming - packages"},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"get-started","dir":"Reference","previous_headings":"","what":"Get started","title":"Build articles section — build_articles","text":"Note vignette name package (e.g., vignettes/pkgdown.Rmd vignettes/articles/pkgdown.Rmd) automatically becomes top-level \"Get started\" link, appear articles drop-. (package name includes ., e.g. pack., use - vignette name, e.g. pack-.Rmd.)","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"missing-articles","dir":"Reference","previous_headings":"","what":"Missing articles","title":"Build articles section — build_articles","text":"pkgdown warn (non-internal) articles listed articles index. can suppress warnings listing affected articles section title: internal (case sensitive); section displayed index page.","code":""},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"external-articles","dir":"Reference","previous_headings":"","what":"External articles","title":"Build articles section — build_articles","text":"can link arbitrary additional articles adding external-articles entry _pkgdown.yml. contain array objects fields name, title, href, description. defined custom articles index, need include name one contents fields.","code":"external-articles: - name: subsampling title: Subsampling for Class Imbalances description: Improve model performance in imbalanced data sets through undersampling or oversampling. href: https://www.tidymodels.org/learn/models/sub-sampling/"},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"external-files","dir":"Reference","previous_headings":"","what":"External files","title":"Build articles section — build_articles","text":"pkgdown differs base R handling external files. building vignettes, R assumes vignettes self-contained (reasonable assumption vignettes PDFs) copies files explicitly listed .install_extras. pkgdown takes different approach based rmarkdown::find_external_resources(), also copy images link . reason automatic detection work, need add resource_files field yaml metadata, e.g.: Note can use fig.path change output directory generated figures default value strong assumption rmarkdown.","code":"--- title: My Document resource_files: - data/mydata.csv - images/figure.png ---"},{"path":"https://pkgdown.r-lib.org/dev/reference/build_articles.html","id":"embedding-shiny-apps","dir":"Reference","previous_headings":"","what":"Embedding Shiny apps","title":"Build articles section — build_articles","text":"like embed Shiny app article, app hosted independently, (e.g. https://www.shinyapps.io). , can embed app article using