Skip to content
B-Cubed documentation

Contributing guide

This guide outlines how to make contributions to this website.

Code of conduct

Section titled “Code of conduct”

Please note that this website is released with a Contributor Code of Conduct. By contributing, you agree to abide by its terms.

Technology

Section titled “Technology”

This website makes use of Astro (a web framework) and Starlight (a documentation theme for Astro) to transform Markdown and configuration files to a static website. A GitHub action will automatically rebuild this site on GitHub Pages for each commit on the main branch.

To preview this site locally, use:

  • npm install to install dependencies.
  • npm run dev to start a local development server at localhost:4321 where you can preview the site.

See the file astro.config.mjs for site-wide configuration.

Editing pages

Section titled “Editing pages”

The site contains two types of pages/tutorials: source pages and external pages. They differ in the way they are updated.

Source pages

Section titled “Source pages”

Source pages are maintained in the GitHub repository of this site. The homepage and pages listed under Guides, Infrastructure and Tutorials are source pages.

To update a source page:

  1. On this site, click Edit page at the bottom of the page. This will open the underlying Markdown file in GitHub.
  2. Make changes in the Markdown file (either in your browser or locally).
  3. Commit your changes to a new branch (and push).
  4. Create a pull request and assign a reviewer.
  5. Once accepted and merged, your changes will go live on this site.

To add a source page:

  1. Browse to src/content/docs/ and select the appropriate directory for your page (typically guides or tutorials).
  2. Look at the existing Markdown files for inspiration and syntax, then choose Add file > Create new file to add a new page.
  3. Follow steps 2-5 above.

Does your page contain images or data? Place them in public/<page-type>/<name-of-page>/. It’s best to do this locally on your new branch. To refer to images in Markdown, use:

![Short description](/<page-type>/<name-of-page>/<name-of-image>.png)

Source pages are licensed under a Creative Commons Attribution 4.0 International License.

External pages

Section titled “External pages”

External pages are maintained elsewhere. To centralize documentation on this site, they are copied (and executed) from their source using a semi-automated workflow. The pages listed under Software are external pages.

The workflow supports:

  1. README.md files.
  2. README.Rmd files.
  3. Vignettes, i.e. R package tutorials maintained with their source code (example).
  4. rst files.

To update or add an external page:

  1. Clone this repository.
  2. Check if vignette is listed in vignettes.yml (organized by R package). If not, add it (use the other vignettes as examples).
  3. Open documentation.Rproj in R Studio.
  4. Pull external files and create pages for this website:
    • For rst files only: Open rst_to_md.Rmd and run all code. This will create markdown files in interim.
    • For all files: Open rmd_to_md.Rmd, select the package and run all code. Thanks to b3doc, this will rebuild all vignettes and put the Markdown and images files in the appropriate folders.
  5. Check if you encountered any errors. If yes, fix and rebuild again.
  6. Commit your changes to a new branch (and push).
  7. Create a pull request and assign a reviewer.
  8. Once accepted and merged, your changes will go live on this site.

Do you want to include an external page that is not a vignette? Create an issue.