{"id":14066597,"url":"https://github.com/carpentries/sandpaper","last_synced_at":"2026-03-09T15:31:18.731Z","repository":{"id":37261372,"uuid":"284129340","full_name":"carpentries/sandpaper","owner":"carpentries","description":"User Interface for The Carpentries Workbench","archived":false,"fork":false,"pushed_at":"2026-03-06T13:17:51.000Z","size":25197,"stargazers_count":47,"open_issues_count":107,"forks_count":32,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-03-06T13:53:12.241Z","etag":null,"topics":["carpentries","carpentries-infrastructure","carpentries-workbench","lesson-template","lessons","markdown","r","r-package","static-site-generator"],"latest_commit_sha":null,"homepage":"https://carpentries.github.io/sandpaper","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carpentries.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["carpentries"],"custom":["https://www.zeffy.com/en-US/donation-form/donate-to-make-a-difference-7497"]}},"created_at":"2020-07-31T21:05:12.000Z","updated_at":"2026-03-06T13:10:55.000Z","dependencies_parsed_at":"2023-12-18T16:43:50.992Z","dependency_job_id":"1f157734-3790-4a5d-87b8-2eb462ee1b31","html_url":"https://github.com/carpentries/sandpaper","commit_stats":null,"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/carpentries/sandpaper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Fsandpaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Fsandpaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Fsandpaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Fsandpaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carpentries","download_url":"https://codeload.github.com/carpentries/sandpaper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Fsandpaper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30301109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T14:33:48.460Z","status":"ssl_error","status_checked_at":"2026-03-09T14:33:48.027Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["carpentries","carpentries-infrastructure","carpentries-workbench","lesson-template","lessons","markdown","r","r-package","static-site-generator"],"created_at":"2024-08-13T07:05:10.786Z","updated_at":"2026-03-09T15:31:18.667Z","avatar_url":"https://github.com/carpentries.png","language":"R","funding_links":["https://github.com/sponsors/carpentries","https://www.zeffy.com/en-US/donation-form/donate-to-make-a-difference-7497"],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n# {sandpaper}: User Interface to The Carpentries Workbench \u003cimg src='man/figures/logo.png' align='right' alt='' width=120 /\u003e\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  eval = FALSE,\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\", out.width = \"100%\")\n```\n\n\u003c!-- badges: start --\u003e\n[![R Universe](https://carpentries.r-universe.dev/badges/sandpaper)](https://carpentries.r-universe.dev/ui#builds)\n[![Codecov test coverage](https://codecov.io/gh/carpentries/sandpaper/branch/main/graph/badge.svg)](https://codecov.io/gh/carpentries/sandpaper?branch=main)\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)\n[![CRAN status](https://www.r-pkg.org/badges/version/sandpaper)](https://CRAN.R-project.org/package=sandpaper)\n[![R-CMD-check](https://github.com/carpentries/sandpaper/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/carpentries/sandpaper/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\nThe {sandpaper} package was created by [The Carpentries] to re-imagine our method\nof creating lesson websites for our workshops. This package will take a series\nof [Markdown] or [RMarkdown] files and generate a static website with the\nfeatures and styling of The Carpentries lessons including customized layouts and\ncallout blocks. Much of the functionality in this package is inspired by\n[Jenny Bryan's](https://jennybryan.org/) work with the [{usethis}] package.\n\n## Documentation\n\n**Want to know how this works in a lesson format? Head over to\n\u003chttps://carpentries.github.io/sandpaper-docs/\u003e.**\n\nIf, instead, you already know how a lesson is built and are interested in\nunderstanding how the functions in {sandpaper} work, you can visit this package\ndocumentation site at \u003chttps://carpentries.github.io/sandpaper/\u003e.\n\n## Installation\n\n{sandpaper} is not currently on CRAN, but it can be installed from our\n[Carpentries Universe](https://carpentries.r-universe.dev/ui#builds) (updated\nevery hour) with the following commands:\n\n``` r\noptions(repos = c(\n  carpentries = \"https://carpentries.r-universe.dev/\",\n  CRAN = \"https://cran.rstudio.com/\"\n))\ninstall.packages(\"sandpaper\", dep = TRUE)\n```\n\nNote that this will also install development versions of the following packages:\n\n| package      | What it does |\n| -------------| ------------ |\n| [{varnish}]  | html, css, and javascript templates for The Carpentries (in progress) |\n| [{tinkr}]    | manipulation of knitr markdown documents built on the commonmark xml library |\n| [{pegboard}] | programmatic interface to lesson components for validation (in progress) |\n\n\n## Design\n\nThis package is designed to make the life of the lesson contributors and\nmaintainers easier by separating the tools needed to build the site from the\nuser-defined content of the site itself. It will no longer rely on Jekyll or\nany of the other [\u003e450 static site generators](https://staticsitegenerators.net),\nbut instead rely on R, RStudio, and [{pkgdown}] to generate a site with the\nfollowing features:\n\n- [x] optional offline use\n- [x] filename-agnostic episode arrangements\n- [x] clear definitions of package versions needed to build the lesson\n- [ ] lesson versioning (e.g. I can navigate to\n   https://swcarpentry.github.io/python-novice-gapminder for the current\n   version and https://swcarpentry.github.io/python-novice-gapminder/2020-11\n   for the release in 2020-11)\n- [x] seamless updates to the Carpentries' style\n- [x] caching of rendered content for rapid deployment\n- [ ] packaging of [{learnr}] materials\n- [x] validation of lesson structure\n- [x] git aware, but does not require contributors to have git installed\n\n### Rendering locally\n\n![The local two-step model of deployment into local folders](vignettes/articles/img/local-flow.dot.svg){alt='diagram of three\nfolders. The first folder, \"episodes/\", labelled as RMarkdown, has an arrow\n(labelled as hash episodes) pointing to \"site/built/\", labelled as Markdown.\nThe Markdown folder has an arrow (labelled as \"apply template\") pointing to\n\"site/docs/\", labelled as \"HTML\". The first folder is labelled in pale yellow,\nindicating that it is the only one tracked by git.'}\n\nIn a repository generated via {sandpaper}, only the source is committed to avoid\nissues surrounding out-of-date artefacts and directory structure confusion.\n\nThe website is generated in two steps:\n\n1. markdown files from the source files are rendered containing a hash for the\n   source file so that these need only be re-rendered when they change.\n2. html files are generated from the rendered markdown files and the CSS and JS\n   sources in the [{varnish}] package for the preview.\n\nTo ensure there are no clashes between minor differences in the user setup, no\nartifacts are committed to the main branch of the repository. Because of the\ncaching mechanism between the website and the rendered markdown files,\nlong-running lessons can be updated and previewed quickly.\n\n### Rendering on continuous integration\n\n![Two-step deployment model on continuous integration](vignettes/articles/img/branch-flow.svg){alt='Diagrammatic representation of the GitHub\ndeployment cycle showing four branches, gh-pages, md-outputs, main, and\nmy-edit. The my-edit branch is a direct descendent of the main branch, while\nthe gh-pages and md-outputs branches are orphans. Each commit of the main\nbranch has a process represented by a dashed arrow that builds a commit of the\nsubsequent orphan branches'}\n\nContinuous integration will act as the single source-of-truth for how the\noutputs of the lessons are rendered. For this, we want the resulting website\nto be:\n\n - CI agnostic (but currently set up with GitHub)\n - easy to set up\n - auditable (e.g. I can see changes between the content of two commits)\n - versionable (e.g. I can instruct learners to go to `\u003cWEBSITE\u003e/1.1`. This\n   is inspired from the python documentation style)\n\nTo acheive this, there will be two branches created: `md-outputs` and `gh-pages`\nthat will inerit like so main -\u003e `md-outputs` -\u003e `gh-pages`. Because the build\ntime from main to `md-outputs` can be time intensive, this will default to\nupdating only files that were changed.\n\n - `md-outputs`: this branch will contain the files and artifacts generated from\n   rmarkdown in the vignettes directory of a thin package skeleton.\n - `gh-pages`: this branch is generated via `md-outputs` and bundles the html,\n   css, and js for the website. This will contain a single `index.html` file\n   with several subfolders with different versions of the site. The `index.html`\n   file will redirect to the `current/` directory, which contains the up-to-date\n   site.\n\n#### Scheduled builds\n\n - `gh-pages` website: Because we are designing the lessons to have content\n   separated from the styling, we will set up the CI to generate the webpage\n   from the pre-built sources on a weekly basis, which will check if there has\n   been an update to the styles (which I have in the [{varnish}] package) and\n   then rebuild the site without rebuilding the content.\n - `md-outputs` branch: This will be rerun every month from scratch with the\n   most recent version of R and R packages. If there is a change, a pull request\n   can be generated to update the `renv.lock` file with a link to the changed\n   markdown files in this branch.\n\n\n### Function syntax\n\nThe functions in {sandpaper} have the following prefixes:\n\n - `create_` will create/amend files or folders in your workspace\n - `update_` will update build resources in the lesson\n - `build_` will build files from your source\n - `validate_` will check the validity of either the elements of the lesson and/or episodes\n - `fetch_` will download files or resources from the internet\n - `reset_` removes files or information\n - `get_` will retrieve information from your source files as an R object\n - `set_` will update information in files.\n - `ci_` interacts with continous integration to build the website\n\nHere is a working list of user-facing functions:\n\n**Lesson and Episode Creation**\n\n - `create_lesson()` creates a lesson from scratch\n - `create_episode()` creates a new episode with the correct number prefix\n - `create_dataset()` creates a csv or text data set from an R object\n - `set_episodes()` arranges the episodes in a user-specified order\n\nAccessors\n\n - `get_config()` reads the contents of `config.yaml` as a list\n - `get_drafts()` reports files that are not listed in `config.yaml`\n - `get_episodes()` returns the episode filenames as a vector\n - `get_syllabus()` returns the syllabus with timings, titles, and questions\n\n**Website Creation and Validation**\n\n - `validate_lesson()` checks and validates the source files and lesson structure\n - `build_episode_md()` renders an individual file to markdown (internal use)\n - `build_episode_html()` renders a built markdown file to html (internal use)\n - `build_lesson()` builds the lesson into a static website\n - `build_portable_lesson()` builds the lesson into a portable static website\n - `build_glossary()` builds a Glosario-based glossary for the lesson\n\n**Continuous Integration Utilities**\n\n - `ci_deploy()` builds and deploys the lesson on CI from the source files\n - `ci_build_markdown()` builds the markdown files on CI from the source and deploys them to the markdown branch.\n - `ci_build_site()` deploys the lesson on CI from pre-rendered markdown files\n - `ci_release()` builds and deploys the lesson on CI from the source files and adds a release tag\n - `update_github_workflows()` updates GitHub workflows\n\nCleanup\n\n - `reset_episodes()` removes the schedule from the config.yaml file\n - `reset_site()` clears the website and cache\n\n## Usage\n\nThere are five use-cases for {sandpaper}:\n\n 1. Creating lessons\n 2. Contributing to lessons\n 3. Maintaining lessons\n 4. Rendering a portable site\n 5. Rendering a site with GitHub actions.\n\n### Creating a lesson\n\nTo create a lesson with {sandpaper}, use the `create_lesson()` function:\n\n```{r}\nsandpaper::create_lesson(\"~/Desktop/r-intermediate-penguins\")\n```\n\nThis will create folder on your desktop called `r-intermediate-penguins` with\nthe following structure:\n\n```\n|-- .gitignore               # - Ignore everything in the site/ folder\n|-- .github/                 # - Scripts used for continuous integration\n|   `-- workflows/           #\n|       |-- deploy-site.yaml # -   Build the source files on github pages\n|       |-- build-md.yaml    # -   Build the markdown files on github pages\n|       `-- cron.yaml        # -   reset package cache and test\n|-- episodes/                # - PUT YOUR MARKDOWN FILES IN THIS FOLDER\n|   |-- data/                # -   Data for your lesson goes here\n|   |-- figures/             # -   All static figures and diagrams are here\n|   |-- files/               # -   Additional files (e.g. handouts)\n|   `-- 00-introducition.Rmd # -   Lessons start with a two-digit number\n|-- instructors/             # - Information for Instructors\n|-- learners/                # - Information for Learners\n|   `-- setup.md             # -   setup instructions (REQUIRED)\n|-- profiles/                # - Learner and/or Instructor Profiles\n|-- site/                    # - This folder is where the rendered markdown files and static site will live\n|   `-- README.md            # -   placeholder\n|-- config.yaml              # - Use this to configure commonly used variables\n|-- CONTRIBUTING.md          # - Carpentries Rules for Contributions (REQUIRED)\n|-- CODE_OF_CONDUCT.md       # - Carpentries Code of Conduct (REQUIRED)\n|-- LICENSE.md               # - Carpentries Licenses (REQUIRED)\n`-- README.md                # - Introduces folks how to use this lesson and where they can find more information.\n```\n\nOnce you have your site set up, you can add your RMarkdown files in the episodes\nfolder. By default, they will be built in alphabetical order, but you can use\nthe `set_episodes()` command to build the schedule in your `config.yaml` file:\n\n```{r}\ns \u003c- sandpaper::get_episodes()\nsandpaper::set_episodes(order = s, write = TRUE)\n```\n\nWhen you want to preview your site, use the following:\n\n```{r}\nsandpaper::build_lesson()\n```\n\n\u003e #### Working in RStudio?\n\u003e\n\u003e If you are using RStudio, you can preview the lesson site using the keyboard\n\u003e shortcut \u003ckbd\u003ectrl + shift + B\u003c/kbd\u003e (which corresponds to the \"Build Website\" button in the \"Build\" tab. To preview individual files, you can use\n\u003e \u003ckbd\u003ectrl + shift + K\u003c/kbd\u003e (This corresponds to the \"Knit\" button in the editor pane)\n\nThis will create the website structure inside of the the `site/` folder, render\nthe RMarkdown files to markdown (for inspection and quick rendering), render the\nmarkdown files to HTML, and then enable a preview within your browser window.\n\n\n### Contributing to a Lesson\n\nTo contribute to a lesson, you can either fork the lesson to your own repository\nand clone it to your computer manually from GitHub, or you can use the {usethis}\npackage to automate it. For example, This is how you can create a copy of\n[**Programming With R**](http://swcarpentry.github.io/r-novice-inflammation/) to\nyour computer's Desktop.\n\n\n```{r}\nusethis::create_from_github(\n  repo = \"swcarpentry/r-novice-gapminder\",\n  destdir = \"~/Desktop/r-novice-gampinder\",\n  fork = TRUE\n)\n```\n\nThis will copy all of the source files to your computer and move you to the\ndirectory.\n\n### Maintaining a Lesson\n\nWhen you are maintaining a lesson, there is a high likelihood that you will\nalready have a copy on your machine. If not, follow the instructions in the\n[contributing to a lesson](#contributing-to-a-lesson) section above.\n\nThe typical workflow will look like this:\n\n1. open the sandpaper project in RStudio and make edits to files in the\n   `episodes/` folder\n2. in the R console run the following\n\n\n```{r}\nsandpaper::validate_lesson() # validates the structure of the input files\nsandpaper::build_lesson() # builds and validates lesson\n```\n\n### Rendering a portable site\n\nTo render a portable site, you can follow the instructions for [contributing\nto a lesson](#contributing-to-a-lesson) or [maintaining a\nlesson](#maintaining-a-lesson) to set up. Once you have the lesson set up, you\ncan use the following command:\n\n```{r}\nsandpaper::build_portable_lesson(version = \"current\")\n```\n\nThis will render a fully portable lesson site as a zip file in the `site/`\nfolder. You can distribute this lesson to learners who do not have reliable\ninternet access for use offline without sacrificing any of the styling.\n\n### Rendering with GitHub actions\n\nUltimately, there should be a minimal number of functions that handle this\nsituation because writing CI configuration files is maddening. The most\nstraightforward function is:\n\n```{r}\nsandpaper::ci_deploy(md_branch = \"md-outputs\", site_branch = \"gh-pages\")\n```\n\nThis function will create [git\nworktrees](https://git-scm.com/docs/git-worktree) for the orphan `md-outputs`\nbranch in the `site/built` folder and the orphan `gh-pages` branch in the\n`site/docs` folder. After that, we generate the site as normal.\n\nBecause css and js libraries may need updating before any lesson material does,\na step can be created just for rebuilding the site that uses:\n\n```{r}\nsandpaper::ci_build_site(branch = \"gh-pages\")\n```\n\nWhen a lesson is given a release, the current site folder needs to be duplicated\nto a versioned folder and a tag needs to be added to the `md-outputs` branch:\n\n```{r}\nsandpaper::ci_release(tag = \"0.1\", md_branch = \"md-outputs\", site_branch = \"gh-pages\")\n```\n\n\n[The Carpentries]: https://carpentries.org\n[Markdown]: https://www.markdownguide.org/getting-started/\n[RMarkdown]: https://rmarkdown.rstudio.com/\n[{learnr}]: https://rstudio.github.io/learnr/index.html\n[{remotes}]: https://remotes.r-lib.org/\n[{usethis}]: https://usethis.r-lib.org/\n[{gh}]: https://gh.r-lib.org/\n[{varnish}]: https://github.com/carpentries/varnish#readme\n[{pegboard}]: https://carpentries.github.io/pegboard\n[{tinkr}]: https://docs.ropensci.org/tinkr/\n[{gert}]: https://github.com/r-lib/gert#readme\n[{testthat}]: https://github.com/r-lib/testthat#readme\n[{pkgdown}]: https://github.com/r-lib/pkgdown#readme\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarpentries%2Fsandpaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarpentries%2Fsandpaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarpentries%2Fsandpaper/lists"}