Academic Writing in Markdown

Welcome to this introductory video and Markdown,
where I show you how working in plain text can make your academic writing easier. In this video I'm going to cover the following
topics: First, I'm going to give you a definition of what Markdown is, and then I'll talk about
the advantages of working in Markdown, both in general and then specifically for academics. After that, I'll do a live example of academic
writing and Markdown. In fact, if you want to skip right to the
action you can just forward the video. Then finally, I'll end with some recommendations
for those of you who are interested in pursuing Markdown further. So what is Markdown? On an abstract level, we could say that Markdown
is a way to simplify writing in the digital age, where we have to publish the same text
in multiple forms and where we rarely have to print things out. On a more concrete level, though, Markdown
is a syntax that allows you to incorporate rich text elements into plain text documents. Now there's a lot of jargon in that definition,
so let me unpack some of those terms. First, what is rich text? So you know when you open up a Microsoft Word
document and you can see all the formatting features in the text? You know, the word you want to be bold or
bold, and the words that you want to be italicized appear in italics. Then there are other elements. They are footnotes, section titles, different
kinds of fonts, sizes, colors. Those are all features that you can see in
a rich text document. Now, in contrast, a plain text document has
none of those features. All you have are letters, numbers, punctuation
marks, and then other symbols. You don't have any of the formatting elements
that you can include in a rich text document. And all of this then brings us to syntax. Now syntax is a system for using symbols and
characters to explain to your computer how you want certain things done or, in this case,
how you want your text to look. For example, if I'm writing in plain text
and I want a word to appear as bold, I can't simply highlight it and then hit control+B
like I do in Microsoft Word. So I use a certain syntax to represent it
in Markdown. That just means that I put asterisks on either
side of the word that I want to be bold. So, now what are some of the general advantages
of writing in Markdown? First and foremost, it makes you focus on
your writing and keeps you from getting distracted by formatting. And I don't know about you, but when I have
a writing project and I'm working in Microsoft Word, I spend a lot of time making sure that
the headers look the way I want them to look, picking the font that I want to use — you
know, generally fiddling with the formatting — as a way to procrastinate. But when I'm writing in Markdown, I don't
have any of those excuses. I have to, you know, write. Another advantage of Markdown is that it can
easily be exported to multiple formats. So I can write a document in Markdown and
then convert it into HTML for publishing on a web site, or to a PDF for printing, or even
a Word document if the person I'm working with just has to have it in Microsoft Word. Markdown allows you to export to all these
different formats. The actual text file that you're working in
is basically future-proof. I mean, have you ever wanted to access some
writing that you did a decade ago and WordPerfect or maybe you have a bunch of writing you did
in Pages (Apple Pages) before they changed the file format and now you can't open those files? Or what will happen if people stopped using
Microsoft Word? What will happen to those files? Or maybe you just don't want to pay Microsoft
Word for their license. None of this is a worry if you're working
in plain text. It's the same as it was decades ago, and it'll
continue to be the same decades from now. The final advantage of plain text documents
is that they're small, easy to move from one device to another, and easy for many different
programs to read. This means that you can start a document on
your computer, and then you can work on it on your iPad or even on your phone, and you
don't need to worry about taking up lots of memory or having compatibility issues. And all of these features that I just mentioned,
they're going to be helpful to academic writers, but there are two additional benefits that
I think will be especially helpful. The first is that Markdown makes collaboration
easy. Have you ever been working with a team on
an article or a long report and you all have formatting conflict issues? Like, one person wants Microsoft Word, another
person is using Google Docs, the third person is using Microsoft Word but with a template
that they really like. None of this is an issue when you're writing
in plain text. You just assemble all of the pieces, and then
everything is uniform and formatted consistently. The second benefit is that in the particular
flavor of Markdown that I am using (called Pandoc), all the references are auto-generated
for you. So it doesn't matter if one person is using
Chicago, another person likes APA. Again, Markdown takes care of all of that
for you. In fact, even if you're writing just for yourself,
it's helpful to not have to worry about all the citations being correct. You just let Markdown take care of it. So that's what I have to say about the benefits
of Markdown. Now let's move to the demonstration part of
this video. Before I do though let me point out a few
things. On the next screen, the left side is going
to have a white background, and that's where I'll be writing in plain text. The right side of the screen is where the
final formatted text will appear. It represents how your text might look if
it were published on a website. I've made it yellow and added some other contrasting
colors to make it stand apart from the plain-text side of the screen. Remember that you can always adjust the colors
and formatting as you see fit. Also, because this is more of a demonstration
video than a how-to video, I'm going to move pretty quickly through the features of writing
in Markdown. My objective is to give you an idea of how
Markdown works so that you can then go off and explore it further on your own. So with all of that in mind, let's get started. So here we are in the demonstration screen
and, again, the plain text is on the left and the preview is on the right. The first thing I'm going to do is add a title
to this document, and the way you do that is in the first line of the document you start
with a percent sign (%), and then you add your title. If you want to add the author, you use another
percent sign in the next line, and you can even add the date. Of course, most academic writing also needs
sections, so let's add those, too. The way you do that (and I'll go to a new line) is you use
a hashtag (#). If I wanted to add a subsection, instead of using one hashtag, I would use
two. Once you have the document structure in place, you can start writing. And in Markdown, you simply separate your paragraphs by one
blank line. So it might look something like this. Now, if I wanted my words to be in bold or
italics, I would simply put asterisks (*) around the part that I wanted to be in italic or
bold. So for italics, I use one asterisk on either
side, and if I wanted it to be bold, I would use two asterisks. Now let's say, in this first paragraph, I wanted
to include a list. How would I do that? Well, I would start a new line. I'll make my list items here. If I wanted this to be a bulleted list, I
would just add asterisks and a space before each item. If, instead of a bulleted list, I wanted a
numbered list, I would replace it with — you guessed it — numbers. Another thing you might want in your academic
writing is a block quote for long citations. This is very easy in Markdown. All you do is you add a more-than sign (>) and
a space. Something else that might be useful are footnotes. To do that, you just use a square bracket
([]), a caret symbol (^), and the shorthand you want for your note. Then you close the square brackets. Then at the bottom of the document (actually
anywhere in the document), you repeat the same syntax with a colon (:) and then
the note. You can see in the preview, the number's right
here. If I click on it, it'll take me down to the
bottom, and then I can click on the back arrow to take me back. Let's say that, instead of a numbered list,
I actually wanted to use a table. Well in Markdown, I would use a series of
pipes and dashes to create that table. It would look something like this. If I wanted to add a caption, I would just
add it below. And now we're going to get to the good part,
the part where Markdown really earns its keep for academic writing, and that's in citations. So let's start with the block quote. Let's say I want to add a parenthetical citation
at the end of that block quote. The way I would do it is I would use the "at" symbol (@)
and then a citation key. So let me get the citation key. You can see the citation key has been added
here. I'll put it in square brackets, and watch
as it appears on the other side. Now this is in Chicago format. In addition to parenthetical citations, I
can also do in-text citations. In fact, if we go to the first paragraph,
let me just copy and paste this same one. You can see that I have the author name and
year. Then if I scroll to the end of this document,
you can see that the full reference has been added. So that's a quick rundown of academic writing
in Markdown: How you can add title, author, date, sections, paragraphs, bold and italic
words, add lists, also block quotes, footnotes, tables, and references. I hope what comes across is just how simple
these syntax rules are and what a big payoff you can get in the long term in your own academic
writing. So that's it for this video on academic writing
in Markdown. If you like the video, please click like below. If you want more, please subscribe, and also
leave me your comments in the comment section. Also, let me end with a few recommendations
if you want to pursue Markdown further, the first resource I would recommend is the *Markdown
Field Guide* by David sparks and Eddie Smith. The second one I would recommend is going
to the Pandoc website. There's a lot of tutorials and very comprehensive
instructions on using this version of Markdown. Finally, I recommend David Smith's blog, which
has some great tips for starting to use Markdown if you're an academic writer. The links to all of these resources are in
the description for this video. So that's it for now. Thanks for watching and take care!

37 thoughts on “Academic Writing in Markdown

  1. Great video. I'm glad more professionals are standardizing on Markdown, I found it recently and love it.
    Just a little technical note: the audio is very low at certain parts of the video, do you think you could try playing with the audio gain for the video?

  2. Thank you for sharing this incredible presentation for academic writing with Markdown. Time for me to download this application on my system.

  3. Just discovered #pandoc today but didn't know that markdowns could be a future-proofing technology. My Office 365 subscription just ended and I needed to find a better (free) way to convert back and forth from Word .doc/.docx files to PDFs. Looks like pandoc might do it. Great run-though

  4. Hi Nicholas, I wonder if you have plan to write tutorials on the version control system for academic writing. Actually one of my motives to learn markdown language is that I want to learn to use Git to control the versions of writing. Thanks a lot!

  5. Noice! My only issue is that I feel your description for pandoc markdown would better describe lightweight markup languages in general.
    Secondly, have you heard of org-mode markup for emacs? It is what I write most of my schoolwork in these days and is pretty intuitive.

  6. This is such a great video. Despite the fact that im totally overwhelmed by markdown and its simplicity, you've just got the right way to give your audience enough information without taking too long to get on point. Keep your great work on!

  7. Great explanation. I co-edit an open access academic journal called Asian Ethnology. At the moment, all authors submit work in Word, we edit that, and then import into InDesign to publish PDFs (for print and download). But we're about to launch a new website with all new material also available online. I really want to do what you are showing here – it would be great if the authors would also use Markdown but I'm I'm afraid many won't. I've tried the online Word to Markdown converter, but I'm wondering if there's a less clunky way of doing it (so that the Markdown document doesn't get filled with various Word junk). So I'm considering how to resolve the workflow issues. If you've got any tips, I'd love to hear them. But this is the clearest explanation of Markdown for academic writing I've seen so far. Thank you.

  8. Thanks for the tips. I didn't find any clues for command line users though. Got stuck with pandoc-citeproc. Get an error every time I try to make reference to a my bib file.

Leave a Reply

Your email address will not be published. Required fields are marked *