DEV Community

Cover image for How to Use GitHub Pages
Bruno Drugowick
Bruno Drugowick

Posted on • Updated on

How to Use GitHub Pages

How to Use GitHub Pages

GitHub Pages can serve static content for free using your GitHub account. I use Jekyll to theme and blog on (and the irony is that I'm moving to now - more on that later). Whenever you commit to your GitHub Pages repository, Jekyll runs to rebuild the pages in your site, from the content in your Markdown (or HTML) files.

Quick Start

For free GitHub accounts, create a public repository called <username> The <username> must be your GitHub username.

Create an file with the following content:

# Hello World
Enter fullscreen mode Exit fullscreen mode

Now your website is up and running at https://<username>


You can theme GitHub pages simply by going to your repository Settings page and selecting a theme using the Theme Chooser on the GitHub Pages section. What this does is create a file on the root of your project... so, if you create the file yourself, you're done. Follow the steps:

  1. Create a file named _config.yml on the root of your GitHub Pages repository.
  2. Add the following to the file:

    theme: jekyll-theme-cayman
  3. Commit the file and push it to GitHub.

You're themed! If you want to use other themes, you can either go to your repository Settings page or learn more here.

Blog Posts

Create a file

Blog posts are files with the following name convention under _posts directory:
Enter fullscreen mode Exit fullscreen mode

Add a header

The following header must be added to every blog post, although you might want to customize title and other things. It's up to you, really. The HOME link for example is totally a personal choice.

layout: default
title: "Hello World"

[HOME]({{ site.url }})
Enter fullscreen mode Exit fullscreen mode

You then start writing your post using Markdown syntax.

Developing locally

You don't want to edit everything on your web browser, do you? Especially after you start to know everything Jekyll can do.

To build the website locally follow the instructions here. You'll need Ruby. Build and run locally with bundle exec jekyll serve after configuring everything.


There's way more to learn about GitHub Pages and Jekyll, but I'd like to suggest just one more piece of documentation:

Jekyll Data Files

Jekyll Data Files are very useful to organize the information on your GitHub Page. It gives you the ability to edit sections of your page without touching the markup file (.md or .html), just like I taught you with the Posts, but for your own data structures.

If you want to take a look, this websites uses, so far, Data Files for the "Useful Links" and "Active Projects" sections.

Top comments (2)

chrisrhymes profile image
C.S. Rhymes

I use Jekyll on GitHub pages too. If you use the Jekyll-feed plugin it will generate an RSS feed. You can then link to this in your settings and auto import your articles as drafts on

brunodrugowick profile image
Bruno Drugowick

Hi, Chris. Thanks for the suggestion.

But you end up with several comment options, right? I saw that in your website you have Disqus and you have a duplicate of the post here on, with native comments from

I don't want that. I ended up here at trying to figure out the best way to have both more traffic and comments on my blog/posts. What I did (in fact just did, see this commit) was to move my posts to and on the blog my posts are now just excerpts of the posts. To the excerpt I added a property with the link to the post.

Take a look: (if you haven't already).

This way I have more traffic (I can say that with confidence since we're discussing over my post, hahahaha) and only one place to manage the discussions.

This added a complication, which is to create the excerpts on my blog after every post here on I could maybe iterate over the RSS from on my Jekyll blog (since API doesn't provide an excerpt) or even automate the excerpt creation... but that's for another time... hehehe.