Menu Search
Jump to the content X X
SmashingConf London Avatar

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf London, dedicated to all things web performance.

Build A Blog With Jekyll And GitHub Pages

I recently migrated my blog from WordPress to Jekyll, a fantastic website generator that’s designed for building minimal, static blogs to be hosted on GitHub Pages. The simplicity of Jekyll’s theming layer and writing workflow is fantastic; however, setting up my website took a lot longer than expected. [Links checked March/29/2017]

What is Jekyll? Link

Jekyll is a website generator that’s designed for building minimal, static blogs to be hosted on GitHub Pages.

In this article we’ll walk through the following:

  • the quickest way to set up a Jekyll powered blog;
  • how to avoid common problems with using Jekyll;
  • how to import your content from WordPress, use your own domain name, and blog in your favorite editor;
  • how to theme in Jekyll, with Liquid templating examples;
  • a couple of Jekyll 2.0’s new features, including Sass and CoffeeScript support and collections.

Further Reading on SmashingMag: Link

Jekyll’s Simple Purpose Link

Tom Preston-Werner created Jekyll to enable people to blog using a simple static HTML website, with all of the content hosted and version-controlled on GitHub. The goal was to eliminate the complexity of other blogging platforms by creating a workflow that allows you to blog like a hacker5.

Jekyll’s Octocat mascot
Jekyll’s Octocat mascot. (Image credit: GitHub6)

Jekyll takes your content written in Markdown, passes it through your templates and spits it out as a complete static website, ready to be served. GitHub Pages conveniently serves the website directly from your GitHub repository so that you don’t have to deal with any hosting.

Here are some websites that were created with Jekyll:

The Advantages of Going Static Link

  • Simplicity
    Jekyll strips everything down to the bare minimum, eliminating a lot of complexity:

    • No database
      Unlike WordPress and other content management systems (CMS), Jekyll doesn’t have a database. All posts and pages are converted to static HTML prior to publication. This is great for loading speed because no database calls are made when a page is loaded.
    • No CMS
      Simply write all of your content in Markdown, and Jekyll will run it through templates to generate your static website. GitHub can serve as a CMS if needed because you can edit content on it.
    • Fast
      Jekyll is fast because, being stripped down and without a database, you’re just serving up static pages. My base theme, Jekyll Now54291913, makes only three HTTP requests — including the profile picture and social icons!
    • Minimal
      Your Jekyll website will include absolutely no functionality or features that you aren’t using.
  • Design control
    Spend less time wrestling with complex templates written by other people, and more time creating your own theme or customizing an uncomplicated base theme.
  • Security
    The vast majority of vulnerabilities that affect platforms like WordPress don’t exist because Jekyll has no CMS, database or PHP. So, you don’t have to spend as much time installing security updates.
  • Convenient hosting
    Convenient if you already use GitHub, that is. GitHub Pages will build and host your Jekyll website at no charge, while simultaneously handling version control.

Let’s Try It Out Link

There are multiple ways to get started with Jekyll, each with its own variations. Here are a few options:

  • Install Jekyll locally via the command line, create a new boilerplate website using jekyll new, build it locally with jekyll build, and then serve it. (The Jekyll website14 shows this workflow.)
  • Clone a starting point to your local machine, install Jekyll locally via the command line, make updates to your website, build it locally, and then serve it.
  • Fork a starting point, make changes, and then serve it.

We’ll get started with the quickest and easiest option: forking a starting point. This will get us up and running in a few minutes, and we won’t have to install any dependancies. Here’s what we’re going to do directly on in the browser:

  1. Create our Jekyll powered website.
  2. Host it for free on GitHub Pages.
  3. Customize it to include our name, avatar and social links.
  4. Publish our first blog post!

1. Fork A Starting Point Link

We’ll start by forking a repository that has followed best practices and the workflows that we’ll be covering in this article. This will get us on the right track and save a lot of time.

I have prepared a repository for us already. Head to Jekyll Now15, and hit the “Fork” button in the top-right corner of the repository to fork a copy of the blog theme to your GitHub account.

Walkthrough of steps 1 and 2. (View large version17)

