Writing a New Lesson

To write a new lesson, follow the steps summarized below and demonstrated in this tutorial:

  1. Navigate (in R Studio or in your file system) to the folder lessons and then into the folder for the category to which this lesson belongs. See [createCats] on how to create new categories.

  2. Create a new folder using a unique name. We suggest that you use the following naming template for lesson folders: l-CCC-NNN-subject where CC is the category to which the lesson belongs, NNN is the lesson’s unique number (unique to the category), and subject is a summary of the lesson’s topic. So, for example if you want to write a new lesson on editing videos on Vimeo belonging to category “910 / Video Editing” and using the unused lesson number 202, then you should name the folder l-910-202-edit-video-vimeo. Note that the folder name can actually be anything but it is useful to follow this naming convention. To find all categories, view all lessons from the Artificium website, e.g., http://artificium.us.

  3. Copy the contents of an existing lesson whose format you like or copy the files in the _lesson_template folder.

  4. Rename the lesson’s .Rmd file to a name that matches the lesson’s number and category, e.g., l-910-202.Rmd. The lesson files can actually be any name but following convention helps.

  5. Remove any data, code, or other files you do not want.

  6. Edit the lesson’s Rmd file following the steps below.

Editing a Lesson’s Markdown

Lessons are written in R Markdown, an extension to Markdown. You can download the code (.Rmd file) for any lesson on Artificium and inspect the Rmd to learn how to build certain sections.

You need to minimally update the following:

  • Update the metadata between —— at the beginning of the lesson’s Rmd file. When the Rmd is knitted, the information from the metatags is inserted into the Artificium database, so be careful when editing.

  • Change the title to the title of your lesson. This will be displayed as the lesson’s title on the generated HTML page.

  • Change the category and number to reflect the lesson’s number and the category to which it belongs. This information is critical as this is the information that is inserted into the repository database and used to generate the website. While the folder and lesson file do not have to match the lesson’s number and category, the category and number metatags must match. These are the actual definition of the lesson’s number and category. You cannot easily change a lesson’s category and number. If you update them here, the old lesson will need to be removed manually from the database, so be mindful or lesson and category numbering.

  • Add the estimated time to complete the lesson (in minutes) in time.

  • Update the level for the lesson in the level tag.

  • Update the tags under tags. These are used for searching so be generous and careful. Separate them with commas but do not add a space after the comma.

  • Add a lesson description. This is displayed during lesson search and preview as well as in courses. You may add HTML to the description but it is not recommended.

  • Update the author, affiliation, and email information. You can add HTML tags to modify the display, but it is not recommended.

  • Do not update the output: section unless you know R Markdown and wish to change the theme.

  • Do not update the second title definition. It is only used for autogeneration.

  • Ignore the R code chunks. Do not modify them in any way. They are automatically executed and will generated HTML and insert the lesson into the repository during knitting.

Now you are ready to build the content of the lesson. Start by defining headers using ‘##’ and ‘###’. Do not use level 1 ‘#’ headers as the lesson title is a level 1 header.

The lesson headers are automatically added to the floating table of contents.

Continue with the section on ?????.

Editing an Existing Lessons

Compiling a Lesson

Lessons are “compiled” to HTML through knitting which runs the rmarkdown::render() function to generate HTML from the markdown.

You can knit (or “compile”) a lesson in two ways:

  1. By clicking ‘Knit’ or ‘Preview/Knit to HTML’ in R Studio.

  2. By running the script ‘knitAll-Lessons.R’ located in _utils. Open the script and click ‘Source’ in R Studio.

Removing a Lesson

Generally, lessons should not be removed as they could be linked to from courses, stacks, or externally. For example, someone may have copied the URL to the lessons and incorporated it in their course. Unless you can be certain that a lesson is not referenced anywhere, do not delete a lesson.

You might consider marking the lessons as obsolete, deprecated, or with some other flag by updating the title or content of the lesson’s Rmd.