Write Quarto books with Bioconductor

Package: BiocBookDemo
Authors: Jacques Serizay [aut, cre]
Compiled: 2025-04-10
Package version: 1.5.1
R version: R Under development (unstable) (2025-03-08 r87910)
BioC version: 3.21
License: MIT + file LICENSE

What are BiocBooks?

BiocBooks are package-based, versioned online books with a supporting Docker image for each book version.

A BiocBook can be created by authors (e.g. R developers, but also scientists, teachers, communicators, …) who wish to:

  1. Write: compile a body of biological and/or bioinformatics knowledge;
  2. Containerize: provide Docker images to reproduce the examples illustrated in the compendium;
  3. Publish: deploy an online book to disseminate the compendium;
  4. Version: automatically generate specific online book versions and Docker images for specific Bioconductor releases.
Tip

A {BiocBook}-based package hosted on GitHub with a branch named RELEASE_X_Y provides:

  • A Docker image: hosted on ghcr.io;
  • An online book (a.k.a website): hosted on the GitHub repository gh-pages branch;

Both are built against the specific Bioconductor release X.Y.

A {BiocBook}-based package submitted to Bioconductor also lead to the online book being independently built by the Bioconductor Build System (BBS) and deployed to https://bioconductor.org/books/<bioc_version>/<pkg>/

What is this {BiocBook} package?

