The best way to submit a blog post is as follows:
- Fork and clone the GitHub repository
- Write your blog post and add all multimedia to the directory
- View results on your computer (optional)
- Push your changes to your GitHub
- Create a pull request to merge your changes into the main website
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.
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
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
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
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".
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
It should be named after your tag, like
_data/tags.yml in your text editor and create a new tag.
It should look like this:
your-tag-name: 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
Second, create a folder to store any pictures for your blog post as
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
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
To install the files specified in the
Once that’s done, you can run the site!
bundle exec rake site:watch.
You should see a line that looks like
Server address: http://127.0.0.1:4000// Server running... press ctrl-c to stop.
In that case, open
http://127.0.0.1:4000// 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
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 🥛!