Markdown

NOTE: use the arrow/cursor keys or icons (bottom right) to navigate

Teaching Innovation Project

Aim: "A standard template and guide for a system to generate module handbooks in .epub and .mobi formats (iPhone/iPad, Android, Kindle), and PDF, from a single plain-text document using free services and software, including LeanPub."
contact: deveritt@dmu.ac.uk

Learning materials

From Markdown, you can generate…

  1. HTML
  2. Word
  3. PDF
  4. e-books
  5. web-based presentations (Powerpoint not accessible/web-friendly)

…from single or few text-based source document(s), then you can fiddle with the formatting.

Fighting lock-in

(suitable clickbait graphic here)

Office suite developers hate this Melton Mowbray lecturer!

One secret trick Microsoft and Apple don't want you to know!

QUERTY

  • The QUERTY keyboard prevented typists locking up from going too fast, but has itself become locked-in
  • The most popular isn't always the best. Office suites are from the 80s. The web and semantically-structured text is the ideal delivery platform.

No lock-in!

  • Free yourself from applications and their compatibilities!
  • Your text doesn't depend on any proprietary software!
  • Generate proprietary formats if you need/must!

Plain text formats

  • Lightweight, small file sizes e.g. .md or .txt vs .ppt
  • No software version incompatibility (e.g. old Word can't open new Word)
  • Future-proof
  • Machine-readable, therefore more accessible
  • Portable and platform/device independent

What is Markdown

easy to read/write/edit

The aim is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format…

easy to sharing between devices/people

Unlike cumbersome word processing applications, text written in Markdown can be easily shared between computers, mobile phones, and people. It’s quickly becoming the writing standard for academics, scientists, writers…

–Daring Fireball (John Gruber)

gentle learning curve

Formatting text in Markdown has a very gentle learning curve. It doesn’t do anything fancy like change the font size, color, or type. All you have control over is the display of the text… making things bold, creating headers, and organizing lists."

–MarkDown tutorial

Extended Markdown

MultiMarkdown is maintained by Fletcher Penney and extends the original Markdown syntax with extra features, including epub generation (although this can also be done with other conversion tools).

markdownguide.org - Extended Syntax gives a brief summary of some now-common extended Markdown, including tables.

Markdown flavours

There are a few Markdown flavours although many are similar and some are trivial. There are also attempts to standardise Markdown variations.

However, most Markdown parsers and/or Multimarkdown are likely to have everything most people commonly need.

Other lightweight markup languages

…although Markdown has become the most widely-supported and well-documented with converters in every widely-used programming language.

The web and Markdown

  • with static site generators, you can use Markdown to build an entire wesite or maintain a blog
  • there are static site generators in almost every programming language e.g. (hover for language) Nanoc and Jekyll, Hakyll, Sculpin, Hugo…

See staticSiteGenerators.net

Two tiers of use:

Use Markdown quickly without a little learning, or deeply by learning more

  • essential:
    prepare handbooks and documents, learning materials, HTML, quickly structure content
  • advanced:
    version control with GIT, continuous deployment with a permanent URL on GitHub pages, CSS styling for HTML output, e-books…

Why bother?

Why use Markdown?

How to Write Faster, Better & Longer: The Ultimate Guide to Markdown —John O'Nolan

Hardcore questions:

Q. Why not just use LaTeX?

  • A. Markdown can be a quick start for generating a LaTeX document to expand later
  • A. Markdown is sufficient for many general documents
  • A. Markdown has minimal setup overheads
  • A. simpler markup is more future-proof

Softcore question:

Q. Why not stick to Office suites?

  • A. They're not naturally web-friendly
  • A. They don't encourage semantically-structured content
  • A. Office suites don't easily transport between formats
  • A. WYSIWYG formatting can be lost (e.g. fonts)

Advantages

  • Highly portable
  • Future-proof
  • Semantic structure is accessible and machine-readable (screen readers)
  • creates semantic and accessible outputs
  • Multiple Markdown editing options: from plain text to dedicated visual editors
  • Editable on any device and platform
  • minimal and writing-focussed

Disadvantages

  • Not an immediately visual environment
  • Resistance to change from familiar software
  • prior investment in existing skills
  • The ubiquitous dominance of Microsoft as a primary source
  • Attachment to personal formatting (colours, fonts...)
  • some conversions and advanced features require installs

Markdown issues

  • limited set of tags with no HTML5 semantic tags
  • some parsers do/don't allow inline HTML/attributes
  • no direct way of adding maths

but:

e.g. $ delimiters with Pandoc: ${e}^{i\pi }+1=0$
gives: eiπ + 1 = 0

Writing Markdown

most programming text editors

dedicated Markdown editors…

Many more free or inexpensive:

Markdown resources

Selection in progress, but for now:

Acknowledgements

Presentation made with Reveal.js, using RJSMake to generate the presentation directly from a single Markdown file.

See the raw Markdown or the HTML generated from this Markdown. The source code is available for download/cloning, and you can report any issues.