Markdown for OER

Open standard for your open content

• Markdown is an open standard.
• Many extensions.
• Decentralized Darwinian approach.
• Supported by many open source tools and apps.

Your OER content, you publish

• Render as HTML or PDF (or docx, rtf, etc.)
• File-based: send as email attachment to students (ew!).
• LMS-based: upload as files to Canvas.
• Google Drive: upload and convert to Google Doc.
• Self-hosting.
• Tool-supported cloud hosting.
• Etc.

Short, medium, or long OER content

• Easy (low-overhead) enough for short announcements.
• Flexible enough for semester-long books.
  • May benefit from file inclusion, see the pandoc section.
• And everything in between!

What is Markdown?

Web-centric

• Translates to HTML.
• Can mix HTML in Markdown.
• Better than HTML (we will get to that).

A kinder HTML

<ul>
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
</ul>

becomes

* item 1
* item 2
* item 3

Compatible with HTML

• Can use all the Cascading Style Sheet specifications
  • Physical page layout control
    • Keep sections on the same page
    • Multiple columns
• Artistic people can express themselves!

Keyboard friendly

• No shortcut keys to remember
• No using the mouse to click something

# level 1 header

## level 2 header

Easy to integrate links

How to do a [Google](https://www.google.com) search.

How to do a Google search.

Mouseless equation

$\sum_{i=0}^{n}i = \frac{n(n-1)}{2}$

\(\sum_{i=0}^{n}i = \frac{n(n-1)}{2}\)

Industry standard

• GitHub
• Discord
• Google is starting to support Markdown in comments

Extensions

• Mermaid for making graphs
• pandoc has many extensions and “filters”

Who

should consider using Markdown?

Fast typers

• Using the right editor, there is no need to use a mouse
• No shortcut keys to remember
• Can use any simple plain text editor

Math people

• Uses \(\LaTeX\) for equations.
• Inline equation \(y=2x\) is easy.

Computer science people

• Syntax highlighted program listing is easy:

#include <stdio.h>
int main()
{
  printf("Hello world!\n")
}

Chemistry people

• Reactions like \(\ce{H2SO4 -> 2 H+ + SO4^2-}\)
• Bonds like \(\ce{ C6H5-CHO }\)
• Check out https://mhchem.github.io/Mathjax-mhchem

All people

• Images

![Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/320px-Markdown-mark.svg.png)

• Cross referencing

[Link to start page](#what_is_markdown)

Link to start page

• Tables

|Prompt|Answer|
|----|----|
|knock knock|who's there|
|Marco|Polo|
|Tak|Ikel|

• Graphs

```mermaid
flowchart LR
  id1(Do something)
  id1-->|again|id1
``` 

GitHub

As a platform.

Easy!

• Sign up for an account at https://gibhub.com.
• Use the web interface to create repositories.
• In a repository create files with an extension of md
• Free revision control

Advantages

• Free.
• All-in-one
  • Editing/creating.
  • Rendering.
  • Hosting.
• Just a URL to the content!
  • Easy to link from Canvas.

More advantages

• Issue ticket system
• Discussions
• Open to collaboration
• Very easy to “fork” in different directions

Limitations

• No numbered sections.
• No table of contents.
• The online editor is very plain, no spell checking.
  • Easily remedied by using git and a nice editor on a personal computer.
  • Some nice editors have built-in git capabilities.

Good for

• Shorter content where numbered sections are not needed.
• Projects that involve many contributors in terms of content and ideas.
• Ultra high-mobility missions
  • Frequent updates
  • High collaborative interactions
  • Fast turn-around response to suggestions/feedback
• Web-centric delivery

pandoc

as a rendering tool

What is pandoc?

• pandoc is
  • A command line program.
  • The “universal translator” of documents (hence its name!).
  • It is here to stay:
    • Open sourced
    • Widely used
  • Extensible via “filters”

Export possibilities

• The boring but universal formats: rtf, doc, PDF, etc.
• The web-friendly: HTML
• The e-book friendly: EPUB
• The presentation friendly: reveal.js, PowerPoint, etc.
  • Yes, this presentation is written in Markdown!

Cool extensions

• Table of contents
• Numbered sections
• Inclusion of other files
• Many, many more!

Author’s computer

• pandoc
• Markdown files
• Rendered publication files

Publication options

• Paper (printed from PDF).
• Web-accessible general purpose server.
  • This is how this presentation file is published.
  • Create links from LMS platforms like Canvas.
• File hosted by LMS platforms.

Advantages

• More features and flexibility.
• Many publication options.
• Can customize using personal CSS specifications.

Limitations

• Need more knowledge to operate the tool.
• File-based approach, does not include publication, revision control, team management, etc.

Good for

• Solo authors who are proficient with using command line tools.
• Long content that can benefit from numbered sections and a table of content.
• Even longer content that should be published in EPUB as a book.

Joplin

as a learning tool, editor, organizer, and publication platform

Where to get it

• JoplinApp.org
• Cross-platform: Windows, macOS, Linux, Android, iOS.

Content-creator friendly

• Real-time rendering on the side, great learning tool.
• WYSIWYG “cheat mode”.
• Intuitive user interface.
• Installed on end-user device, but content can be cloud hosted.
• Has vi key binding for the mad computer scientists (yours truly).

Built-in organizer

• Notebooks are like folders.
• Notes are like files.
• Tags to aid non-hierarchical organization.
• Table-of-contents in the same document is supported.

Subscription-based Joplin Cloud

• Maintain content from any device.
• Publish content via cloud mechanism.
  • Readers do not need Joplin installed.

Advantages

• Superior user interface and user experience.
• Eases the learning curve of Markdown.
  • The HTML cheat mode helps!
• Organization.

More advantages

• Paid cloud content hosting.
• Publication capability.

Limitations

• Cloud features are subscription-based.
  • Can still publish as HTML files for other publication methods.
• Does not support numbered sections.

Good for

• First-time content creators learning Markdown.
• People who work on content from multiple devices.
• In-class discussions (the real-time rendering is great).
• Note-taking.

Modules vs Books

Book approach

• More traditional.
• More linear.
• Easier to print.
• More self-contained.

Book approach

• More daunting.
• Requires more developer discipline.
• Does not work well with ADHD.
• Longer lead time to usable content.

Modular approach

• Allows non-linear linking.
• “Wiki-like”.
• Aligns with the “Agile methodology”.
• Quicker to develop something that is usable.

Modular approach

• OER development does not seem as daunting.
• Flexibility of granularity.

Markdown modular OER

• Markdown is well suited for rapid content development.
• Significantly less typing compared to \(\LaTeX\) and HTML.
• Does not require WYSIWYG editors that may or may not be universal.

How do I get started?

Joplin for learning

• Great learning tool.
• Publication method is limited.
• Free of charge.

GitHub for publishing

• Convenient web interface.
• Can utilize most sophisticated tools for updates.
• Issue tracking and project forking.
• Discussion forums.

pandoc

• Great flexibility and many extensions.
• Require a bit of familiarity with command line tools.
• Good for larger projects:
  • The include features helps break into smaller files.
  • Section numbering.
  • Export to Epub, PDF and other book-like formats.

Comparison to LibreTexts

Compatibility

• Markdown converts to HTML
  • Joplin has an export feature.
  • GitHub renders automatically, copy-and-paste the HTML content.
  • pandoc can convert to HTML

Authoring

• LibreTexts has a WYSIWYG HTML editor.
• LibreTexts has a steeper organizational learning curve.
• LibreTexts has more interactive element integration for activities.