loading...
Cover image for How to Use GitHub Pages

How to Use GitHub Pages

brunodrugowick profile image Bruno Drugowick Updated on ・2 min read

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 drugo.dev (and the irony is that I'm moving to dev.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>.github.io. The <username> must be your GitHub username.

Create an index.md file with the following content:

# Hello World

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

Theming

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:

YEAR-MONTH-DAY-title.md
Example: 2019-04-24-HelloWorld.md

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

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.

Finally...

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.

Posted on by:

brunodrugowick profile

Bruno Drugowick

@brunodrugowick

I love helping people to understand and deal with technology. If I can build something in the process, even better!

Discussion

markdown guide
 

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 dev.to settings and auto import your articles as drafts on dev.to.

 

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 dev.to, with native comments from dev.to.

I don't want that. I ended up here at dev.to 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 dev.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 dev.to post.

Take a look: drugowick.dev/ (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 dev.to. I could maybe iterate over the RSS from dev.to on my Jekyll blog (since dev.to API doesn't provide an excerpt) or even automate the excerpt creation... but that's for another time... hehehe.