1 Initialize the course with init_course()
The init_course() function is the first step to creating a course. It creates a new R project for the course, saves some metadata about the course in a .csv (metadata_course.csv) for later reference, installs the Quarto website structure and theme template, and (by default) sets up Git/GitHub and automatic publishing. This function has eleven arguments. The course information can be supplied either as individual arguments or all at once in a single object, course_info (see Supplying course info as a table or list). When using individual arguments, only course_proj is mandatory:
course_projis the desired name for the course project repository, and will also drive the course’s eventual home on the interwebs. We recommend a format likeyyyy-mm-<course type>, such as2024-10-coreRor2024-06-delta. Characters other than letters, numbers,_and-are replaced with_(with a warning).course_orgis the GitHub organization (or GH user) where the course project will live. Defaults to"nceas-learning-hub".course_titleis a brief, descriptive title for the course. If left blank, defaults to the same ascourse_proj.course_descis a brief (~ 1 sentence) description of the course content. This is stored in the course metadata but currently not otherwise used. If left blank, defaults to the same ascourse_title.course_datesis a text field containing the dates of the course, in whatever format. If left blank, no dates will be recorded.setup_github(defaultTRUE) initializes the course as a Git-tracked project, makes an initial commit, creates a GitHub repository namedcourse_projin the organizationcourse_org, and sets up publishing (see Publish the course). Set toFALSEto skip these steps and handle Git/GitHub yourself.templateselects the stylistic template, which defines the default index page, banner colors, hex logo, etc.:"lh"(default) for Learning Hub;"adc"for Arctic Data Center;"delta"for Delta Stewardship Council;"corer"for coreR.packageis the lessons package that supplies the Quarto structure and index page files. Defaults to"lhLessons"; currently a placeholder for potential future custom lesson packages.locis the desired location where the new course will be created. Defaults to the current working directory. The location must not be inside an existing Git repository - this is checked before anything is created, and if it is,init_course()stops with an error. If you are currently working in an existing Git-tracked R project, some options:- Close the current project; this should leave you in the default location for projects you’ve set in RStudio. Then it should be fine to use
loc = '.'(default). - Keep the current project open, but set
loc = '..'to create the new course one level up, parallel to your current project. - Define some custom location and set
locto that directory.
- Close the current project; this should leave you in the default location for projects you’ve set in RStudio. Then it should be fine to use
quiet(defaultTRUE) controls whether progress and diagnostic messages are shown. Setquiet = FALSEto see details.course_info(optional) is an object holding all of the course information, to be used instead of the individual arguments above: either a one-row data frame whose column names match the argument names, or a named list whose names match the argument names. See below for details.
The function invisibly returns the full path to the new course project. With the default quiet = TRUE, the new project is activated automatically; with quiet = FALSE the instructor is instead prompted (y/n) whether to open the new project. Either way, the instructor is advised to close the current project and open or activate the new course project directly.
After this step, the course has structure but no lessons. We’ll fix that in the next step!
1.1 Supplying course info as a table or list
Instead of typing each argument, you can pass all of the course information in the course_info argument, e.g., a table you maintain as a .csv and read in with your preferred function. The rules:
course_infomust be a one-row data frame whose column names match the argument names, or a named list whose names match the argument names.course_projis required. Any other argument that is missing fromcourse_info, orNAincourse_info(e.g., a blank .csv cell), gets its default value.- Names in
course_infothat are not arguments ofinit_course()cause an error. - Supplying individual arguments alongside
course_infoalso causes an error - use one approach or the other. setup_githubandquietmay be given asTRUE/FALSEor as text such as"TRUE"(handy when reading from a .csv).
The course files will be pulled from the version of {lhLessons} package that the instructor currently has installed. We recommend reinstalling the package (remotes::install_github('nceas-learning-hub/lhLessons')) before running this function to make sure you have the latest version!
2 What init_course() installs
Course structure is set up internally by init_course() (the helper setup_course_structure() is not exported, so it is not called directly by the instructor). Here’s what gets installed:
metadata_course.csv, holding the course project name, organization, title, description, and dates.- A
_quarto.ymlfile that creates the structure of the course site, populated with course info from the metadata. It contains placeholders (# START SESSIONS,# SESSION_LINKS,# END SESSIONS) wheresetup_lessons()will later insert the lesson sequence. - An
index.qmdfile with boilerplate text based on the selected template. This can (and should) be edited to provide specific info on the new course. - An
_extensionsfolder with CSS information and image files to control the appearance of the site according to the selected template, such as the header bar at the top, font faces, sizes, colors… - Other miscellaneous course files from the lessons package (e.g., a
404.qmd). - If
setup_github = TRUE: a.gitignoreand a.githubfolder with a GitHub Actions workflow to auto-publish the site whenever a new commit is pushed to GitHub (see Publish the course).
2.1 Editing the index.qmd
Edit this file to your heart’s content. You can modify the title in the YAML header, but leave the rest of the header in place. The text of the page is specific to this course. Some boilerplate text is already in place, but you may wish to edit specific learning objectives, schedule, and details about the course book to reflect the needs of the course.
2.2 Linking to Git and GitHub
With the default setup_github = TRUE, init_course() handles the Git and GitHub setup. This requires that your Git user.name and user.email are already configured (the function stops with an error otherwise), and that you have write privileges to the GitHub organization.
If Git/GitHub are not (fully) set up - e.g., setup_github = FALSE - the function checks and prints reminders such as:
This project does not seem to be a Git repository. You might want to:
• Use `usethis::use_git()` to set up your project as a Git-tracked project, and then...
• Use `usethis::use_github(organisation = 'nceas-learning-hub')` to connect the project with Github!
Follow those directions, answering the prompts after each function call. Don’t overlook the organisation = 'nceas-learning-hub' argument (note the British spelling), otherwise it will be linked to your user account.