explore automation for CodiMD template generation

[tobyhodges]

We should explore options for automated creation of the template CodiMD notes document for these trainings.

[tobyhodges]

My current theory for how we could achieve this involves extracting the title of each episode plus the contents of the following fenced divs:

• questions
• objectives
• keypoints
• challenge
• discussion

Any other content we want included in the notes template could be placed between HTML comment tags, e.g. something like:

• <!-- /INCLUDE IN NOTES TEMPLATE/ --> and <!-- /END/ --> to wrap page content that should also appear in the notes template, and
• <!-- /INCLUDE IN NOTES TEMPLATE/ and /END/ --> to wrap content for the notes that should not appear on the lesson page, e.g. a bullet point list summarising important points from a particular section.

We would then need:

1. some boilerplate for the start of the notes doc containing space for training event info (date, names of Trainers, etc), some important links (CoC, curriculum site, placeholder for training event webpage), and a [TOC] marker for the table of contents.
2. a script to read the episode order from config.yaml and pull out the content from episode source files, writing this to a Markdown file
3. an Actions workflow to run this script and return the resulting file as an artifact that Trainers can download and paste the contents into a new CodiMD for their training event.

Pinging @zkamvar to see if he a) knows of any existing tools that could be used for this instead of us writing our own, and b) can comment on how best we could configure such an Actions workflow for incorporation into the lesson infrastructure. This is certainly not something that every lesson will want, but I imagine it would be a helpful feature for more than only ours. Could we set it up to run if a certain file is present in some specific location in the repo? (E.g. the boilerplate .md in the instructors directory?)

[zkamvar]

Hey Toby, for the contents of the etherpad, you might consider what instructor training used to have because I'm pretty sure the needs overlap: https://github.com/carpentries/instructor-training/blob/legacy/gh-pages/_extras/etherpad.md?plain=1

WRT to the method to add content to the notes: the comments will work, but they are cumbersome af to write. It may be better to add an explicit codimd class of divs (which can be added to other divs e.g.

::: {.callout .codimd}

This callout will be included in the codimd as a note

:::

This will not appear in the codimd.

::: codimd

This will be included in the codimd as text

:::

Regarding extracting content, I absolutley do not want anyone to have to write their own GHA workflow to extract content. That is hell. Absolute hell. I already have a mechanism in carpentries/pegboard#101 which will enable the ability to create a code handout (but I know that's not what you are looking for) includes challenges without solutions, but the important thing that I want to stress (especially for the @carpentries/workbench-maintainers, who will be thinking about the design) is that this is a feature that more than one lesson will want. We already have precedent for these opt-in patterns.

For example, for the issue linked above, I am planning on making it triggerable by a handout: true config YAML item and I think the codimd: true YAML item is even easier to implement (since it does not involve commenting out non-code elements).

[tobyhodges]

Thanks @zkamvar. Our need does overlap heavily with Instructor Training and indeed their Etherpad template was mentioned during the discussion that led to the opening of this issue. The thing I am unclear on is how easy it would be to adapt the Instructor Training approach to prepare Markdown content for a CodiMD template. I will investigate further.

The only drawback I can see to introducing another fenced div class for content exclusive to the CodiMD template (which also applies to my suggested approach with HTML comments) is that it will make the episode source files more confusing for contributors by introducing content that does not appear anywhere in the built site.

Perhaps, given that extraction of page content divs, such as objectives, questions, and exercises, will give us 90+% of what we need, we should aim for that and accept that a bit of manual tweaking would be necessary to polish up the template to be exactly what we want for any given training?

[zkamvar]

is that it will make the episode source files more confusing for contributors by introducing content that does not appear anywhere in the built site.

Oh, I was thinking that this would be a way of explicitly flagging content that should be included to be included in the main site.

Perhaps, given that extraction of page content divs, such as objectives, questions, and exercises, will give us 90+% of what we need, we should aim for that and accept that a bit of manual tweaking would be necessary to polish up the template to be exactly what we want for any given training?

💯

[zkamvar]

The thing I am unclear on is how easy it would be to adapt the Instructor Training approach to prepare Markdown content for a CodiMD template. I will investigate further.

Also to clarify: I wouldn't adopt the instructor training approach (embedding JavaScript that is pre-processed with liquid to generate the weird HTML of etherpad from the lesson contents). I just wanted to show you the kind of elements they were taking.

[tobyhodges]

Oh, I was thinking that this would be a way of explicitly flagging content that should be included to be included in the main site.

Some of it will be this, but we have also found it helpful to present templated summaries of content that appears in the lesson e.g. bullet lists of exercise formats that are described in more detail in the curriculum itself. This seems to be useful scaffolding to encourage notetaking.

[tobyhodges]

Added to the milestone for the 2024 release, but the goal for that timeframe is to figure out a path forward/plan for how we would implement this, and not to do the implementation.

[anenadic]

Just adding a link to some code that Toby did and I modified to extract exercises (it is not perfect and there was a small issue with nested blocks) but it is a good starting point perhaps: https://github.com/anenadic/extract-exercises