Build A Blog With Jekyll And GitHub Pages
Table Of Contents
Benefits Of Jekyll
- Markdown support comes pre-installed (kramdown).
- Easy deployment and maintenance with GitHub Pages.
- Easily customizable with liquid templates.
- Low complexity and fast rendering.
Installation And Setup
Install Jekyll on Windows
- Install RubyInstaller for Windows.
- Install Jekyll and Bundler using gem install jekyll bundler.
- Verify the installation with the jekyll -v command.
- Run jekyll new blogname to create a Jekyll boilerplate.
- From the new blog folder, run the bundle exec jekyll serve command.
- Click the address printed, or access your blog on http://localhost:4000.
Deploy Jekyll on GitHub Pages
- Create a dedicated repository for your website on GitHub.
- Go to Settings from the repository and click Pages.
- Select GitHub Actions as source, and select GitHub Pages Jekyll.
- Click commit changes. GitHub will generate a Workflow that will trigger when you push new code to your repository.
- Use Git CLI og GitHub desktop to push your local Jekyll deployment to your new repository, and watch the GitHub Action automatically trigger and complete the deployment.
- Your initial domain will be username.github.io/repository. I pointed my own domain to GitHub Pages using A records and the IP addresses defined here.
- Remember to verify ownership of your own domain under Pages in your personal profile settings.
Customization
Change Default Jekyll Theme
I wanted to change the default Jekyll to something closer to what I wanted, and decided to use Minimal.
- Here’s the theme I used: Minimal
The separate SCSS-file is to keep all your custom properties separate from the base theme, so you retain modality. All properties in this file will overwrite the theme sheet, because they will be applied last when files are merged.
Change Default Jekyll Permalinks
The default permalinks in Jekyll uses the following format by default:
/:categories/:year/:month/:day/:title:output_ext
I wanted to simplify, so I added the following to _config.yaml:
permalink: /:title/
Display Blog Posts On Homepage
I wanted to display blog posts on the homepage, so I added the liquid post loop to the index file. You can do something like this to render every post in your _posts folder as a title link. Each post get an entry in the list.
<ul>
{% for post in site.posts %}
<li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
Add Mermaid Support To Jekyll
I wanted to add support for using Mermaid charts in Markdown, I so added the following to the head of the HTML template:
<script type="text/javascript" src="https://unpkg.com/mermaid@10.2.4/dist/mermaid.min.js"></script>
Add the initializing script at bottom of the body, before the closing body tag:
<script>mermaid.initialize({startOnLoad:true});</script>
Now, Mermaid syntax gets rendered when written inside the following element:
<div class="mermaid"></div>
Other Tips
- Add a jekyll sitemap generator: Jekyll-Sitemap Gem
- Always open Markdown links in a new window: Jekyll-Target-Blank Gem