Introduction to Markdown digital workflows

What is plain text?

  • Data that consists of only readable characters

Example:

What is plain text?

  • Not plain text:
    • Formatted text
    • Binary files

Where might you have seen plain text?

  • Email
  • Internet forums / comment forms
  • Editing wikis like Wikipedia
  • Project Gutenberg
  • “View Source” on Web sites

Where might you have seen binary files?

  • Images
  • Videos
  • Microsoft Word
  • Powerpoint
  • PDFs

Why use plain text?

General reasons for using plain text

  • Portability
    • Files are portable between different operating systems and programs
  • Speed
    • Plain text files are lightweight and fast
  • Consistency
    • Plain text always looks the same

General reasons for using plain text

  • Flexibility
    • Can be used by multiple programs for many different purposes
  • Distraction-free writing
    • Focus on writing rather than fiddling with your tools
    • Think about content rather than formatting

General reasons for using plain text

  • No lock-in
    • No compatibility issues
    • No dependance on proprietary software
    • No need to worry if others can open
    • No need for special software or tools
  • Both human and machine readable

Human-readable formats

  • Easily read by humans
    • No need for additional assistance
    • No need for special software/hardware

Reasons for scholars to use plain text

Short-term benefits:

  • Quickly edit large amounts of data
    • Easily work with large, image-heavy documents or tables
  • Generate indices automatically
    • Table of contents, bibliography, citations etc
  • Track changes with version control
    • Git, diff, and other standard tools are designed for use with plain text

Reasons for scholars to use plain text

Long-term benefits:

  • Preservation of data
    • Persistence of knowledge stored in text files
  • Freedom and flexibility
    • Easily switch to another format if needed
  • Future-proofing your work, data, ideas
    • Will your work still be accessible in 20, 50, 100 years?

Input and output

  • Input/storage formats: plain text
  • Output formats: PDF, PPT, HTML, EPUB, .docx

Workflow for using plain text formats

  • Write in structured plain text
    • Use any editing software you prefer
  • Preview
    • Or use an editor with a live preview function
  • Output
    • Export to any other format as needed

Let’s try it out!

What is Markdown?

Markdown is a lightweight markup language based on the formatting conventions used in email

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. –John Gruber

Markup formatting

Markdown, AsciiDoc, ReStructured Text, Org-Mode, HTML, XML… are all types of text markup that introduce various conventions for formatting text

Most importantly, they allow different methods for introducing minimal structure into plain text documents

Plain text markup formats

  • Markdown
  • AsciiDoc
  • Org-Mode
  • ReStructured Text
  • HTML
    • Hypertext Markup Language
  • XML
    • Extensible Markup Language
  • …

Markup can be easily converted into…

  • Polished documents (e.g., PDF, .docx, Epub)
  • Websites (e.g., Jekyll)
  • Documentation (e.g., Just the Docs)
  • Presentations (e.g., Reveal.js, PPT)

Plain text data formats

  • Tab-Separated Values (TSV)
  • Comma-Separated Values (CSV)
  • JavaScript Object Notation (JSON)
  • YAML
  • MySQL

Plain text data can be easily converted into…

  • Spreadsheets (e.g., .xlsx)
  • Databases
  • Charts, graphs, analytics
  • Website APIs

Formats of interest to scholars

  • BibTeX (Bibliographies and citation data)
  • TEI (Text Encoding Initiative)
  • CSL (Citation Style Language for citation formatting)

Complex documents

  • Markdown is great for short, simple documents
    • Designed for publishing to the web
    • Issues when trying to create more complex documents

Complex documents

  • For academic writing and more complex documents, AsciiDoc may be a better choice:
    • Supports footnotes, call-outs, complex tables, math, embedded files etc.

Complex documents

  • AsciiDoc is designed for formal publishing

Complex documents

Complex documents

More examples:

Converting between formats

  • Pandoc
    • “Swiss-army knife” for converting from one markup format to another
    • Command-line tool
    • But we can try it online: