Tips, suggestions, standards, naming conventions, structure for new lessons
See https://cambiotraining.github.io/quarto-course-template/materials/01-render_guidelines.html for an idea of how to organize it
The coreR course structure is a website with a left sidebar to navigate among lessons and a right sidebar to show the contents of the current lesson.
1 _quarto.yml
In the course repository, the _quarto.yml contains all the information on how to render the website.
2 Lessons
The lesson .qmd files are copied out of the lessons package ({lhLessons} by default) and into the course repository. To maintain some order, a prefix is appended to the lesson names, e.g., s01_r_programming_introduction.qmd.
For consistency, lesson files must be Quarto documents with a .qmd extension and a yaml header containing a title (lessons in the package may also carry categories tags, which search_lessons() can filter on). Older lessons in .Rmd format should be updated.
3 Lesson supporting files
Some lessons link to external images, data, or embedded slides. These files are stored in directories named lessons/images, lessons/data, lessons/slides, and lessons/resources respectively. For a given lesson, correspondingly named subdirectories will appear in each of these directories, like this (for a lesson s01_r_programming_introduction.qmd):
<project root>
├── lessons ### all lesson .qmd files and supporting content
│ ├── s01_r_programming_introduction.qmd ### lesson
│ ├── s02_github_introduction.qmd ### etc
│ ├── data
│ │ └── r_programming_introduction
│ │ └── dataset1.csv
│ ├── images
│ │ ├── r_programming_introduction
│ │ │ ├── image1.png
│ │ │ └── image2.png
│ │ └── github_introduction
│ │ ├── image1.png
│ │ └── image2.png
│ ├── slides
│ │ ├── r_programming_introduction
│ │ │ ├── slides.qmd
│ │ │ └── lesson_style.scss
│ │ └── github_introduction
│ │ ├── github_slides.qmd
│ │ └── style.css
│ └── resources
│ └── r_programming_introduction
│ ├── references.bib
│ └── document.pdf
└── …
3.1 What goes into each folder
Each supporting folder is organized by lesson name (matching the lesson filename without the sXX_ prefix and .qmd extension). For example, lessons/images/github_introduction/ contains all images for the s02_github_introduction.qmd lesson. There are no strict rules about what goes into each of these folders, but generally:
lessons/images/: Image files (.png,.jpg,.gif, etc.)lessons/slides/: Quarto slide decks, plus any supporting files like.scssstylesheets or sub-directories for slide-specific imageslessons/data/: Data files (.csv,.gpkg, etc.) required for rendering the lesson. When possible, link to data from its original source (e.g., an R data package, a URL) rather than storing it locally. Store only when data is not readily available, or provide a downloadable copy for learners.lessons/resources/: Miscellaneous resources like.bibfiles, PDFs, handouts, instructor documentation, etc.
If a lesson does not have supporting files, e.g., no images, then there may not be a corresponding folder (e.g., the github_introduction.qmd lesson above does not have a data folder!)
3.2 File naming and sizing for supporting content
Within each lessons/images/, lessons/data/, lessons/slides/, and lessons/resources/ subdirectory, there are no specific naming conventions—just use short, descriptive filenames that make sense for the content. Pay attention to:
- File size — especially for images, which should be as small as reasonable. Screen captures are often captured at full resolution but remain readable when shrunk to a coarser resolution; use a photo app to optimize them.
- Naming — keep it concise and meaningful, so it’s clear what the file contains at a glance.
lhLessons package
The file structure inside the lhLessons package mirrors the course structure, except nested within inst/lessons instead of at the Quarto course site root:
- the lesson
.qmds and supporting files/folders all live in theinst/lessonsfolder inside the package repository - supporting files are organized in
lessons/data,lessons/images,lessons/slides,lessons/resourcesdirectories - all content inside the supporting folders is copied over to the new course without modification.
4 Extensions and formatting
The look of the course site (banner, fonts, colors, callout styling) is kept separate from the lesson content, in a Quarto extension.
init_course()installs the extension for the chosen template by runningquarto add nceas-learning-hub/theme_<template>(e.g.,theme_delta), along withquarto-ext/fontawesomefor icons. This requires the Quarto command line tool and an internet connection. The extensions are installed into the course’s_extensionsfolder, not the project root.- The template extension (
_extensions/nceas-learning-hub/theme/) contains:_extension.yml, which sets the default HTML options for the site (light and dark themes, table of contents, numbered sections, code copy on hover, and the title banner) and registers the Lua filter.theme_light.scssandtheme_dark.scss, which control fonts, colors, and callout styling.banner/, with the banner CSS and logo images used in the title banner at the top of each page.callout_exercise.lua, a filter that implements the custom exercise/hint/answer/example callouts (see the content guidelines).
- The
_quarto.ymlin the course root refers to the extension (underfilters:andformat: theme-html:) and holds course-specific settings such as the site title, navbar, and sidebar contents.
To change the styling of a single course, edit the files inside its _extensions folder (or add course-specific CSS/SCSS and reference it from _quarto.yml). Avoid editing the lesson .qmd files for styling purposes, so that lessons can still be updated from the lessons package and checked back in without carrying course-specific formatting. Note that edits to the _extensions copy affect only that course; to change the styling for all future courses, the template extension in its own GitHub repository must be updated.