Installation


How to use Beautiful Jekyll

Beautiful Jekyll is a ready-to-use template to help you create a beautiful website quickly. Perfect for personal sites, blogs, or simple project websites.

There are a few different ways to build a website using Beautiful Jekyll, and for most people (including myself!) I recommend the method outlined in the official documentation.


Advanced installation methods

The following installation methods are not recommended for beginners!


Method 1: GitHub repository with remote_theme

Beautiful Jekyll was initially developed as a GitHub Pages theme that was meant to be used via forking, but several years later GitHub released the remote themes feature that allows you to use a theme on any GitHub repository. For full details, you should read GitHub’s documentation on remote themes, but here is a summary of the steps required:

  • Create a new GitHub repository (or go to an existing repository)
  • Add remote_theme: daattali/beautiful-jekyll@6.0.1 to your _config.yml file (remove any previous theme or remote_theme parameters that may have been there before)
  • Go to Settings, click on the Pages tab on the left side, select “master” (or “main”) in the Branch section, and click Save.
  • Your website will be at https://YOURUSERNAME.github.io/REPOSITORY

Make sure to read the post-installation setup instructions as well.

Method 2: Ruby and jekyll gem

Due to high demand, you can also use this theme when creating jekyll websites locally with Ruby.

If you choose this method, you will not get any support. You’re expected to know Ruby and be able to debug any issues on your own.

  • Make sure you have Ruby installed (e.g. sudo apt install ruby-full build-essential zlib1g-dev)
  • Install the jekyll gem (e.g. sudo gem install jekyll bundler)
  • Create a new jekyll site (e.g. jekyll new mysite)

Once you have your jekyll site ready, you can choose to either use the remote theme gem or to use the beautiful-jekyll gem. Choose one of the following two options:

  • Option 1: Using the beautiful-jekyll gem:
    • Add gem "beautiful-jekyll-theme", "6.0.1" to your Gemfile
    • Add theme: beautiful-jekyll-theme to your _config.yml (remove any previous theme or remote_theme parameters that may have been there before)
  • Option 2: Using the remote theme gem:
    • Add gem "jekyll-remote-theme" to your Gemfile
    • Add remote_theme: daattali/beautiful-jekyll@6.0.1 to your _config.yml file (remove any previous theme or remote_theme parameters that may have been there before)
    • Add - jekyll-remote-theme to the plugins section of your _config.yml file to activate the plugin

After these modifications, run bundle install. You can preview your site by running bundle exec jekyll serve -H <IP ADDRESS>.

Make sure to read the post-installation setup instructions as well.

Post-installation setup

When you use Beautiful Jekyll with the “easy way” (forking on GitHub), you’ll have direct access to all the theme’s files because you’ll be literally copying the entire project. But if you use one of the methods on this page, many of the theme’s files and folders will be hidden from you, so you’ll need to:

  • Go through Beautiful Jekyll’s _config.yml file and copy any settings you want to use into your project’s config file.
  • Some config features will not work immediately because of missing files that you’ll need to copy from Beautiful Jekyll into your project:
  • If you want the home page to include a feed of all blog posts, create an index.html file and use layout: home in its YAML.

If at any point in the future you want to update to a newer version of Beautifu Jekyll, you can simply update the remote_theme or gem fields accordingly.

After setting up your site, you should still go through the rest of the Beautiful Jekyll documentation to learn about all its features and how to use them.