Usually when we create files, we notice that they have a few characters after a ., like .doc or .csv or .txt.. That’s what is known as a file extension and it tells computers the file format, as well as which applications and programs can interact with that file. To see a full list of file formats, visit https://en.wikipedia.org/wiki/List_of_file_formats.

Under the Document heading https://en.wikipedia.org/wiki/List_of_file_formats#Document, you’ll find many of the different standards that exist for working with documents specifically and also the usage of different file formats (so GDOC is a Google Drive Document for example).

The one we’ll be using for writing documents in this course is called Markdown or MD. Markdown files end with .md extension and can be written in your text editor of choice. Also there are specific writing tools that can be used to write Markdown files, like Ulysses for Macs or Ghostwriter for Windows. Also if you use the popular tool, Notion.so it also exports to Markdown.

As some background for what Markdown is exactly,

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form. From Wikipedia page https://en.wikipedia.org/wiki/Markdown

The big difference from writing in something like Word or Google Docs is that Markdown is a plain text format and that you don’t use buttons to format your text. Instead, you directly format it with Markdown.

For example, if you wanted to write a header with a paragraph, you would write it like this:

### This is a subheading

Here is a paragraph with a bolded word: **bolded**

Which renders in our browser like this:

This is a subheading

Here is a paragraph with a bolded word: bolded

This may seem like a lot of extra work, but the advantages of Markdown are numerous.

  1. It is much more sustainable than Word or Google Docs. This is because the text is saved as plain text and not in a format that is optimized for editing. This makes it future-proof so that you don’t require a license or access to an application to see your files.
  2. It can also be rendered by any text editor. This is because Markdown is a plain text format and not a rich text format. This makes it platform agnostic.
  3. Finally, Markdown plays nicely with Github, which renders it directly in your browser. This makes it easy to push up your files into your repositories.

If you are new to using Markdown or have some questions about some syntax we have been using, I highly recommend you take a look at the following resources.

  1. Sarah Simpkin, “Getting Started with Markdown,” Programming Historian 4 (2015), https://doi.org/10.46430/phen0046.
  2. Then for more depth, you could also check out the Markdown Guide’s Getting Started page https://www.markdownguide.org/getting-started/
  3. The Markdown Guide also has a series of helpful cheatsheets if you are looking for a quick reference:
  4. And finally for Github-flavored Markdown (that is Markdown that is compatible with Github’s Markdown syntax), you can check out https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.

Have any additional questions? Either ask them in our Discord or message the instructor

Updated: