The Digital Fellows’ “Format Your Dissertation Like a Pro: Writing with Markdown” workshop taught by Rafael Davis Portela introduced Markdown, a markup language (a way to annotate and present text in a document using tags, with HTML being one example) meant for writing dissertations, web content, notes, or really any form of text, that uses relatively limited formatting options so that the focus remains on the actual writing itself.

Basically, you’re writing your document in a plain text editor with the ability to add minimal formatting to it using syntax. There are benefits such as being able to move paragraphs around without worrying about messing up the formatting, writing lists without being concerned about the specific order, and including notes to yourself that don’t appear in the final version. The file is a plain text file so you don’t have to worry about compatibility issues and you can easily convert it to other formats when you’re finished such as a doc, pdf or html file, or even into presentation slides.

Pre-Markdown

You will need to download some tools to convert the Markdown file when you’re done and if you prefer, you can create the Markdown file itself in Terminal, the info for which is all found on Rafael’s Github page for the class. Just to try using Markdown, you can use Visual Studio Code like we did in the workshop or another text editor, and save the file as a .md file. Or try Markdown in a browser without installing anything at dillinger.io.

Markdown syntax

You’re pretty much just writing your text in the text editor but when you want some basic ways of structuring or styling your text, such as for headlines, lists or links, here’s some of the syntax you can use. (I wasn’t sure of the best way to present the syntax and the result in WordPress so I used screenshots.)

Headings: For the equivalent of headings in Word or Google Docs, you use the pound sign (or hashtag). I’m not sure the best way to present the syntax

Paragraphs and line breaks

• To start a new paragraph, leave a blank line after the previous paragraph
• For a line break, add a “\” at the end of the line

Text formatting

Block quotes: Add a “>” in front of the text to make a block quote. (Correction: The result is missing the words “in Markdown.”)

Lists

• Use *, + or – for unordered lists and add four spaces before the mark for second-level bullets.
• Write “1.” or “1)” for ordered lists – you can use 1 or any number, and repeatedly, as Markdown will automatically convert it to an ordered list. (Correction: The “A.” in the syntax should be a “1.” or any number. Doesn’t matter as Markdown will order it for you.)

Comments: A comment doesn’t appear in the final version. It can be a reminder or note to yourself. Or it can be text you’re not sure you want to include in the document but in case you change your mind, you simply remove the syntax, which is:

<!– A comment surrounded on both sides by the syntax –>

Links: Use brackets for the text you’re linking and parentheses for the URL with no space in between.

The rest

• Go to Rafael’s Github page for the workshop for more on inserting images, footnotes and converting Markdown files to pdf/doc/html files, eBooks, presentations, etc. And on automatic citation.
• Additional syntax info here and here.
• To get an idea of what Markdown could look like, here’s a screenshot of the post I wrote before putting it in WordPress:
• Before the workshop, I would use the TextEdit application in plain text format to write since I could produce a clean text that can be formatted in other software. However, I did wish I could, for example, differentiate heading text from paragraphs or make links or tables. Markdown looks like a good solution for keeping the focus on the text without, say, being distracted by multiple fonts and colors or inconsistent line spacing, while still letting you do some basic formatting to distinguish different parts of the text. I still have to become comfortable with converting the Markdown document to other formats – and figure out if there was an efficient way to “convert” it to a WordPress post – but in the meantime it seems like an efficient way to write text without many of the concerns that come with word processing software.