Submit a blog post using git and GitHub

The best way to submit a blog post is as follows:

  1. Fork and clone the GitHub repository
  2. Write your blog post and add all multimedia to the directory
  3. View results on your computer (optional)
  4. Push your changes to your GitHub
  5. Create a pull request to merge your changes into the main website
  6. Profit

Sound tricky? It’s not as hard as it sounds. Learning to contribute to GitHub repositories is a valuable skill!

Feeling stuck? We’re here to help 😉! Head over to the GitHub issues tab and click the “New Issue” button.

Before we get started

  • You’ll need a good text editor. There are lots of great ones out there but if you don’t have one VS Code is a good option
  • You’ll need a GitHub account. If you don’t have one, head over to https://github.com/ and create one
  • You need git installed on your computer. If you haven’t used git before, GitHub Desktop is a great choice

Fork and clone the repository

GitHub’s documentation explains that forking a repository allows you to freely experiment with changes without affecting the original project. In this case, forking the repository lets you create a copy of this web site’s source code, which you can modify to add your article.

You can follow the instructions here to fork the repository jdossgollin/americas-water-blog and clone it onto your computer.

Write your post

Now you have a copy (“clone”) of the web site source code on your own computer. It’s time to write your blog post!

Adding yourself to the authors list

If this is your first time contributing to the blog, you first need to add your information to the list of authors! This lets the web site build a profile page for you, like mine.

First, think up a username for yourself. It should be easy to remember!

Next, find a square image of yourself that you like. Copy it into assets/images/people. If you see one there called jdossgollin.jpg you’re in the right place! Make this file your username (i.e., jdossgollin is my username so my picture is jdossgollin.jpg).

Optionally, if you have a cool background image (think a cover photo like Facebook, Twitter, and LinkedIn), you can copy it here as well. Follow the same naming convention, like jdossgollin-cover.jpg.

Last, open the file _data/authors.yml in your text editor. Add a block that looks like this and fill in the missing fields.

your_user_name: # update this
  username: your_user_name # update this
  name: Your full name
  url_full: A URL linking to your web site or profile
  url: a short version of the URL
  bio: A short description of yourself
  picture: assets/images/people/your_user_name.jpg # replace your_user_name
  twitter: jdossgollin # your handle here
  cover: assets/images/people/your_user_name-cover.jpg # replace your_user_name

Be aware that .yml files are sticklers about indentation and syntax. You may wish to wrap your bio in double quotation marks: bio: "long string here".

Adding tags

Every post is organized with one or more tags that explain what kind of post it is. Just like every author has a profile page, every tag gets a profile page that shows off all the posts that are tagged with it. Tags are organized just like authors, with a profile page of their own.

First, take a look at the tags that are already on the web site here. If your post fits one or more of these tags, skip to the next section.

If you want to create a new tag, then the process is very similar to adding an author. First, think of a name – with no spaces – for the tag. Shorter is better. Next, find a cover photo for the tag and add it to assets/images/tags/. It should be named after your tag, like how-to-contribute.jpg. Last, open _data/tags.yml in your text editor and create a new tag. It should look like this:

  name: your-tag-name
  long_name: A title for your tag
  description: A longer description of your tag
  cover: assets/images/tags/your-tag-name.jpg

Write the post

Phew, that was a lot of work. But you made it and you didn’t give up 🎉🎊! Now it’s time to write the blog post!

As discussed in the Guide to Writing in Markdown (you’ll want to read that), blog posts should be written in Markdown format. Markdown is easy to write with, has minimal syntax, and is converted to HTML on the back end to look great on the web.

First, create a blank file in the _posts directory. Name it YYYY-MM-DD-your-title-with-no-spaces.md.

Second, create a folder to store any pictures for your blog post as assets/images/YYYY-MM-DD-your-title-with-no-spaces/.

Next, find a cover photo for your blog post. Save it that directory as and name it cover so the full path is assets/images/YYYY-MM-DD-your-title-with-no-spaces/cover.png (PNG, JPG, it’s all fine).

Next, you need to add post information. Add a block that looks like this to the very top of your post and update the cover, title, date, tags, author, and permalink fields. Paste the others as they are.

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
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

That’s all the setup required. Go ahead and write your amazing content! Remember to check out our Guide to Writing in Markdown to see how to add math, images, and more!

Build locally (optional)

If you’re not comfortable at the command line skip, this step – it’s optional! Come back in a few months when you feel a bit more confident 💪🧠.

You’ll need Ruby installed on your machine. See their documentation – on OSX it’s as simple as brew install ruby.

Next, in the terminal open up the americas-water-blog directory. To install the files specified in the Gemfile run bundle install.

Once that’s done, you can run the site! Run bundle exec rake site:watch. You should see a line that looks like

Server address:
Server running... press ctrl-c to stop.

In that case, open in your browser. You should see a small version of the site that updates in real time as you make changes. This is a great way to make sure that your post looks just the way you want.

Push your changes

Now that you’ve written a thoughtful and incisive post, it’s time to push your changes. Specifically, this will push the changes from your computer to your GitHub account.

If you’re using GitHub Desktop, then see the instructions here to commit and push your changes. It should take just two clicks! You’ll see a box where you’re invited to write a summary of your changes. Write a helpful message like “Wrote first draft of post on how to submit a post”.

Create a pull request

The GitHub documentation says

Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.

The documentation on Pull Requests also adds that

Create a pull request to propose and collaborate on changes to a repository. These changes are proposed in a branch, which ensures that the master branch only contains finished and approved work.

To create a pull request, follow directions here. This will submit your changes for approval. We may give you feedback on your post or ask for changes to your code (for example, if you forgot a : in the authors.yml page). You can make those changes on your computer, push them to GitHub, and they will show up on the pull request – no need to delete it!

Then we’ll approve the pull request. The web site will be rebuilt automatically!


Your wallet may not be any thicker, but your software skills are looking a little sharper and you’ve shared your water vision with the world! Go drink a tall glass of cool water – you’ve earned it 🥛!


James Doss-Gollin

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

Read More