Developer Guide

Contributing

This project is currently under active development, and contributions from the community are very welcome.

To maintain an inclusive environment for contributors from around the world, and to ensure that discussions are understandable and maintainable by as many developers as possible, please prefer using English when opening issues, submitting pull requests, or participating in development discussions.

Computation-Intensive Documents

For any vignettes involving actual computation and execution, such as simulation tutorials, please adopt a local pre-compilation approach to accelerate the GitHub Pages build process.

The corresponding file structure for each document is as follows. For example, for a document named tutorial-a:

.
├── vignettes
│   ├── tutorial-a.Rmd.orig      # Pre-compilation source file (can be omitted for documents without computation)
│   ├── tutorial-a.Rmd           # Final file generated from source
│   └── tutorial-a/              # Subdirectory for storing resources and pre-compiled figures

Local Pre-compilation

First, in the vignettes/ directory, rename the Rmd file that requires pre-compilation to *.Rmd.orig, for example tutorial-a.Rmd.orig.

Ensure that in the Rmd file, you configure the figure path to a subdirectory under vignettes/ with the same name, and prefer using vector graphics formats (such as SVG) for better scaling. An example configuration:

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "./tutorial-a/",
  dev = "svg",
  fig.ext = "svg"
)

Then, in your local R environment, run the appropriate line from the code below to generate the final Rmd file:

# In R environment
source("scripts/knit_vignettes.R")

# Or in terminal
Rscript scripts/knit_vignettes.R

# If you need to force recompile all scripts (not recommended)
Rscript scripts/knit_vignettes.R false

Alternatively, you can manually modify and run the following code snippet to compile a specific Rmd file:

old <- getwd()
setwd("vignettes")

knitr::knit(
  "tutorial-a.Rmd.orig",
  output = "tutorial-a.Rmd"
)

setwd(old)

Add Document to _pkgdown

Once you have completed the pre-compilation process, ensure that the new Rmd file is properly referenced in the _pkgdown.yml file. For example:

articles:
- title: Tutorials
  navbar: Tutorials
  contents:
  - another-document
  - tutorial-a

Commit Changes

Afterwards, you can try building the pkgdown site locally to ensure everything works correctly:

pkgdown::build_site()

After confirming that all content is correct, commit both the *.Rmd.orig and the generated *.Rmd files.

Additionally, please do not manually modify the generated *.Rmd files. We should assume that these files are automatically generated from their corresponding *.Rmd.orig files.