How to write blog posts with Markdown

Blog posts are written in Markdown, which is a human- and machine-readable language that’s easy to use and write with! You’ve probably already used Markdown somewhere.

  • You can see what the Markdown files corresponding to each blog post look like on GitHub.
  • If you’re looking for a text editor that works well with Markdown, try VS Code with the Markdown Preview Enhanced extension or Typora for a streamlined experience.
  • For syntax like italics, bold text, code, and links see a good Markdown Cheat Sheet.

There are a few special features we’ve implemented that are worth mentioning. And if you feel overwhelmed, don’t worry – we’re here to help 😎!

Post metadata

At the top of every blog post is a block of information, or metadata, telling Jekyll (the program that builds the web site) how to treat your post. It will look something like this:

cover:  assets/images/YYYY-MM-DD-your-title-with-no-spaces/cover.jpg
title: Title for your post
date: YYYY-MM-DD HH:mm:ss
tags: [tag-1, tag-2, tag-3]
author: username # remember when you created an author username? It goes here!
permalink: YYYY-MM-DD-your-title-with-no-spaces # this will be the permanent link to your post
navigation: True # don't change this
layout: post # don't change this
current: post # don't change this
class: post-template # don't change this
subclass: 'post' # don't change this

Most of them you should copy and paste exactly. However:

  • author: If you’re writing a post for the first time, create a username and add it with your information to /_data/authors.yml. Then set this field to the username you created
  • cover: an image to use with your post on the homepage
  • date: Set the date you would like to have associated with your post
  • permalink: this will be the link to your post so choose something short and unique (no spaces!)
  • tags: You can add any number of tags to your image. If you’re creating a new tag, you should also add a description to /_data/tags.yml.
  • title: The title of your post


If you’re using images, it’s vital that you post an image that you have permission to share – we don’t want to get in legal trouble! There are two ways to do this:

  1. add an image that you have taken (or that you have permission to share) to the repository (put it in assets/images and give it a specific, useful name – perhaps one that relates to the name of your post). then, link to it as assets/images/file_name.sufix when you’re including it (see syntax below)
  2. embed an image from a site like Wikipedia or Flickr that provides open-access images.

To add an image, you just use regular markdown syntax:

![alt text](image-url)

If you add #full to the end of the image URL, you can get cool full-width images:

![full width image of drought](https://upload.wikimedia.org/wikipedia/commons/4/4e/Drought_in_the_Valley.JPG#full)

full width image of drought

Sites like Flickr also provide code to embed an image. Copying and pasting in the html code from their site gives nice results like:

maaslant kering (5)

Here’s how to link to a local image

![stock photo](assets/images/2020-07-24-markdown-tips/cover.jpeg)

stock photo


You can embed math using KaTeX. For example,

{% katex display %}
c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

will render as

c=±a2+b2 c = \pm\sqrt{a^2 + b^2}

See https://github.com/linjer/jekyll-katex for more sophisticated syntax including inline math and shortcuts if you’re writing a lot of equations.


If you’re citing an academic document, you can do so using the jekyll-scholar plugin. To do so, you first need to put the bibtex entry for the work you would like to cite in _bibliography/library.bib. For example, add

  title = {Adaptation over Fatalism: Leveraging High-Impact Climate Disasters to Boost Societal Resilience},
  author = {{Doss-Gollin}, James and Farnham, David J. and Ho, Michelle and Lall, Upmanu},
  year = {2020},
  volume = {146},
  doi = {10.1061/(ASCE)WR.1943-5452.0001190},
  journal = {Journal of Water Resources Planning and Management},
  number = {4},
  open = {true}

Then I can cite it using

{% cite doss-gollin_fatalism:2020 %}

which renders as (Doss-Gollin et al., 2020). To add a bibliography, just add

{% bibliography --cited %}

at the end of your document and it will render as

  1. Doss-Gollin, J., Farnham, D. J., Ho, M., & Lall, U. (2020). Adaptation over Fatalism: Leveraging High-Impact Climate Disasters to Boost Societal Resilience. Journal of Water Resources Planning and Management, 146(4). https://doi.org/10.1061/(ASCE)WR.1943-5452.0001190


You may want to reference some material that isn’t an academic paper or clarify a subtle point. You can do so using footnotes. To add a footnote to markdown, just type type [^some_key] after your text. some_key can be a unique identifier for each footnote, since you can have an unlimited number of footnotes.1 Then somewhere below type

[^some_key]: This is an example of a footnote

and at the bottom of the page it will render as

  1. This is an example of a footnote 


James Doss-Gollin

I use data science, decision science, and earth science to design adaptive infrastructure for resilient communities

Read More