Build A Blog With Jekyll And GitHub Pages

07 Jul 2023technical

Table Of Contents

Benefits

  • Free hosting.
  • Fast and responsive static sites.
  • Jekyll is using Liquid templating, which is a fairly easy language to grasp and very customizable.
  • Markdown support comes pre-installed with Jekyll (kramdown).

Limitations

Running Jekyll on Github Pages will limit website functionality to features you can build with HTML, CSS and Javascript. If you need complex functionality like server-side functions, you either need to use a different hosting service or use an external service that provides the required back-end.

Installation and configuration

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

  • Install Ruby, RubyGems, Jekyll and Bundler.
  • Start new Jekyll blog and and use Bundler to run a local test environment.
  • 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.

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

Similar posts