I want to make my own theme with Jekylll

I want to make my own theme with Jekylll but I can’t change anything because of config.yml settings. How can I make my own theme from scratch?


The very first step is deciding two things:

  • Is the theme intended to be used only on one site or have it available for use by multiple sites or for public consumption.
  • Is your site going to be built by GitHub Pages (which uses Jekyll with restrictions) or by yourselves using Jekyll directly.

If the theme is intended for single use only, the process is less cumbersome.
Refer Setup | Jekyll • Simple, blog-aware, static sites and complete all steps.

The process is better if you’re starting with a blank site altogether but if you are with a directory containing (your own) existing posts and pages or some third-party pages:

  • First delete any mention of theme or remote_theme from your config file.
  • Now instruct Jekyll to build your site. If it succeeds without any hard errors, you’re good to start creating a theme from scratch. There may be some warnings about missing layouts, you may ignore that for now. However, if there was an error regarding Liquid tags, you’d need to go to the file concerned and remove the offending tags. Repeat until you get a successful Jekyll build.

Here on, the steps are similar to the tutorial…

  • For learning purposes, delete everything in your config file and just have the following:
    title: My Blog
  • The first step to theme-ing in Jekyll is to create a layout. Open your index.md or index.html file. Does it have layout: <some name> in the front matter? If yes, create an empty HTML file of that name in a _layouts directory.
    For example, if was layout: home, create _layouts/home.html.
    If not, add or edit to have layout: home in the block enclosed by triple dashes. This block of content is known as front matter.
  • Add <p>Welcome to {{ site.title }}</p> to the layout file you just created.
  • Start Jekyll’s dev server by running jekyll serve --livereload
    (or bundle exec jekyll serve --livereload if there’s a Gemfile.)
  • Point your browser to the address printed in the terminal. You should now see the welcome message from your layout in the home page.
  • Now add Hello {{ page.author }} to your index file after the front matter block. Once the file is saved, Jekyll will automatically regenerate the site and refresh your browser window.
  • Don’t panic because you don’t see the greeting in the browser. The reason is because the home layout hasn’t accepted the index file’s contents yet. Edit the _layouts/home.html file to contain {{ content }} in the line above <p>Welcome to {{ site.title }}</p>.
  • Save your layout file and see a greeting render in your browser.
  • Go back to the index file and add author: Jane Doe to the front matter. Save the file and see the complete greeting render on your blog’s home page.

You’ve successfully learnt to start the dev process of a Jekyll site.
To proceed and refine remember to refer Setup | Jekyll • Simple, blog-aware, static sites


There is a command to set up a new theme

Use global install of Jekyll or Jekyll in an existing project and target a directory for your new project

$ jekyll new-theme my-site-name

You are also welcome to click the Use this Template button on my repo, which is based on the output of the command above.

That includes docs to help you, it uses Jekyll 3.

…and it works as a demo site on GH Pages.


I’ve set up a minimal site on gh-pages branch which deploys from the code on master. In practice this would usually be a separate repo pulling in the theme from another repo.

Here documentation there will you with configuration

1 Like

Someday I’d like to make my own theme from scratch too. Therefore I find your question quite interesting. However, I found just using someone else’s theme and modifying it a few times more than enough education for a month!

Another consideration is there are a limited amount of GitHub Pages approved Jekyll Themes and getting added to that list might prove difficult. Still you can quite easily copy someone else’s theme and modify it so much that it becomes your own.

That said I like the thought of using Jekyll’s Cayman Theme because they do all the heavy lifting to ensure compatibility with different screen sizes, devices and browser manufacturers / versions. Or at least their thousand lines of code suggest that to me.

Users with problems on the Cayman Theme means they get it fixed and I get to benefit from it. I add my own styling to my website with navigation bars, table of contents, copy code to clipboard and custom front matter. So in the end it almost IS my own theme.

Good luck with your theme! Thanks for asking this question so I can follow the answers posted here :slight_smile:

You don’t have to get onto the list of supported themes.

If you use the Remote Theme plugin which is built into the environment, you can use any theme which is a public repo.

remote_theme: username/repo-name

There are a ton of themes to choose from and you can pick one as a starting point if you like the look and want different colors or your own menu or whatever.