Get started

Quick start

To create, render, and preview a new documentation website, execute these commands from the root directory of your package:


### Initialize
## setup_docs("docute")
## setup_docs("mkdocs")

### Render

### Preview

Below, we explain in more detail what these commands do.



To create documentation websites with either docsify or docute, you only need to install altdoc in R. The rest of this section only concerns mkdocs users.

The procedure to use mkdocs is slightly more involved. mkdocs is a Python library, meaning that you will first need to set up a Python virtual environment (or “venv”) in your package folder. In the terminal, run the following:

python -m venv .venv_altdoc

Then, you can now install mkdocs (and other libraries such as mkdocs-material if needed). The correct commands to run can depend on your environment. For example, on Linux or Mac, this command may work:

.venv_altdoc/bin/pip install mkdocs mkdocs-material

On Windows, this might work:

.venv_altdoc\Scripts\pip.exe install mkdocs mkdocs-material

See the mkdocs and mkdocs-material installation guides for details.

Package structure

altdoc makes assumptions about your package structure:

README images

When using a Rmarkdown or Quarto document to generate the README and Home Page of the package website, we recommend that you include this code chunk at the top of the document:

  fig.path = "man/figures/README-"

This will store images in the man/ and allow them to be displayed on CRAN, Github, as well as on the website.

Static images can also be stored in man/, and linked using the normal syntax, ex:



These functions initialize a documentation website structure: setup_docs(tool = "docsify"), setup_docs(tool = "docute") and setup_docs(tool = "mkdocs"). Calling one of them will:

  1. Create a docs/ folder
  2. Create a altdoc/ folder
  3. Add altdoc/ to .Rbuildignore
  4. Copy default settings files to altdoc/ for the chosen documentation generator


To customize the documentation, you can edit the settings files in the altdoc/ folder. The settings files differ between the different documentation generators. For example, this is the default mkdocs.yml settings created when one calls setup_docs(tool = "mkdocs"):

  - search
  - Home:
  - Changelog: $ALTDOC_NEWS
  - Code of Conduct: $ALTDOC_CODE_OF_CONDUCT
  - License: $ALTDOC_LICENSE

By editing this file, you can change the name of the website, the order of the sections, add new sections or drop irrelevant ones, etc.

The settings files can include $ALTDOC variables which are replaced automatically by altdoc when calling render_docs():

Also note that you can store images and static files in the altdoc/ directory. All the files in this folder are copied to docs/ and made available in the root of the website, so you can link to them easily.

Interested readers should refer to their chosen documentation generator documentation for more details:

Render and update

Once the documentation is initialized, you can render it with:


This function will:

  1. Render and copy standard R package files to docs/.
    • Ex:,,,, etc.
  2. Render Rmarkdown and Quarto files (.Rmd and .qmd extensions) from the vignettes/ directory and store them in docs/vignettes/.
  3. Copy Markdown files with extension .md from vignettes/ to docs/vignettes/.
  4. Convert the manual pages stored in man/ from .Rd to .md format, and copy them to docs/man/.
  5. Copy all static files from altdoc/ to docs/.

Whenever you make changes to the man pages or to the vignettes, you can call render_docs() again to render the new files and update the website.


To preview the website, you need to run a local web server.

In RStudio you can launch one automatically in the Preview Pane by calling:


In Visual Studio Code, you can use one of the many “live preview” or “local server” extensions available. For example,

  1. Install the Live Preview extension from Microsoft.
  2. From the command palette, select “Live Preview: Start Server”.
  3. When the preview pane opens, navigate to the docs/ folder.

The code and images in this subsection are inserted as a demonstration of images in Rmarkdown vignettes.

with(mtcars, plot(mpg, wt))