Let’s start from scratch on a macOS environment from the installation of ruby to actually running the theme. The jekyll theme that we will be running is Type-on-Strap. If you are on a different operating system and have issues check out the Jekyll docs. If you have an issue you can refer to Installation issue #57 or open a new one.
Dev tools dependencies
# Xcode is the macOS developer tool xcode-select --install # Check your version first brew -v Homebrew 3.0.8 Homebrew/homebrew-core (git revision 3f7c96754c; last commit 2021-03-22) Homebrew/homebrew-cask (git revision a0a9782687; last commit 2021-03-22)
You are now a developer! 😛 So now you have met the basic requirements, let’s go with the installation of Ruby.
So Mac comes with a ruby installed:
ruby -v ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]
However, we won’t be using it to avoid any weird issues. We’ll use
rbenv to install our own ruby version.
This way we will be able to select which ruby version by default we want to use in the terminal.
# Install rbenv and ruby-build brew install rbenv # Set up rbenv integration with your shell rbenv init # At the end of the previous command, you'll need to add that to your zshrc echo 'eval "$(rbenv init -)"' >> ~/.zshrc
Once you have initialized it you can now install and use your own version of Ruby:
rbenv install 2.7.2 rbenv global 2.7.2 ruby -v ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin19]
Yeah, this part is done! You can use the above command to install a different version of Ruby, but keep in mind that the theme might not be compatible with older version.
You can check the Ruby dependency of the gem at rubygems.org. There are also links for the documentation, issues and much more.
Install Bundler gem
We will use the gem bundler that is a gem manager that will allow us to install the ones we need for the jekyll theme. Just do:
gem install bundler
The other necessary gem will be installed through bundler.
Set up your Type-on-Strap theme
You don’t need much for it to work as a gem. Let’s create a new folder and add the necessary files. This is also to set up your folder structure to get started with Jekyll and blogging.
Here is the gemfile that list the gem dependencies that will be installed later.
source "https://rubygems.org" gem 'type-on-strap', ">= 2.3.3", "< 3.0"
You need at least the default config file in order for it to work
baseurl: "" theme: type-on-strap
Not that this is a very dry config, you may want to add the additional attributes for more customization. It will display very basic information with just that, however the theme might look a bit different, and the blog part will not work.
For type on strap, here are the basic customization attributes for your config file that you can add so that most of the basic feature will work:
# THEME-SPECIFIC CONFIGURATION title: "My blog" avatar: assets/img/avatar.png favicon: assets/favicon.ico header_text: Welcome to my blog! header_feature_image: assets/img/banner.jpeg # BLOG CONFIGURATION post_navigation: true paginate: 10 paginate_path: "blog/page:num" plugins: [jekyll-paginate, jekyll-seo-tag, jekyll-feed]
With that you should have some basic configuration.
jekyll-paginate plugin is validated by GitHub and is used by many jekyll theme out there, you definitely need it for your blog.
index.html is the root file, you will need to create one at the root.
In order for the file to be displayed add that into it:
--- layout: home ---
This will render the home layout which is usually the main layout for a gem jekyll theme.
Those are mostly optional depending on what you want to do with the theme:
- Create a
_postsfolder where you can put your blog articles
- Create an
_assetsfolder where you can add images or other static files for your posts
- If you want the pages shown in the Type-on-Strap demo site (About, Gallery, Portfolio, Search, Tags, Not found page 404),
you may want to copy the
pagesfolder in here.
- To customize the theme you can always refer to the documentation
Install your dependencies and run
Now that you have your theme set up following the above, and you have added either some customization or not. Your folder structure should be similar to that:
. ├── Gemfile ├── _config.yml ├── _posts │ └── 2021-03-24-Example-blog-post.md ├── assets │ ├── favicon.ico │ └── img │ ├── avatar.png │ └── banner.jpeg ├── index.html └── pages ├── search.md └── tags.md
Go in the root of your theme folder and install the dependencies using:
Everything necessary for the theme will be installed (mainly jekyll and its dependencies for Type-on-Strap).
Gemfile.lock will be created to track the version of the installed gems.
Then you can start running the theme using:
bundle exec jekyll serve
The theme should be available and running at localhost:4000.
The theme is built in a
_site folder that is generated automatically.
You can also ignore the
.jekyll-cache folder which is used by jekyll.
When running locally you may encounter this error:
`bind': Address already in use - bind(2) for 127.0.0.1:4000 (Errno::EADDRINUSE)
That means you may have run another application on port 4000 already, or the blog may be already running from another terminal, and you can’t re-run it because the port 4000 is already taken.
In this case you can kill whatever is running on port
4000 (on MacOS) with:
lsof -t -i tcp:4000 | xargs kill -9
or you can specify another port using:
bundle exec jekyll serve --port 2000
So your application will run on
127.0.0.1:2000, you could also change the host with
--host 0.0.0.0 when running
inside a docker for example.
Even though we talked about this specific theme, most gem based jekyll theme should work fairly the same. This was the most default settings. Some theme might add some more folders or pages or extra customizable stuff, so make sure you check out the doc.
Finally, if you want your theme to work the same locally and on GitHub-page, you can use the
This way the theme will be built correctly on GitHub-page as well, using directly the Type-on-Strap repository as a base like the gem would do with
You can have both too, but you may receive a warning from GitHub Page if you have
theme saying that it’s not recognized as GitHub by default refuse all external gems.
That warning can be discarded.