Abstract

This practical, hands-on, exercise-focused tutorial focuses specifically on how to use Markdown when producing academic work, whether that be a dissertation, a thesis, an article or a book. It is aimed at both those who have used Markdown before, and those who have no experience with it. It covers basic and extended Markdown, including how to use a reference manager such as Zotero and Citation Style Language to produce proper citations and bibliographies, and the use of additional LaTeχ packages for more advanced features such as an index or glossaries. After the course, attendants will be able to produce a document fit for publication and in accordance with academic requirements.

When it comes to academic writing, whether it is for publishing books and articles, or writing dissertation and theses, there often seems to be precious little choice regarding the writing software, especially in the Humanities. Choose Microsoft Word – and suffer unpredictable layout changes, images that move randomly, captions that do not align and inexplicable formatting changes.

Other options, such as LaTeχ, may sound great in theory, but come with a steep learning curve that is often difficult to tackle on one’s own, and restrictions in the output formats, with the generic LaTeχ output being a PDF document.

Markdown’s learning curve is much gentler, not least because of its prevalence in many common chat applications and its broad use within IT. It offers many of the same benefits that LaTeχ has – structured text, a significant reduction in layouting effort thanks to the ability to implement layout changes with just one command, and thus great versatility in what the output looks like. An additional benefit is the flexibility in output formats – Markdown can much more easily be transformed into an HTML, DOCX or PDF than LaTeχ.

Using Markdown for academic writing, however, requires features that go beyond basic Markdown. Bibliographies, footnotes, image captions and links to different parts of the document are just some of the requirements, with advanced features like glossaries often being desirable for longer works like doctoral theses or books. These features can, again, seem daunting to master.

This tutorial aims to soften that learning curve for those unfamiliar with and those who have already used basic Markdown.

Format

The full-day tutorial covers:

Morning session (4 hours):

• Installation help and troubleshooting (½ hour before the tutorial starts officially)
• Short introduction to Markdown editors
• Basic Markdown
• Creating YAML frontmatter
• Generating output with Pandoc via the console
• Reference managers and Citation Style Language

Afternoon session (3 ½ hours):

• Extended Markdown for academic writing
• Including citations and bibliographies in Markdown
• Useful Markdown hacks
• Using additional LaTeχ packages in a Markdown document

Each of the above-listed points is accompanied by practical, hands-on exercises that the participants are required to attempt to complete during the course. The solutions will be discussed straight after the exercise has been completed, and the course coordinator will be on hand in case of problems.

Practical information

Participants

The number of participants is restricted to 10 to ensure enough room for questions and troubleshooting. Attendants may be at any stage of their academic career – students, PhD, post-doc or seasoned academic looking to learn something new.

Prior experience with the shell/command line is recommended, but not required.

Technical requirements

Participants must bring their own computer and have installed the following prior to the tutorial:

• a shell (recommended: Git Bash)
• a plain-text editor such as KATE, Visual Studio Code or Notepad ++
• the document translator Pandoc
• a LaTeχ distribution such as MikTeX, TeXlive or MacTeX
• a reference manager like Zotero, JabRef, Mendeley etc.

! Note that most of those will likely be available via university software libraries/centres and can be downloaded and installed directly from there, without admin rights being required for installation. On Windows, seach for “Software Center” and check the applications listed there.

Help with installation and questions will also be available ½ hour before the tutorial starts officially. Questions can also be sent pre-conference to e.m.magin@khm.uio.no.

Learning outcomes

Participants will acquire an understanding of how structured text and markup languages, specifically Markdown, operate, and how they support distraction-free writing. They will learn how to use Markdown to produce their own academic work, including the parallel use of a reference manager to keep track of literature and produce bibliographies. They will also learn how to make use of LaTeχ packages for more advanced features such as glossaries.

Coordinator

Elisabeth Maria Magin has published a book on the use of SQL databases in Runology, layouted entirely in LaTeχ, and teaches courses on a variety of writing tools, including but not limited to Markdown and LaTeχ, at DHNB conferences and the University of Oslo. She uses Markdown and LaTeχ on the daily to write her own publications, and has over one decade of experience with using everything from Microsoft Word over LibreOffice Word to LaTeχ and Markdown for academic writing.