Get Started

Learn how to get started with the basics of pkgdocs.

Prerequisites

You will need: A source R package you want to generate docs for.

You will also need either of the following:

Overview

Building a documentation site with pkgdocs is a three-step process:

  1. “building”: generating markdown content from your package sources
  2. “publishing”: rendering the markdown content into a static web site.
  3. “deployment”: moving the static web assets to location where it’s accessible by your target audience.
  1. is out-of-scope since it’s not specific to pkgdocs and lots has been written on the subject. A good starting point is https://gohugo.io/hosting-and-deployment/

The remainder of this vignette will deal with (1) and (2).

Build

To get started with your site, run the following in a working directory that contains your R package and a README.md if you have one (typically the repository root if you are using version control):

pkgdocs::build()

The first time you run it, this function will generate the following content in a docs folder:

  • a Hugo configuration file
  • articles: markdown pages for each of your package vignettes
  • reference: markdown pages for each of the topics documented in your package man/ folder
  • home, changelog and license pages based on package metadata

Publishing

To convert your markdown pages into a static website, you need to run hugo. A typical approach is to run this step as part of a continuous integration workflow

For development and debugging purposes however, you can use the builtin webserver in hugo to serve the site locally. If you make any change to the markdown pages while the server is running, for example by re-running pkgdocs::build() the website will update according automatically.

The remainder of this section shows how to do this both for the case where you have hugo installed directly on your system and for the case where you only want to run hugo through docker.

Publishing Locally

You can run hugo commands through pkgdocs.

The first step is to check whether Hugo is installed:

pkgdocs::hugo_available()

Which should return TRUE. If that’s not the case check whether you installed Hugo correctly and that it’s available on the ssytem path.

To start the webserver, run:

setwd("docs")
pkgdocs::hugo_server()

You should expect to see some output, ending with:

Built in 960 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Navigate your browser to http://localhost:1313 and you should very own package documentation site!

Publishing Locally with Docker Compose

If you have Docker installed you can also run Hugo through Docker instead of installing it on your system. This has the additional benefit of easily being able to lock down a specific hugo version for your project.

You can generate a compose file with:

pkgdocs::write_hugo_compose_file()

Then, in a terminal shell, run:

docker compose up

And navigate your browser to http://localhost:1313

Troubleshooting

  • Could not find a github repository in your package metadata.

    A github repository is required if you wish to import the default theme (Docsy) automatically.You can pass one directly as an argument (github_repo) to build or mention one in your DESCRIPTION (e.g. via ?usethis::use_github_links).

    Note that the repository doesn’t need to actually exist: all that’s necessary is a unique name to be able to import hugo modules.