Build A Blog With Jekyll And GitHub Pages

Installation and configuration

Without going into every detail, here’s an overview and helpful references of the process.

Install Ruby, RubyGems, Jekyll and Bundler.
- For Windows
- For Mac
- Guides for Ubuntu and other linux distros are also available.
Start new Jekyll blog and and use Bundler to run a local test environment.
- Instructions
Create a new private Github repository.
Go to Settings and Pages of your repository.
Select Github Actions as Source in the drop-down under Build and deployment, and chose Github Actions Jekyll.
Push your local folder to your new repository using Git CLI or Github Desktop.
Github will run Actions for Jekyll and deploy your website to Pages.
Configure your domain:
- Go to your Github profile settings, click Pages and add your domain.
- Verify domain ownership by adding a TXT-record in the DNS settings of your domain registrar.
- Create A-records and point them to IP addresses for GitHub Pages.
- Point a WWW CNAME to your Github Pages default domain - [username].github.io.
- Get a coffee to let DNS propagate, and verify your DNS setting in Github Pages settings.
Customize and start blogging!

Customization

Change Default Jekyll Theme

Documentation on themes + theme libraries

Here’s an example of a Jekyll theme you can install: Minimal

I replaced the whole CSS to develop my own theme.

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/

Documentation on permalinks

Display Blog Posts On Homepage

I wanted to display blog posts on the homepage, so I added a 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 (li) in the list (ul).

<ul>
{% for post in site.posts %}
    <li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>

You have many options to add conditions here.

Documentation on Liquid

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>

Documentation from Mermaid

Other Tips

Add a jekyll sitemap generator: Jekyll-Sitemap Gem
Always open Markdown links in a new window: Jekyll-Target-Blank Gem

About