Starting with a fork is great because it will give you a feel for what Jekyll is like before you have to set up a local development environment, install dependencies and figure out Jekyll’s build process.

Common problem #1: Creating a Jekyll website through the local command line can be frustrating and time-consuming because you have to install and configure dependencies like Ruby and RubyGems. Let GitHub Pages build the website for you, until you have a real need to build it locally.

2. Host On Your GitHub Account Link

As a GitHub user, you’re entitled to one free “user” website (as opposed to a “project” website), which will live at This space is ideal for hosting a Jekyll blog!

The best part is that you can simply place your unbuilt Jekyll blog on the master branch of your user repository, and GitHub Pages will build the static website and serve it for you. You don’t have to worry about the build process at all — it’s all taken care of.

Click the “Settings” button in your new forked repository (in the menu on the right), and change the repository’s name to, replacing yourusername with your GitHub user name.

Your website will probably go live immediately. You can check by going to Don’t worry if it isn’t live yet: Step 3 will force it to be built.

The base theme of your blog will look like this after being forked.18
The base theme of your blog will look like this after being forked. (Image: Jekyll Now54291913) (View large version20)

Whew! We’re moving fast here. We already have a Jekyll website up and running! Let’s step back for a second and look at some of the most common issues to be aware of when hosting a Jekyll website on GitHub Pages.

Common problem #2: Be aware of the difference between user websites and project websites21 on GitHub. With a user website (which we’re setting up), you don’t need to do any branching. The master branch is already configured to run anything placed on it through Jekyll. You don’t need to set up a gh-pages branch.

Common problem #3: Using a project website for your Jekyll website introduces some complexity22 because your website will be published to a subdirectory. The URL will look like, which will cause problems in Jekyll templates, such as breaking references to images and not letting you preview the website locally.

Common problem #4: Jekyll has a lot of plugins23, but GitHub Pages supports only a few of them24. If you try to include a plugin that isn’t supported, then Jekyll will fail while building your website. So, stick to the supported list. Luckily, my favorite plugin is on the list: Jemoji25 lets you include emoji in blog posts, just like you would on GitHub and Basecamp.

3. Customize Your Website Link

You can now change your website’s name, description, avatar and other options by editing the _config.yml file. These custom variables have been set up for convenience and are pulled into your theme when your website gets built.

Making a change to _config.yml (or any file in your repository) will force GitHub Pages to rebuild your website with Jekyll. The rebuilt website will be viewable a few seconds later at If your website wasn’t live immediately after step 2, it will be after this step.

Go ahead and customize your website by updating the variables in your _config.yml file and then committing the changes.

You can change your blog’s files from here on in one of three ways. Pick whichever suits you best:

  • Edit files in your new repository directly in the browser at (as shown below).
  • Use a third-party GitHub content editor, such as Prose26 by Development Seed. It’s optimized for Jekyll, which makes it easy to edit Markdown, write drafts and upload images.
  • Clone your repository and make updates locally, and then push them to your GitHub repository (Atlassian has a guide27 on this).
Editing your website’s _config.yml on 28
Editing your website’s _config.yml on (Image credit: Jekyll Now54291913) (View large version30)

Common problem #5: Don’t assume that you need to jekyll build the website locally in order to customize and theme a Jekyll website. GitHub Pages does that for you. You just need to place the files that you want to be built in the master branch of your user repository or in the gh-pages branch of any other repository, and then GitHub Pages will process it with Jekyll.

4. Publish Your First Blog Post Link

Your website is now customized, live and looking good. You just have to publish your first blog post:

  1. Edit /_posts/, deleting the placeholder content and entering your own. If you need a quick primer on writing in Markdown, check out Adam Pritchard’s cheat sheet31.
  2. Change the file name to include today’s date and the title of your post. Jekyll requires posts to be named
  3. Update the title at the top of the Markdown file. Those variables at the top of the blog post are called front matter, which we’ll dig into a little later. In this case, they specify which layout to use and the title of the blog post. Additional front-matter variables32 exist, such as permalink, tags and category.

