Introduction to Markdown Digital Workflows
Plain text formats have received increasing attention from scholars in recent years and have been described as among the best ways to store knowledge persistently. This workshop will introduce you to the benefits of using plain text files and simple markup formats to create flexible, robust, and future-proof workflows for digital scholarship, research, and knowledge. We will begin with a brief introduction to the Markdown text format and create a short sample document which, with the use of a few simple tools, can be converted into a website, dynamic slideshow presentation, PDF, and even a formatted PhD thesis. We will also cover how to migrate existing “closed” files like Word documents and PowerPoint presentations into more accessible plain text Markdown (or similar formats like Asciidoc), for archival, collaboration, version control, and other purposes.
Prerequisites
- A text editor (note: not a word processor!) that can save in plain text format. We will be using the online Markdown editor Dillinger in this session. For a cross-platform editor that you can download and install on your machine, a good choice is Atom.
Helpful, but not required
- A GitHub.com or GitLab.com account. We’ll discuss briefly how to use GitHub Pages to host a static site. For a more complete introduction to creating static sites with GitHub Pages, please see the Introduction to Jekyll workshop.
- Some familiarity with working in a command line / Unix shell interface. Some of the tools we will introduce make use of the command line, but there are usually online or graphical alternatives and this is not required. If you’d like to learn more about the command-line shell before you start, please take a look at this workshop: Introduction to the Unix Shell.
- Pandoc command-line setup. Install Pandoc if you would like to follow the optional examples for converting Markdown to Word, PDF, and presentation formats. The introductory exercises do not require it.
- Some familiarity with Git and version control. If you’d like to learn more about Git and GitHub before going any further, please see this workshop: Introduction to Git and Github.
Pandoc set-up (optional)
The following steps prepare Pandoc, the workshop files, and a command-line environment for the optional conversion examples.
Download the workshop files
Download the complete workshop repository as a ZIP file, then extract it on your computer. The extracted intro-markdown-HEAD directory contains the sample Markdown files and their images. GitHub does not provide a built-in option to download only the data directory, and the conversion examples rely on its directory structure, so downloading the complete repository is the simplest approach.
Open a Unix shell
- macOS: Open the Terminal application. You can find it in Applications > Utilities or search for it with Spotlight.
- Linux: Open your distribution’s Terminal application.
- Windows 10 or 11: Install Windows Subsystem for Linux (WSL) and a Linux distribution such as Ubuntu. We also recommend Windows Terminal for working with WSL. These are the same tools used in the Introduction to the Unix Shell workshop.
Install Pandoc
On macOS, install Homebrew if needed, then run:
$ brew install pandoc
On Ubuntu, Debian, or Ubuntu running in WSL, run:
$ sudo apt update
$ sudo apt install pandoc
Packages are also available for other operating systems on Pandoc’s installation page.
Confirm that the installation works:
$ pandoc --version
The first line should display the installed Pandoc version. Creating Word and PowerPoint files requires only Pandoc. Creating PDFs with Beamer also requires a LaTeX distribution; TinyTeX is a relatively lightweight option. You may install LaTeX before the workshop or complete only the non-PDF conversion exercises.
This workshop is part of the Core Skills series.
Download
You can download a PDF containing the handouts for this workshop here.
Loading last updated date...