Instructor Notes
Episode: Introduction
HedgeDoc/CodiMD Collaborative Notes Document
We recommend the usage of HedgeDoc (formerly called CodiMD) and for instance The Carpentries CodiMD instance for creating your new documents. All instructors can use it for note-taking when preparing or teaching this lesson and we also encourage its usage during the workshop for asking questions and collaborating during exercises, especially when using breakout rooms. The main advantage is that it uses Markdown so it can easily convince learners on the importance of learning Markdown. Make use of HackMD Mechanics from CodeRefinery. Take time to orient your learners to using the document early on to be ensure everyone understands how to use HedgeDoc.
Hello World in HTML
When demonstrating “Hello World in HTML” you may choose to write the
example HTML in a text editor before viewing the saved file in a
browser. Or you may prefer to write the HTML directly into the workshop
HedgeDoc/CodiMD shared notes document, which will provide immediate
visual feedback on the rendered equivalent. The advantage to using the
workshop CodiMD is that it reduces the need to switch between so many
windows and introduce the text editor. The advantage of opening a plain
.html file in the browser is that it clearly demonstrates
the utility of the title element.
Shared Website Example Repository
When multiple instructors are teaching this lesson, the person who demonstrates creating the website repository (at the end of the Introduction episode) should remember to add the other instructors as collaborators on that repository. This will save you trying to maintain consistency between multiple demo repositories while also handling questions, helping people who are stuck, etc.
Episode: Authoring With Markdown
‘Add Your Repository Details to HedgeDoc’ Exercise
We recommend doing the “Optional Exercise: Add Your Repository Details to CodiMD” exercise when teaching online, as it is very useful for helpers to have links to all the learner repos and rendered websites for troubleshooting. Then when a learner messages in chat, the helper can find their repo and look at the commit history to find the error.
Episode: Hosting Websites on GitHub
Adding a theme through the GitHub Pages Settings tab
If you’re pushed for time and want to quickly introduce adding themes
to your website without lots of additional context around Jekyll there
is now a Theme Chooser section in the GitHub Pages Settings
tab. This allows users to briefly browse supported Jekyll themes for
GitHub Pages and select one for their site. It will add a
_config.yml file to the repository containing a single line
that sets the theme i.e. theme: jekyll-theme-cayman. This
will be committed automatically to your default branch and rebuild your
site with the new theme. Please note that using the
Theme Chooser is incompatible with subsequent episodes in
this lesson and is only recommended if you don’t expect to progress onto
further episodes (in particular Page Layouts).
Episode: Starting With Jekyll
Episode: Reusing Blocks of Content
includes vs include
Learners sometimes get confused about when to use
includes vs include in the Reusing Blocks of Content episode. Good
to stress that the folder is _includes (e.g. it contains
several files that can be included hence the plural form) and when you
want to use something from that folder you include it.
Episode: Page Layouts
Layout Names Confusion
Learners sometimes get confused about conventional names of layouts
used in Jekyll - for example home layout vs. home page
(index.html), page layout vs. page used as a
term for ‘webpage’, default layout was not much better
either. While it is not a must, recommendation here is to stick with
this conventional terminology as it is reused across different Jekyll
websites that learners may come across in future and to spend some time
clarifying this.