Getting started with GitHub Pages: Part 1 -- Publishing a single markdown file

GitHub Pages is GitHub’s static site publishing platform. In addition to supporting regular HTML content, GitHub Pages is deeply integrated with Jekyll, a popular static site generator designed for blogging and software documentation. And that’s not all! GitHub Pages sites are used for everything from blogs to full blown sites.

We’re going to talk about more complex GitHub Pages sites later on in this series. For right now, we’re going to work through the simplest way to use GitHub Pages: publishing a single Markdown file.

In this guide, we’ll walk you through creating a repository, using it to publish a User Pages site, editing a file on GitHub, and committing your changes. All you need before we begin is a GitHub account with a verified email address; no other experience is necessary.

Step One: Create your Repository

Once you’re signed in to your GitHub account, you’ll create a new repository to get started.

Your website’s files will live in a repository named $, where “$YOUR_GITHUB_USERNAME” is your actual GitHub username. For example, my GitHub username is nickcannariato, and I’m naming my repository

Important: Make sure to select the “Initialize this repository with a README” checkbox so that GitHub pre-populates your repository with a README file.

Step Two: Edit your README file

Now that you’ve created a repository and named it appropriately, you’ll need to edit your file.

This is where you’ll write your content. This part usually requires a lot of thought, but to speed things up a bit we’re going to provide you with some basic Markdown content. Delete the content currently found in the file and then copy and paste the content below into the file editor.

# Hello, World!

I've just published my first GitHub Pages site!


Step Three: Commit Your Changes

Once you’ve added the content above to the file, you’ll need to write a commit message in the “Commit changes” box below the file editor. Writing good commit messages is a subject worthy of it’s own guide, but an example of a good message you could use for this commit would be:

Add "Hello, World!" text to the README.

If you feel that your commit message needs more context or have any notes about the change you’re making, you can optionally add an extended description in the box below your commit message.

A brief note: committing directly to the master branch is not generally something that we’d recommend. For the purposes of this guide, we’ll stick with committing to master, but rest assured, we’ll walk you through much better workflows in future guides.

Once you’ve added your commit message and selected “Commit directly to the master branch”, you’ll submit your changes by clicking the green “Commit changes” button.


Step Four: You’re done!

GitHub Pages builds your site every time you push changes to your GitHub repository. This means that whenever you commit new changes to your repository, GitHub will publish those changes automatically. It may take a few minutes, but you should now be able to navigate to your GitHub Pages URL (i.e. and find the content of your file published as the main page of your site.

By default, GitHub Pages will apply some minimal styling to your content unless you’ve added a theme to your site. If you’ve followed the steps in this guide, your site will look something like the screenshot below.


What Now?

Congrats! You’ve published your first GitHub Pages site! Be on the lookout for part two where we’ll talk about adding a theme to your GitHub Pages site, and please let us know if there’s a particular GitHub Pages topic that you’d like us to write about in the future.

Finally, If you’re interested in learning more, here are some resources that might help you level up your GitHub Pages skills.


Nice post @nickcannariato! You explained it very well!