A Rapid Workflow for Publishing CS Teaching Materials

Russell Gordon
Lakefield College School

---

Motivation

Avoid fiddling with GUI-based page layout, slides, and diagramming software.

---

Motivation

Satisfy 80/20 rule.

---

Motivation

Meet the needs of English language learners.

---

Benefits

Syntax-highlighted code blocks for most languages.

# Greet the world using a function in Python
def hello_world():
  return "Hello, world!"

---

Benefits

Math notation using LaTeX: single-line.

$x=\frac{-b\pm \sqrt{b^2-4ac}}{2a}$

---

Benefits

Math notation using LaTeX: multi-line.

$\begin{array}{rl}a& =-0.25\\ b& =2\\ c& =1.5\end{array}$

---

Benefits

Inline math notation using LaTeX:

Videos take at least $3x$ units of time to author where $x$ is the length of the video in question.

---

Benefits

Mermaid: left-right flowchart.

flowchart LR

id1["App Entry Point\n(NavigationView)"] --> id2["List\n(NavigationLink)"]
id2 --> id3[Blue Jays]
id2 --> id4[Cheesecake]
id2 --> id5[Claire]
id2 --> id6[Jen]
id2 --> id7[Lasagna]
id2 --> id8[Piper]

---

Benefits

Mermaid: top-down flowchart.

flowchart TD

id1["App Entry Point\n(NavigationView)"] --> id2["List\n(NavigationLink)"]
id2 --> id3[Blue Jays]
id2 --> id4[Cheesecake]
id2 --> id5[Claire]
id2 --> id6[Jen]
id2 --> id7[Lasagna]
id2 --> id8[Piper]

---

Benefits

Mermaid: sequence diagram.

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

---

Benefits

Mermaid: class diagram.

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

---

Benefits

Mermaid: state diagram.

stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

---

Benefits

Mermaid: entity-relationship diagram.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

---

Benefits

Mermaid: user journey diagrams.

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

---

Benefits

Mermaid: Gantt charts.

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d

---

Benefits

Mermaid: pie charts.

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 30

---

Benefits

Mermaid: git graph diagrams.

gitGraph
   commit
   commit
   branch develop
   checkout develop
   commit
   commit
   checkout main
   merge develop
   commit
   commit

---

Benefits

Add images quickly by drag and drop.

---

Benefits

Use animations to convey key concepts without distraction.

---

Benefits

Focus on content, not presentation, by writing in Markdown.

---

Benefits

Your data is stored in plain text files – less potential for lock-in.

---

Benefits

Link quickly to existing content.

---

Benefits

Publish a searchable site.

---

Benefits

Free hosting (at Netlify or Vercel).

---

Drawbacks

Dependencies on:

• Obsidian
• Digital Garden plugin.
• GitHub
• Netlify or Vercel

---

Personal Conclusion

Benefits outweigh potential for software failure.

Better than manually writing HTML, using a word processor, or a proprietary content management system.