The {BiocBook} package offers a streamlined approach to creating BiocBooks, with several important benefits:

  • The author creates a {BiocBook}-based package without leaving R;
  • The author writes book chapters in pages/*.qmd files using enhanced markdown;
  • The author can submit its {BiocBook}-based package to Bioconductor.

The containerization and publishing of the new {BiocBook}-based package is automated:

  • A Github Action workflow generates different Docker images for different Bioconductor releases, with the packages used in the book pre-installed;
  • A Github Action workflow publishes different book versions for different Bioconductor releases.

Main features of BiocBooks

Fully compatible with the Bioconductor Build System

When a {BiocBook}-based package is accepted into Bioconductor, it is automatically integrated into the Bionconductor Build System (BBS).

This means that it is getting built using R CMD build --keep-empty-dirs --no-resave-data .. This triggers the rendering of the book contained in /inst/. Book packages built by the BBS are then automatically deployed and are eventually available at https://bioconductor.org/books/<bioc_version>/<pkg>/.

Automated versioning of Docker images

A separate Docker image is built for each branch (named devel or RELEASE_X_Y) of a {BiocBook}-based Github repository.

Each Docker image provides pre-installed R packages:

  • Bioconductor release X.Y;
  • Specific book dependencies from Bioconductor release X.Y (listed in DESCRIPTION);
  • The book package itself

The Docker images also include a micromamba-based environment, named BiocBook, in which all the softwares listed in requirements.yml are installed.

For example, Docker images built from the {BiocBookDemo} package repository are available here:

πŸ‘‰ ghcr.io/js2264/biocbookdemo 🐳

Get started now πŸŽ‰

You can get access to all the packages used in this book in < 1 minute, using this command in a terminal:

bash
docker run -it ghcr.io/js2264/biocbookdemo:devel R

Automated versioning of the online book

Regardless of whether the book package is submitted to Bioconductor, a Github Actions workflow publishes individual online books for each branch (named devel or RELEASE_X_Y) of a BiocBook-based Github repository.

For example, the online book version matching the devel version of the {BiocBook} package is available from:

πŸ‘‰ http://js2264.github.io/BiocBookDemo/devel/ πŸ“˜

RStudio Server

An RStudio Server instance based on a specific Bioconductor <version> (devel or RELEASE_X_Y) can be initiated from the corresponding Docker image as follows:

bash
docker run \
    --volume <local_folder>:<destination_folder> \
    -e PASSWORD=OHCA \
    -p 8787:8787 \
    ghcr.io/<github_user>/<biocbook_repo>:<version>

The initiated RStudio Server instance will be available at https://localhost:8787.

Further instructions regarding Bioconductor-based Docker images are available here.

Acknowledgments

This works was inspired by and closely follows the strategy used in coordination by the Bioconductor core team and Aaron Lun to submit book-containing packages (from the OSCA series as well as SingleR and csaw books).

  • Orchestrating Single-Cell Analysis with Bioconductor (n.d.)
  • Assigning cell types with SingleR (2023)
  • The csaw Book (2023)

This package was also inspired by the *down package series, including:

  • Xie (2014)
  • Xie (2016)
  • Wickham, Hesselberth, and Salmon (2022)

Session info

sessioninfo::session_info(
    installed.packages()[,"Package"], 
    include_base = TRUE
)
##  ─ Session info ────────────────────────────────────────────────────────────
##   setting  value
##   version  R Under development (unstable) (2025-03-08 r87910)
##   os       Ubuntu 24.04.1 LTS
##   system   x86_64, linux-gnu
##   ui       X11
##   language (EN)
##   collate  C
##   ctype    en_US.UTF-8
##   tz       Etc/UTC
##   date     2025-04-10
##   pandoc   3.6.3 @ /usr/bin/ (via rmarkdown)
##   quarto   1.5.57 @ /usr/local/bin/quarto
##  
##  ─ Packages ────────────────────────────────────────────────────────────────
##   package        * version date (UTC) lib source
##   askpass          1.2.1   2024-10-04 [2] CRAN (R 4.5.0)
##   base           * 4.5.0   2025-03-09 [3] local
##   base64enc        0.1-3   2015-07-28 [2] CRAN (R 4.5.0)
##   BiocBookDemo     1.5.1   2025-04-10 [1] local
##   BiocManager      1.30.25 2024-08-28 [2] CRAN (R 4.5.0)
##   BiocStyle        2.35.0  2024-10-29 [2] Bioconductor 3.21 (R 4.5.0)
##   BiocVersion      3.21.1  2024-10-29 [2] Bioconductor 3.21 (R 4.5.0)
##   bookdown         0.42    2025-01-07 [2] CRAN (R 4.5.0)
##   boot             1.3-31  2024-08-28 [3] CRAN (R 4.5.0)
##   brew             1.0-10  2023-12-16 [2] CRAN (R 4.5.0)
##   brio             1.1.5   2024-04-24 [2] CRAN (R 4.5.0)
##   bslib            0.9.0   2025-01-30 [2] CRAN (R 4.5.0)
##   cachem           1.1.0   2024-05-16 [2] CRAN (R 4.5.0)
##   callr            3.7.6   2024-03-25 [2] CRAN (R 4.5.0)
##   class            7.3-23  2025-01-01 [3] CRAN (R 4.5.0)
##   cli              3.6.4   2025-02-13 [2] CRAN (R 4.5.0)
##   clipr            0.8.0   2022-02-22 [2] CRAN (R 4.5.0)
##   cluster          2.1.8.1 2025-03-12 [3] CRAN (R 4.5.0)
##   codetools        0.2-20  2024-03-31 [3] CRAN (R 4.5.0)
##   commonmark       1.9.5   2025-03-17 [2] CRAN (R 4.5.0)
##   compiler         4.5.0   2025-03-09 [3] local
##   cpp11            0.5.2   2025-03-03 [2] CRAN (R 4.5.0)
##   crayon           1.5.3   2024-06-20 [2] CRAN (R 4.5.0)
##   credentials      2.0.2   2024-10-04 [2] CRAN (R 4.5.0)
##   curl             6.2.2   2025-03-24 [2] CRAN (R 4.5.0)
##   datasets       * 4.5.0   2025-03-09 [3] local
##   desc             1.4.3   2023-12-10 [2] CRAN (R 4.5.0)
##   devtools         2.4.5   2022-10-11 [2] CRAN (R 4.5.0)
##   diffobj          0.3.5   2021-10-05 [2] CRAN (R 4.5.0)
##   digest           0.6.37  2024-08-19 [2] CRAN (R 4.5.0)
##   docopt           0.7.2   2025-03-25 [2] CRAN (R 4.5.0)
##   downlit          0.4.4   2024-06-10 [2] CRAN (R 4.5.0)
##   ellipsis         0.3.2   2021-04-29 [2] CRAN (R 4.5.0)
##   evaluate         1.0.3   2025-01-10 [2] CRAN (R 4.5.0)
##   fansi            1.0.6   2023-12-08 [2] CRAN (R 4.5.0)
##   fastmap          1.2.0   2024-05-15 [2] CRAN (R 4.5.0)
##   fontawesome      0.5.3   2024-11-16 [2] CRAN (R 4.5.0)
##   foreign          0.8-90  2025-03-31 [3] CRAN (R 4.5.0)
##   fs               1.6.5   2024-10-30 [2] CRAN (R 4.5.0)
##   gert             2.1.5   2025-03-25 [2] CRAN (R 4.5.0)
##   gh               1.4.1   2024-03-28 [2] CRAN (R 4.5.0)
##   gitcreds         0.1.2   2022-09-08 [2] CRAN (R 4.5.0)
##   glue             1.8.0   2024-09-30 [2] CRAN (R 4.5.0)
##   graphics       * 4.5.0   2025-03-09 [3] local
##   grDevices      * 4.5.0   2025-03-09 [3] local
##   grid             4.5.0   2025-03-09 [3] local
##   highr            0.11    2024-05-26 [2] CRAN (R 4.5.0)
##   htmltools        0.5.8.1 2024-04-04 [2] CRAN (R 4.5.0)
##   htmlwidgets      1.6.4   2023-12-06 [2] CRAN (R 4.5.0)
##   httpuv           1.6.15  2024-03-26 [2] CRAN (R 4.5.0)
##   httr2            1.1.2   2025-03-26 [2] CRAN (R 4.5.0)
##   ini              0.3.1   2018-05-20 [2] CRAN (R 4.5.0)
##   jquerylib        0.1.4   2021-04-26 [2] CRAN (R 4.5.0)
##   jsonlite         2.0.0   2025-03-27 [2] CRAN (R 4.5.0)
##   KernSmooth       2.23-26 2025-01-01 [3] CRAN (R 4.5.0)
##   knitr            1.50    2025-03-16 [2] CRAN (R 4.5.0)
##   later            1.4.1   2024-11-27 [2] CRAN (R 4.5.0)
##   lattice          0.22-7  2025-04-02 [3] CRAN (R 4.5.0)
##   lifecycle        1.0.4   2023-11-07 [2] CRAN (R 4.5.0)
##   littler          0.3.21  2025-03-25 [2] CRAN (R 4.5.0)
##   magrittr         2.0.3   2022-03-30 [2] CRAN (R 4.5.0)
##   MASS             7.3-65  2025-02-28 [3] CRAN (R 4.5.0)
##   Matrix           1.7-3   2025-03-11 [3] CRAN (R 4.5.0)
##   memoise          2.0.1   2021-11-26 [2] CRAN (R 4.5.0)
##   methods        * 4.5.0   2025-03-09 [3] local
##   mgcv             1.9-3   2025-04-04 [3] CRAN (R 4.5.0)
##   mime             0.13    2025-03-17 [2] CRAN (R 4.5.0)
##   miniUI           0.1.1.1 2018-05-18 [2] CRAN (R 4.5.0)
##   nlme             3.1-168 2025-03-31 [3] CRAN (R 4.5.0)
##   nnet             7.3-20  2025-01-01 [3] CRAN (R 4.5.0)
##   openssl          2.3.2   2025-02-03 [2] CRAN (R 4.5.0)
##   parallel         4.5.0   2025-03-09 [3] local
##   pillar           1.10.1  2025-01-07 [2] CRAN (R 4.5.0)
##   pkgbuild         1.4.7   2025-03-24 [2] CRAN (R 4.5.0)
##   pkgconfig        2.0.3   2019-09-22 [2] CRAN (R 4.5.0)
##   pkgdown          2.1.1   2024-09-17 [2] CRAN (R 4.5.0)
##   pkgload          1.4.0   2024-06-28 [2] CRAN (R 4.5.0)
##   praise           1.0.0   2015-08-11 [2] CRAN (R 4.5.0)
##   preprocessCore   1.69.0  2024-10-29 [2] Bioconductor 3.21 (R 4.5.0)
##   prettyunits      1.2.0   2023-09-24 [2] CRAN (R 4.5.0)
##   processx         3.8.6   2025-02-21 [2] CRAN (R 4.5.0)
##   profvis          0.4.0   2024-09-20 [2] CRAN (R 4.5.0)
##   promises         1.3.2   2024-11-28 [2] CRAN (R 4.5.0)
##   ps               1.9.0   2025-02-18 [2] CRAN (R 4.5.0)
##   purrr            1.0.4   2025-02-05 [2] CRAN (R 4.5.0)
##   R6               2.6.1   2025-02-15 [2] CRAN (R 4.5.0)
##   ragg             1.3.3   2024-09-11 [2] CRAN (R 4.5.0)
##   rappdirs         0.3.3   2021-01-31 [2] CRAN (R 4.5.0)
##   rcmdcheck        1.4.0   2021-09-27 [2] CRAN (R 4.5.0)
##   Rcpp             1.0.14  2025-01-12 [2] CRAN (R 4.5.0)
##   remotes          2.5.0   2024-03-17 [2] CRAN (R 4.5.0)
##   rlang            1.1.5   2025-01-17 [2] CRAN (R 4.5.0)
##   rmarkdown        2.29    2024-11-04 [2] CRAN (R 4.5.0)
##   roxygen2         7.3.2   2024-06-28 [2] CRAN (R 4.5.0)
##   rpart            4.1.24  2025-01-07 [3] CRAN (R 4.5.0)
##   rprojroot        2.0.4   2023-11-05 [2] CRAN (R 4.5.0)
##   rstudioapi       0.17.1  2024-10-22 [2] CRAN (R 4.5.0)
##   rversions        2.1.2   2022-08-31 [2] CRAN (R 4.5.0)
##   sass             0.4.9   2024-03-15 [2] CRAN (R 4.5.0)
##   sessioninfo      1.2.3   2025-02-05 [2] CRAN (R 4.5.0)
##   shiny            1.10.0  2024-12-14 [2] CRAN (R 4.5.0)
##   sourcetools      0.1.7-1 2023-02-01 [2] CRAN (R 4.5.0)
##   spatial          7.3-18  2025-01-01 [3] CRAN (R 4.5.0)
##   splines          4.5.0   2025-03-09 [3] local
##   stats          * 4.5.0   2025-03-09 [3] local
##   stats4           4.5.0   2025-03-09 [3] local
##   stringi          1.8.7   2025-03-27 [2] CRAN (R 4.5.0)
##   stringr          1.5.1   2023-11-14 [2] CRAN (R 4.5.0)
##   survival         3.8-3   2024-12-17 [3] CRAN (R 4.5.0)
##   sys              3.4.3   2024-10-04 [2] CRAN (R 4.5.0)
##   systemfonts      1.2.2   2025-04-04 [2] CRAN (R 4.5.0)
##   tcltk            4.5.0   2025-03-09 [3] local
##   testthat         3.2.3   2025-01-13 [2] CRAN (R 4.5.0)
##   textshaping      1.0.0   2025-01-20 [2] CRAN (R 4.5.0)
##   tibble           3.2.1   2023-03-20 [2] CRAN (R 4.5.0)
##   tinytex          0.56    2025-02-26 [2] CRAN (R 4.5.0)
##   tools            4.5.0   2025-03-09 [3] local
##   urlchecker       1.0.1   2021-11-30 [2] CRAN (R 4.5.0)
##   usethis          3.1.0   2024-11-26 [2] CRAN (R 4.5.0)
##   utf8             1.2.4   2023-10-22 [2] CRAN (R 4.5.0)
##   utils          * 4.5.0   2025-03-09 [3] local
##   vctrs            0.6.5   2023-12-01 [2] CRAN (R 4.5.0)
##   waldo            0.6.1   2024-11-07 [2] CRAN (R 4.5.0)
##   whisker          0.4.1   2022-12-05 [2] CRAN (R 4.5.0)
##   withr            3.0.2   2024-10-28 [2] CRAN (R 4.5.0)
##   xfun             0.52    2025-04-02 [2] CRAN (R 4.5.0)
##   xml2             1.3.8   2025-03-14 [2] CRAN (R 4.5.0)
##   xopen            1.0.1   2024-04-25 [2] CRAN (R 4.5.0)
##   xtable           1.8-4   2019-04-21 [2] CRAN (R 4.5.0)
##   yaml             2.3.10  2024-07-26 [2] CRAN (R 4.5.0)
##   zip              2.3.2   2025-02-01 [2] CRAN (R 4.5.0)
##  
##   [1] /tmp/RtmpciTFN8/Rinst8c1d749834
##   [2] /usr/local/lib/R/site-library
##   [3] /usr/local/lib/R/library
##   * ── Packages attached to the search path.
##  
##  ───────────────────────────────────────────────────────────────────────────

References

Assigning cell types with SingleR. 2023. https://bioconductor.org/books/3.17/SingleRBook.
Orchestrating Single-Cell Analysis with Bioconductor. n.d. https://bioconductor.org/books/devel/OSCA.
The csaw Book. 2023. https://bioconductor.org/books/devel/csawBook.
Wickham, Hadley, Jay Hesselberth, and MaΓ«lle Salmon. 2022. Pkgdown: Make Static HTML Documentation for a Package. https://CRAN.R-project.org/package=pkgdown.
Xie, Yihui. 2014. β€œKnitr: A Comprehensive Tool for Reproducible Research in R.” In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC.
β€”β€”β€”. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/bookdown.
Back to top