• Preface
• Creating a Lesson With This Style
  • Initializing a lesson
  • Configuring the Lesson
  • Updating the style
  • Make sure to resolve conflicts!
• Using Syntax Extensions in this Style
  • MathJax
    • Inline equation within the text
    • Math blocks
      • Centered Block Equation
      • Left Justified Block Equation
  • Mermaid Examples
    • Flowchart
    • Git Graph
  • Instructor View
• Advanced formatting
  • Centered Paragraph
  • Set Image Width
  • Image in flow text.

Preface

This style is based on based on The Carpentries style and has some modifications for use by the Digital Research Alliance of Canada (the Alliance) and ACENET. Creating and editing lessons from such styles is explained in the Carpentries Lesson Example.

Creating a Lesson With This Style

Here is a quick rundown on how to create a lesson based on this style.

Initializing a lesson

$ git clone https://github.com/acenet-arc/cc-carpentries-styles.git  my_lesson
$ cd my_lesson
$ python3 bin/lesson_initialize.py
$ git remote rename origin template
$ git remote add origin  <GITHUB_URL_FOR_YOUR_LESSON>
$ git commit --all  -m "initialize lesson"
$ git push -u  origin  gh-pages

Configuring the Lesson

Edit the file _config.yml to set these values:

• carpentry: This changes the branding of the lesson, e.g. carpentry: "alliance" for the Alliance.
• title: Sets the lesson title.
• life_cycle: This indicates how far along the development of the lesson has come.
• email: The email address of the primary contact (probably an email list).

Also don’t forget to edit these files:

• AUTHORS
• CITATION
• index.md
• README.md
• reference.md
• setup.md
• add your episodes (chapters) under _episodes/*

Updating the style

Make sure to resolve conflicts!

Merging changes from the template can result in merge conflicts.

Proficiency in resolving conflicts is recommended, as is having Jekyll set up to test the page locally. But as we are working with git repositories, we can always go back to an earlier version of the history.

# check if you have a remote "template" and whether it points to https://github.com/acenet-arc/cc-carpentries-styles.git :
$ git remote -v
origin	git@github.com:ComputeCanada/my_lesson.git (fetch)
origin	git@github.com:ComputeCanada/my_lesson.git (push)
template	https://github.com/acenet-arc/cc-carpentries-styles.git (fetch)
template	https://github.com/acenet-arc/cc-carpentries-styles.git (push)

# if you don't already have the remote "template", add it:
$ git remote  add  template  https://github.com/acenet-arc/cc-carpentries-styles.git

# now "fetch" the latest commits from "template":
$ git fetch template

# merge the changes:
$ git merge template/gh-pages

# Now resolve the conflicts and test if the page still works.

Using Syntax Extensions in this Style

MathJax

MathJax is a JavaScript library that can render LaTeX math equations on a website. This template has MathJax support enabled and can be used as shown below.

Inline equation within the text

Sometimes we want to use a math expression within the text. We can enclose the LaTeX math expression within double-$ characters like $$ math-expression $$.

This code:

Lorem ipsum dolor sit amet, consectetur  $$ k_{B}T/2 $$ adipisicing elit, sed 
do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

… will be rendered like this:

Lorem ipsum dolor sit amet, consectetur \(k_{B}T/2\) adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Math blocks

But we can also have our equations as blocks in between paragraphs.

Centered Block Equation

This code:

$k_{n+1} = n^2 + k_n^2 - k_{n-1}$
{: .math-center}

… will align the equation to the center of the page:

$k_{n+1} = n^2 + k_n^2 - k_{n-1}$

Left Justified Block Equation

This code:

$k_{n+1} = n^2 + k_n^2 - k_{n-1}$
{: .math-left}

… will align the equation to the left of the page:

$k_{n+1} = n^2 + k_n^2 - k_{n-1}$

Mermaid Examples

Mermaid is a JavaScript library that can be used to write various graphs and flow-charts within Markdown and render them on a website. This template has Mermaid support enabled and can be used as shown below.

Flowchart

Documentation for Mermaid Flowchart

<div class="mermaid">
graph LR
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
</div>

Git Graph

Documentation for Mermaid gitGraph

<div class="mermaid">
gitGraph
   commit id: "C1"
   commit id: "C2"
   branch develop
   checkout develop
   commit id: "C3"
   commit id: "C4"
   checkout main
   merge develop
   commit id: "C5"
   commit id: "C6"
</div>

Instructor View

Some lessons are rather complex and require a lot of information, which can result in long blocks of text that are needed for self-study as well as new instructors that need to familiarize themselves with the material.
In a workshop or presentation setting however it’s difficult to pick out the talking points and having key information in bullet-points would be much better.

A solution to this is to introduce an “Instructor View” that will hide paragraphs that have been marked as {: .self_study_text :} and instead show paragraphs marked as {: .instructor_notes :}, which are otherwise hidden.

If any of those markers a present on a particular page (and only on those), the following toggle switch will appear in the Navigation bar at the top to turn the instructor view on or off:

The state of the toggle is persistent for some time (by default 7 days) by setting a cookie, however this duration can be customized by a variable in _config.yml:

instructor_view_cookie_lifetime: 3

Example:

This is a long text that describes a complex topic in detail. 
This contains information that the instructor explains in detail.   
_Lorem ipsum dolor sit amet,[...] sunt in culpa qui officia deserunt mollit anim id est laborum._
{: .self_study_text :}

* talking points for instructor
* easier to read during the workshop
{: .instructor_notes :}

This is a long text that describes a complex topic in detail. This contains information that the instructor explains verbally in detail.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

• talking points for instructor
• easier to read during the workshop

Advanced formatting

This section contains tips on enhanced formatting techniques that should also work with the unmodified Carpentries Style.

Centered Paragraph

_Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut_
_labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris_
_nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate_
_velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non_
_proident, sunt in culpa qui officia deserunt mollit anim id est laborum._
{: .text-center :}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Set Image Width

The width of an image can be specified by appending {: width="100" } to the image link. e.g.:

![Alliance logo](../assets/img/alliance-icon-color.svg){: width="100" }

As ![alt text](../fig/img.svg){: width="100" } translates to: <img src="../fig/img.svg" alt="alt text" width="100" />, the width can also be specified in percent.

Image in flow text.

Sometimes a small-ish image is associated with a paragraph of text. By adding {: align="right" } after the image-link it is aligned on the right and the text flows around. To reset the flow, a break can be added <br clear="all" />, e.g. to make sure that the image doesn’t flow into a paragraph that it is not related to.

![Alliance logo](../assets/img/alliance-icon-color.svg){: width="100" align="right" .image-with-shadow }

_Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut_
_labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris_
_nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate_
_velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non_
_proident, sunt in culpa qui officia deserunt mollit anim id est laborum._

<br clear="all" />

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.