A comment on the index page for sections included "by magic"

[anenadic]

Data sets, Software setup sections are included in the index page by sandpaper - they are not part of index.md source file. It would be good to add a comment in index.md to say that these sections will be included included in the irendered ndex page by the Workbench.

[sstevens2]

Think that is a good idea so that lesson developers can easily track down where that addition is happening if they aren't super familiar with the workbench.

[zkamvar]

Thank you for pointing this out @anenadic!

This kind of "magic" is something I have always intended to document, but somehow it always slipped through my fingers. In brief, here is the magic pages, by type:

Combined pages

index.md and learners/setup.md

These form /index.html aka the home page where the sidebar shows the sections of the setup document.

source	section	anchor
index.md	index	#
learners/setup.md	setup	#setup

The instructor view is similar, except it includes a schedule before the setup:

source	section	anchor
index.md	index	#
episodes/*	schedule	#schedule
learners/setup.md	setup	#setup

profiles/*

All the profiles pages are concatenated into a single page called /profiles.html.

instructors/instructor-notes.md and episodes/*

The instructor notes (global and inline) are in a page called /instructor/instructor-notes.html The instructor notes are a special kind of combination that adds the in-line instructor notes to the end of the instructor-notes.md file. The in-line instructor notes start at the section with the anchor #aggregate-instructor-notes with subsections that have the anchor of the episode filenames.

Generated Pages

These are pages generated from the contents of the episodes extracted from the rendered pages

All in one page

This is at /aio.html and is a concatenation of the schedule. Each episode will be in a section with the ID aio-<file-slug>. An episode file named introduction.md will have the address /aio.html#aio-introduction in the aio page. Note: the aio prefix is to prevent a clash with the ID.

Keypoints

This is at /key-points.html. The key points of each episode is extracted and placed into sections with the ID of <file-slug>. An episode file name introduction.md will have the address /key-points.html#introduction.

Images

This is at /instructor/images.html and contains a concatenation of all the images in the lesson, printing the alt-text for each image if it exists.