Get started

In altdoc: Package Documentation Websites with 'Quarto', 'Docsify', 'Docute', or 'MkDocs'

Quick start

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

library(altdoc)

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

### Render
render_docs()

### Preview
preview_docs()

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

Installation

install.packages("altdoc")

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.md is the homepage of the website.
• vignettes/ stores the vignettes in .md, .Rmd or .qmd format.
• docs/ stores the rendered website. This folder is overwritten every time a user calls render_docs(), so you should not edit it manually.
• altdoc/ stores the settings files created by setup_docs(). These files are never modified automatically after initialization, so you can edit them manually to customize the settings of your documentation and website. All the files stored in altdoc/ are copied to docs/ and made available as static files in the root of the website.
• The content of the (optional) "news" section is stored in NEWS.md or CHANGELOG.md
• The content of the (optional) "code of conduct" section is stored in CODE_OF_CONDUCT.md.
• The license is stored in LICENSE.md or LICENSE.md.

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:

````{verbatim, lang = "markdown"}

knitr::opts_chunk$set(
  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:

![](man/figures/static_image.png)

Initialize

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

Customize

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"):

site_name: $ALTDOC_PACKAGE_NAME
repo_url: $ALTDOC_PACKAGE_URL
repo_name: $ALTDOC_PACKAGE_NAME
plugins:
  - search
nav:
  - Home: README.md
$ALTDOC_VIGNETTE_BLOCK
  - 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():

• $ALTDOC_PACKAGE_NAME: Name of the package from DESCRIPTION.
• $ALTDOC_PACKAGE_VERSION: Version number of the package from DESCRIPTION
• $ALTDOC_PACKAGE_URL: First URL listed in the DESCRIPTION file of the package.
• $ALTDOC_PACKAGE_URL_GITHUB: First URL that contains "github.com" from the URLs listed in the DESCRIPTION file of the package. If no such URL is found, lines containing this variable are removed from the settings file.
• $ALTDOC_MAN_BLOCK: Nested list of links to the individual help pages for each exported function of the package. The format of this block depends on the documentation generator.
• $ALTDOC_VIGNETTE_BLOCK: Nested list of links to the vignettes. The format of this block depends on the documentation generator. Note that PDF files in the "vignettes/" folder are included, except when docute is used.
• $ALTDOC_VERSION: Version number of the altdoc package.

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:

• https://docsify.js.org/
• https://docute.egoist.dev/
• https://www.mkdocs.org/

Render and update

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

render_docs()

This function will:

1. Render and copy standard R package files to docs/.
2. Ex: NEWS.md, README.md, LICENSE.md, CODE_OF_CONDUCT.md, etc.
3. Render Rmarkdown and Quarto files (.Rmd and .qmd extensions) from the vignettes/ directory and store them in docs/vignettes/.
4. Copy Markdown files with extension .md from vignettes/ to docs/vignettes/.
5. Convert the manual pages stored in man/ from .Rd to .md format, and copy them to docs/man/.
6. 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.

Preview

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:

preview_docs()

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.

Test

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

with(mtcars, plot(mpg, wt))

altdoc documentation built on April 3, 2025, 10:52 p.m.