If you’d like to create new blog posts in the browser on, simply hit the “+” icon in /_posts/. Just remember to format the file name correctly and to include the front-matter block so that the file gets processed by Jekyll.

Creating a new post on GitHub.com33
Creating a new post on (View large version34)

Common problem #6: One concern I had about using Jekyll for my blog was that it has no CMS, so I wouldn’t have the convenience of being able to make quick edits by logging into a CMS interface when I’m away from my laptop. It turns out that your Jekyll blog will have a CMS if you use GitHub Pages, because GitHub itself serves as the CMS. You can edit posts in the browser, even on your phone if you wish. It might not be as convenient as other CMS’, but you won’t be stuck when you’re away from your computer and need to make a change.

Optional Steps Link

Use Your Own Domain Link

Configuring your domain name to point to GitHub Pages is a simple two-step process:

  1. Go to the root of your blog’s repository, and edit the CNAME file to include your domain name (for example,
  2. Go to your domain name registrar, and add a CNAME DNS record pointing your domain to GitHub Pages:
    • type: CNAME
    • host:
    • answer:
    • TTL: 300

Then, refresh What’s My DNS35 like crazy until you’ve propagated. If you run into any problems, refer to “Setting Up a Custom Domain With GitHub Pages36.”

Import Your Blog Posts From WordPress Link

Before importing, you’ll need to export your data from WordPress, possibly massaging the data a little (for example, by updating the image references), and then import it into your new Jekyll website. Fortunately, a few great tools can help.

To export from WordPress, I’d highly recommend Ben Balter’s one-click WordPress to Jekyll Exporter37 plugin. It exports all of your WordPress content as a ZIP file, including posts, images and meta data, converting it to Jekyll’s format where needed. Good on you, Ben.

The other option is to export all content in the “Tools” menu of the WordPress dashboard, and then importing it with Jekyll’s importer38.

Next, we need to update our image references. Ben Balter’s plugin will export all of your images into a folder. Then, you’ll need to copy them to wherever you’re hosting your images on your Jekyll blog. This could be in an /images folder or on a content delivery network.

Then, you have the fun task of updating all of the links to these images across your WordPress content. Because I was only updating five or six posts, a quick find-and-replace worked well, but if you have a lot of content, then it might be worth writing a script or checking out scripts that others have written, such as Paul Stamatiou’s39.

Finally, we have to import comments. Being a platform for static websites, Jekyll doesn’t support comments. However, a hosted solution like Disqus works really well! I’d recommend importing your WordPress comments to Disqus40. Then, if you’re using Jekyll Now, you can enter your Disqus user name in _config.yml and you’re set.

Blog Locally in Your Favorite Editor

If you prefer to write in Sublime, Vim, Atom or another editor, all you need to do is clone to your repository, create new Markdown blog posts in the _posts folder, and then push the changes to GitHub. GitHub Pages will automatically rebuild your website as soon as your Markdown file hits the repository, and your new blog post will be live as soon as the build is complete.

  1. First, git clone, or clone your repository using GitHub Mac41.
  2. Create a new post in the _posts folder. Remember to name it in the format, and include the front matter at the top of the post.
  3. Commit the post’s Markdown file, and push to your GitHub repository. (Atlassian’s guide to Git’s basics42 might come in handy.)
  4. That’s it! Just wait for GitHub Pages to rebuild your website. This typically takes under 10 seconds, assuming you don’t have a huge amount of content.

Common problem #7: Again, you don’t need to build your Jekyll website locally in order to write a blog post locally and publish it to your website. You can write the Markdown post locally and push it with any images you’ve used, and then GitHub Pages will rebuild the website for you on the server.

Theming In Jekyll Link

Want to customize your theme? Here are some things you should know.

Building Your Website Locally Link

If your theme development is more substantial, then building and testing your Jekyll website locally could be convenient. This step isn’t required for theme development. You could just push the theme changes to your repository, and GitHub Pages will do the build for you. However, having Jekyll watch for theme changes locally and preview the website for you would be helpful if you’re creating a custom theme.

First, you’ll need to install Jekyll. The easiest way to do this is to install the GitHub Pages gem43 by running gem install github-pages. It’ll keep your local environment in sync with the same versions of all of the gems that are used to build GitHub Pages, and includes Jekyll and all of the dependancies you’ll need, like: kramdown, jemoji, and jekyll-sitemap. You will need to have Ruby ~> 1.9.344 and RubyGems45 installed.

Here is the workflow for building and viewing your Jekyll website locally:

  1. First, cd into the folder where your Jekyll website is stored.
  2. Then, jekyll serve --watch. (Jekyll explains more build options46.)
  3. View your website at
  4. When you’re done, commit the changes and push everything to the master branch of your GitHub user website. GitHub Pages will then rebuild and serve the website.

Common problem #8: Keep in mind that jekyll build will wipe everything in /_sites/. The first step of jekyll build is to delete everything in /_sites/ and then build it all again from scratch. So, you can’t store any files in there and expect them to stick around. Everything that goes into /_sites/ should be generated by Jekyll.

Directory Structure Link

Here’s a snapshot of my Jekyll website’s directory structure:

├─ CNAME # Contains your custom domain name (optional)
├─ _config.yml # Jekyll's configuration flags
├─ _includes # Snippets of code that can be used throughout your templates
│  ├─ analytics.html
│  └─ disqus.html
├─ _layouts 
│  ├─ default.html # The main template. Includes <head>, <navigation>, <footer>, etc
│  ├─ page.html # Static page layout
│  └─ post.html # Blog post layout
├─ _posts # All posts go in this directory!
│  └─
├─ _site # After Jekyll builds the website, it puts the static HTML output here. This is what's served!
│  ├─ CNAME
│  ├─ about.html
│  ├─ feed.xml
│  ├─ index.html
│  ├─ sitemap.xml
│  └─ style.css
├─ # A static "About" page that I created.
├─ feed.xml # Powers the RSS feed
├─ images # All of my images are stored here.
│  ├── first-post.jpg
├─ index.html # Home page layout
├─ scss # The Sass style sheets for my website
│  ├─ _highlights.scss
│  ├─ _reset.scss
│  ├─ _variables.scss
│  └─ style.scss
└── sitemap.xml # Site map for the website

Liquid Templating Link

Jekyll uses the Liquid templating language to process templates. There are two important things to know about using Liquid.

First, a YAML front-matter block is at the beginning of every content file. It specifies the layout of the page and other variables, like title, date and tags. It may include custom page variables that you’ve created, too.

Liquid template tags are used to execute loops and conditional statements and to output content.

For example, each blog post uses the following layout from /_layouts/post.html:

layout: default

<article class="post">

  <h1>{{ page.title }}</h1>

  <div class="entry">
    {{ content }}

  <div class="date">
    Written on {{ | date: "%B %e, %Y" }}

  <div class="comments">
    {% include disqus.html disqus_identifier=page.disqus_identifier %}

At the top of the file, YAML front matter is surrounded by triple hyphens. Here, we’re specifying that this file should be processed as the content for the default.html layout, which contains the website’s header and footer.

Liquid markup uses double curly braces to output content. The first Liquid template tags that do this in the example above are {{ page.title }} and {{ content }}, which output the title and content of the blog post. A number of Jekyll variables47 are made available for outputting in templates.

Single curly braces and modules are used for conditionals and loops and for displaying includes. Here, I’m including a Disqus commenting partial at the bottom of the blog post, which will display the markup from /_includes/disqus.html.

_config.yml Link

This is Jekyll’s configuration file, containing all of the settings for your Jekyll website48. The great thing about _config.yml is that you can also specify all of your own variables here to be pulled in via template files across the website.

For example, I use custom variables in Jekyll Now’s _config.yml to allow SVG icons to be easily included in the footer:

Here is _config.yml:

# Includes an icon in the footer for each user name you enter
  github: barryclark
  twitter: baznyc

And here is /_layouts/default.html:

<footer class="footer">
  {% if site.footer-links.github %}<a href="{{ site.footer-links.github }}">{% include svg-icons/github.html %}</a>{% endif %}
  {% if site.footer-links.twitter %}<a href="{{ site.footer-links.twitter }}">{% include svg-icons/twitter.html %}</a>{% endif %}
Example of SVG footer icons
Example of SVG footer icons

The variable is outputted to the Twitter URL like this:{{ site.footer-links.twitter }}, so that the footer icon links to your Twitter profile. One other thing I really like about variables is that you can use them to optionally add pieces of UI. So, a footer icon wouldn’t be displayed if you don’t enter anything in the variable.

Common problem #9: Note that _config.yml changes are loaded at compile time, not runtime. This means that if you’re running jekyll serve locally and you edit _config.yml, then changes to it won’t be detected. You’ll need to kill and rerun jekyll serve.

Layouts and Static Pages Link

Most simple blog websites need only two layout files: one for blog posts (post.html) and one for static pages (page.html). The only real difference between these in Jekyll Now is that post.html includes the Disqus comments block and a date, and page.html doesn’t.

If you create a file with an .html or .md extension in the root of your Jekyll website, it will be treated as a static page. For example, would be outputted as Nice and easy!

Images Link

I store my images in an /images/ folder in the repository and haven’t had any performance problems yet. If your website is hosted on GitHub Pages, then the images will be served up by GitHub’s super-fast content delivery network. I haven’t found the need to store them elsewhere yet, but if I wanted to migrate my images to somewhere like CloudFront, then just pointing all of my image links to a folder on that server would be easy enough.

I like the simplicity of saving an image to the /images/ folder and then linking to it in the content. The Markdown to include an image in content is simple:

![Image description](/images/my-image.jpg)

Preprocessor Support Link

Jekyll now supports Sass and CoffeeScript without any need for plugins or Grunt files. You can include your .sass, .scss and .coffee files anywhere in your website’s directory, and Jekyll will process it, outputting a .css file in that same directory.

It's Sass time!
It’s Sass time! (Image credit: Sass49)

To ensure that your .sass, .scss and .coffee files get processed, start the file with two lines of triple hyphens, like this:

$color-coffee: #644C37;

If you’re using @imports to break out your Sass into partials, then you’ll need to let Jekyll know that by including the following flag in your _config.yml file.

  sass_dir: _scss

You can specify the outputted style here, too:

  sass_dir: _scss
  style: :compressed

Advanced Jekyll Features Link

Jekyll has a couple of powerful, more advanced features that might help you if you’re looking to scale up your website from a simple blog.

Data Files Link

There are two ways to integrate external data with a Jekyll website. The first is by using third-party services and APIs. For example, Disqus allows you to embed dynamic content on your static website via its external service.

The second way is by using data files. Jekyll is able to read YAML and JSON data files50 from the /_data/ folder, allowing you to use them in your templates just like other variables. This is really useful for storing repetitive or website-specific data that you wouldn’t want bulking up _config.yml.

Data files also make it possible to include large data sets in your Jekyll website. You could write a script to break down a big data set into JSON files and place them in your Jekyll website’s /_data/ folder. A creative example of this is serving Google Analytics data to Jekyll51 in order to rank blog posts by popularity.

Collections Link

The two standard document types in Jekyll are posts (for blog content) and pages (for static pages). The launch of Jekyll 2.0 brought collections52, which allow you to define your own document types. For example, you could use a collection to define a photo album, book or portfolio.

Conclusion Link

Jekyll isn’t for every project. The biggest disadvantage of a static website generator is that incorporating dynamic server-side functionality becomes difficult. The number of services to integrate, like Disqus, is growing, but not all offer much flexibility or control. Jekyll isn’t suited to building user-based websites because there is no database or server-side logic to handle user registration or logging in.

Jekyll’s strength is its simplicity and minimalism, giving you just what you need to create a content-focused website that doesn’t need much dynamic user interaction — and no more. This makes it perfect for your blog and portfolio and also worth considering for a simple client website.

Don’t let Jekyll’s reputation as a blogging platform for hackers dissuade you. Building a beautiful, fast, minimal website in Jekyll doesn’t require elite hacker skills or knowledge of the command line. As shown in the walkthrough, you can get set up in a matter of minutes, giving you more time to spend on your content and design.

Further Resources Link

  • Jekyll53
    The official website is the best resource for theming Jekyll and creating a website. A lot of the information in this article was drawn from it.
  • Jekyll Now54291913
    This starting point makes it easier to create a Jekyll blog by eliminating a lot of the up-front setting up.
  • Jekyll source code55
    The Jekyll repository shares the source code and discussions about Jekyll.

(al, ml)

Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30
  31. 31
  32. 32
  33. 33
  34. 34
  35. 35
  36. 36
  37. 37
  38. 38
  39. 39
  40. 40
  41. 41
  42. 42
  43. 43
  44. 44
  45. 45
  46. 46
  47. 47
  48. 48
  49. 49
  50. 50
  51. 51
  52. 52
  53. 53
  54. 54
  55. 55

↑ Back to top Tweet itShare on Facebook

Barry Clark is a web developer living in Brooklyn, NY. He works as a hands-on Technical Director for in Manhattan. He loves working on projects that help fellow web developers save time, recently creating Jekyll Now and Bashstrap. In past lives Barry coded video games for Rockstar and traveled the world as a professional poker player. He’s writes a free newsletter on getting hired as a web developer.

  1. 1

    Nice! :D I really like where this github page thing going! i’ve created a small lib to use github pages for error-tracking for your android app ( So there are actually a lot of possibilities :)

  2. 2

    Barry is god web developer
    Also SECOND!

  3. 3

    Michael Rose

    August 1, 2014 3:18 pm

    Really enjoying the built-in Sass support Jekyll recently added. As someone who has opensourced a few themes it’s a great addition.

    For non-devs who wanted to make some minor cosmetic changes to fonts and colors it was a big hurdle to overcome trying to modify the theme’s CSS. Now they just edit a few variables and Jekyll takes care of all the preprocessing at site build.

  4. 7

    I really enjoyed this post. I wish I had it when I started with Jekyll as it is a great getting started guide. I wanted your readers to know that well Jekyll is a good system, and certainly the most popular, there are many other static site generators out there. I started with Jekyll, but was frustrated with it’s dependence on all things Ruby and how long it took to render my blog with a few dozen posts. I found Hugo ( and never looked back. Very similar to Jekyll in usage, but I found it better for me. For one, installation couldn’t be easier. Just download a single program file. No package managers to setup and use. I also love how fast Hugo is. Jekyll took minutes to render my blog, while Hugo does it in under 1 second. One thing that Jekyll does well is github pages integration. I was happy to discover that Hugo’s integration with github pages is rock solid.

    • 8

      Glad you enjoyed the post, John.

      Great point on there being a number of options with static site generators. This list is a great resource for seeing which are the most popular:

  5. 9

    Vlad Dumitrescu

    August 1, 2014 3:30 pm

    A way to ease up the problems with managing dependencies and build locally the same way as GitHub does is to install the github-pages gem (, that sets up the right environment with all supported plugins.

    • 10

      Really good point, Vlad. I’ll submit an edit this weekend to include that in the article.

  6. 11

    This is very informative article.

  7. 12

    Jeseph Meyers

    August 1, 2014 7:40 pm

    Great guide, I’ve become increasingly curious about dynamic sites built with static pages. This might be the motivation that I need to get started (at least for a personal project). One thing holding me back that I can’t seem to get over is the absence of the SEO plugins I’ve come to love. Either way, thank you!

    • 13

      What are your favorite SEO plug-ins, Jeseph?

      I don’t do any type of SEO analysis on posts, now I’m wondering if I should be ;)

  8. 14

    Great tutorial on how to build static blogs. Recently i worked with projects like [DocPad](, which is a cool static website generator, but Jekyll is much simpler than that! And i started to build my own blog in *GitHub* pages thanks to you :)

  9. 17

    Moritz »mo.« Sauer

    August 1, 2014 10:24 pm

    I use Jekyll mainly to build my own little websites for clients who don’t need a CMS. One of the best things for web developers is how you can optimize websites while using Jekyll. For example just check out Compress HTML-Template by Anatol Broder ›

    Within two minutes, you minify all HTML-docs Jekyll builds. Or check out the excellent image plugins by Rob Wierzbowski. With Minimagick and Imagemagick installed on your machine, you resize your images and it’s ALL FREE OPEN SOURCE software.

    Jekyll Image Tag

    Jekyll Picture Tag

    And to finish everything, you let gulp do the rest.

    I just love static website generators.

  10. 18

    Wow, this is what I am looking into now. Great post!

  11. 19

    Brett Jankord

    August 2, 2014 1:51 pm

    Great write-up Barry, this was the nudge I needed to get more familiar with Jekyll.

  12. 20

    Jonas Ohlsson

    August 2, 2014 9:06 pm

    This is great! I’ve been wanting to move my wordpress blog over for a while – this will help a lot, thanks!

  13. 21

    Alberto Apure

    August 3, 2014 5:44 am

    Thanks Barry. With your column and repository it was really easy for me to
    setup a blog. I will learn more while customizing the site.
    Your instructions were great.

  14. 22

    This is a great option for the blog, I have used many times for micro sites. Hyde is good to start theme for jekyll. Only issue is composing article is little messy.

  15. 24

    Ahmad Colapietro

    August 4, 2014 11:57 am

    I enjoyed reading this a lot

  16. 25

    Thanks Barry! Everything’s clear!
    I’d just need some additional helps with scss … Now my scss folder includes my style.scss with all the imports and 2 other folders: BOOTSTRAP folder with all the partials, and CUSTOM folder which contains other folders with my custom partials (modules, layout, vendors, states).
    How should I set the _config.yml in this case?
    Thank you!

    • 26

      It’d be great to take a quick look at your project if you’re still need additional help with this, Francesca.

      Shoot me an email with a link to your GitHub repository? My email address is on the footer of

  17. 27

    Saleh Hamadeh

    August 5, 2014 1:14 pm

    Great article. Jekyll itself could not explain itself that well. One thing that I would like to hear you talk about is making a static blog social. In my blog, I use Disqus for comments, Mailchimp for mailing lists, and AddThis for sharing content. I wrote this article about the social stack that I use

    I am constantly trying to find ways to make blogs socially engaging. If you have any ideas, please share them.

  18. 28

    Middleman is far superior and also has great support for github pages.

  19. 29

    Unfortunately this doesn’t work as well for projects hosted at bitbucket. Hopefully they’ll add support for Jekyll.

  20. 30

    Hi Barry,

    Thanks so much. This is great. I’m trying to set up a personal site that has a blog, but where the blog is not the landing page for the main url. Is there a quick make it such that the main url, go to a static page and not to blog posts?

    • 31

      Hey. I figured out the static page, but I’m now having trouble with Disqus. I put in my short name, and I see Disqus trying to load, but it says there is an error. Any idea what might be going on?

      • 32

        I could take a quick look at your code if you’re still need a hand with this, Alex.

        Shoot me an email with a link to your GitHub repository? My email address is on the footer of

  21. 33

    I wonder if there is anything like Adaptive Images ( to make your blog images responsive in these static blogs? I think there are also some JavaScript solutions but I don’t like to load a ton of scripts, and that would invalidate the point of faster loading. If a lot of scripts have to be requested, then the page stops being fast loaded even if it is static.

  22. 34

    Daniel Peukert

    August 21, 2014 3:14 pm

    thanks very much for the repo, because I really didn’t want to mess with installing Jekyll on Windows. Now onto my question, the JekyllNow repo should continue to work with future version of Jekyll, right? (excluding things like if they change the syntax of _config.yml of course).


  23. 35

    Excellent writing! Thank you very much for sharing it!
    Within very short time, followed your blog, I could set up my blog site and wrote my first blog in Github:

    One question:

    Why you don’t use Disqus as your commenting tool?

    Thanks again


  24. 36

    I’m curious – if I already have a github page setup at, how would I replace those pages with Jekyll? I’m sorry if this is a basic question, but I’m confused.

  25. 37

    Excellent article, Thanks for writing

  26. 38

    Thanks for the article. I am wondering how I can add my own images in /image/ directory? Its not allowing me to. Can you please help me here?

  27. 39

    Migrating from WordPress to Jekyll is something I rather admire!

    For those who are on Macs and just want to do a bit of testing, and do a local build of Jekyll. I whipped up an easy guide on the steps to get it quickly up and running.

    Much thanks Barry.

  28. 40

    Thanks for the article, I managed to get a page up at Github very easily. I have a question though, you list several themes which are compatible, however you point to what appears to be the standard setup. This in turn makes me think we are effectively starting from scratch when we want to change themes. Is there a way to change without starting over?

  29. 41

    That’s awesome!

    BTW, which screenshot app you use to get the animated gif?

  30. 42

    William Denman

    October 30, 2014 10:50 pm

    Really awesome article, well written and very easy to follow.

  31. 43

    is it possible to add custom plugins to ur gh-pages jekyll website ? I specifically want to use youtube plugin.

  32. 44

    In my Jekyll _config.yml file i have future: false. Do you know if Github Pages will show my new future posts based on current date?

  33. 45

    Auxiliujm Technology

    December 6, 2014 7:15 am

    At Auxilium Technology, we design products and services to meet your enterprise needs, and our services are aligned with developing a flawless business strategy and achieving your business goals.

  34. 46

    So I simply decided to move on and to move my blog Github pages. I tried to go through the setup of Github pages with Octopress, but it was quite a pain to get a exact code..

  35. 47

    Hi Barry!

    First off, great post! I followed your guide, however, I cloned your repo, changed the branch name to gh-pages and then pushed it my remote repo. However, for some reason not everything is rendering. Only some text and the image is rendering. What could be the issue? You can the result here:

    Thanks a lot for your time!

  36. 48

    Great article! Thanks. Ever tried Jekyll to build my personal website.

  37. 49

    Chyngyz Arystan uulu

    January 18, 2015 10:50 am

    Thanks! Great post on Jekyll ever! +fork for Jekyll Now

  38. 50

    This post was really helpful, thank you.

  39. 51

    Failed on step 2, already: confused WHERE to exactly modify (there’re >2 “Settings” buttons and symbols ) which field, to make to work, finally.
    “in the menue on the right” does not help – a picture would be better.

  40. 52

    Do we have to update sitemaps manually or will i be update automatically. I had to manually update my mongo db blog sitemap with a sitemap software like Creately

  41. 53

    Valerio Pierbattista

    March 30, 2015 10:01 am

    if you are interested in adding `grunt` to the mix, i’ve created a boilerplate that could be useful for more design oriented jekyll site/blogs:

  42. 54

    I love the idea, but it seems like permalinks are broken for posts? ( )

    I’d appreciate any workaround you folks have found since what’s actually happening in the GitHub pages/jekyll stuff seems to be opaque to the user unless I’ve missed something.

  43. 55

    Daniel Keith

    April 16, 2015 7:57 am

    Nice article. I was using Weebly before this. My experience was good. Now I am planning to try Jekyll. Hope it will be like as it has defined above.

  44. 56

    Great info. Lucky me I came across your website by accident (stumbleupon). I’ve book-marked it for later!

  45. 57

    Thank you for this guide, it’s been really useful! But I have an issue, forked Jeykll Now as you recommended but my posts all include a “Read More” link after only a single line of text from each post. Could you advise?

  46. 58

    Thanks for the detailed steps. If you’re interested in moving off GitHub pages for improved performance and control check out Simple websites with Jekyll and Docker. At the outset users will have their own hosted Jekyll site running under Docker with Passenger, hosted in the cloud.

  47. 59

    Thanks for your jekyll template, it should save me a lot of time. I’m having an issue you may have seen before: I created my GitHub site (as a project page, not user) and simply copied the files from your repo into it. The site “built” and is visible at , but it does not seem like ant CS=S (or other elements) are applied. I’m a newbie, did I miss something ?

    • 60

      Just got it working, had to update the baseurl in your config file.

      Thanks :)

  48. 61

    Is it possible to change the theme?

    I would like to use this one:

    But I’m afraid to break the Jekyll Now


↑ Back to top