Jekyll Blog Setup

I started exploring new blogging systems, and I came across Jekyll.

The Jekyll blog system is a blogging platform written in Ruby on Rails. You just need to know how to run some commands in your terminal. A little knowledge of git and ssh would also be good

The reason I like the Jekyll blog system using the chirpy theme is because I can write content in markdown.

Jekyll blog setup cheatsheet

Setup blog locally

1. Clone project from jekyll chirpy theme
2. Run bundle command to install dependencies

Jekyll serve

jekyll serve: This command does the same as jekyll build (generating files in the _site directory), but it also starts a local development server at http://localhost:4000. The serve command is helpful when you want to preview changes in real-time because it automatically rebuilds and refreshes the site as you edit files.

Serve site to view it locally

The Jekyll blog site is for local editing only. You create your posts locally, edit them, then there is a build process which will generate all your HTML files. Then you deploy your HTML files to a web-server.

Project root

Run all the commands from your project root

rvm use 3.2.2 --default

Ruby Version management

Ensure you are using a compatible version of ruby. If you encounter any errors, you might be using the wrong version of ruby. we can fix that with rvm. Ruby Version Manager.

rvm use 3.2.2 --default

Start up the local environment

Ensure you run the jekyll build and serve commands from your project root.

cd /your-project-root

bundle exec jekyll s --livereload

Create new post (with jekyll compose)

bundle exec jekyll post "My New Post"

Jekyll build

So this is the build process where your markdown files are generated into HTML.

jekyll build: This command generates the static files for your site in the _site directory without starting a local server. You use jekyll build when you want to generate the site’s files for deployment or review but don’t need to see it live in a local environment.

bundle exec jekyll b

set environment before build

JEKYLL_ENV=production bundle exec jekyll b

Deployment

You can use rsync to deploy the site using a custom sshconfig file entry. By combining the Jekyll build function with the deploy function.

Deploy your site directory

cd _site/

   rsync -av * example_ssh_config:/var/www/dynamitefrog.com

Better yet. Stay out of your _site/ directory because there is no good reason to go in there at all. Furthermore, weird stuff will happen if you start running server and build commands from your _site directory.

rsync -av --delete _site/ example_ssh_config:/var/www/dynamitefrog.com

Create an SSH config file

Rsync works by connecting to your server through SSH. But once again, it’s easier to create sshconfig file to handle your SSH connections.

See ssh config file creation

Customize site settings

The primary settings on your site can be customised in the config.yml.

This is where you can edit your site name, Social Media profiles, colour scheme, etc. Now, after updating your config file you must restart your Jekyll website and to refresh the your local site and see the changes. You can stop your Jekyll serve command by hitting control c on your keyboard.

Deploy to github pages

If you’re not hosting on your own server, then you may wish to deploy to github pages. GitHub pages is free and is also written in Ruby on rails.

git add -A
git commit -m "commit message"
git push

Front Matter

In Jekyll (and other static site generators), front matter is a block of metadata at the beginning of a file, written in YAML or JSON format, that provides settings and variables for that file. This information allows Jekyll to manage data associated with each page or post, such as titles, dates, layouts, custom variables, and more. Front Matter Syntax

Front matter is written between two sets of triple dashes (—) at the very top of a markdown or HTML file:

---
title: "My First Blog Post"
date: 2024-01-01
layout: post
author: "John Doe"
categories: [blog, personal]
tags: [introduction, welcome]
custom_variable: "Some custom content"
---

In this example:

title: Sets the title for the post. date: Specifies the date the post was created, which Jekyll uses to organize posts chronologically. layout: Defines which layout file to use from the _layouts directory (e.g., post.html). author, categories, tags: These are common metadata fields used in templates, filters, and organization. custom_variable: You can add any custom key-value pairs here, which can be accessed by your Jekyll templates or custom tags.

Why Use Front Matter?

Front matter makes it easy to manage and organize content because Jekyll reads these values and allows you to reference them dynamically within templates and pages. You can access front matter variables directly in Liquid code, like so:

<h1>{{ page.title }}</h1>
<p>Written by {{ page.author }} on {{ page.date }}</p>

Practical Uses

Set Layouts and Design Elements: You can assign different layouts or designs to different types of pages or posts. Organize Content: Using categories and tags helps structure and filter content on a blog or portfolio. Add Custom Metadata: Custom variables allow you to add anything you want, such as descriptions, extra data fields, or unique identifiers, making your content more flexible.

Common Front Matter Fields in Jekyll

title: The title of the post/page. date: Publication date, typically for posts. layout: Specifies which layout file to use. permalink: Defines a custom URL path. tags, categories: Organizes posts into tags and categories. published: Controls if a post is published (set to false to hide).

Front matter is essential for controlling how Jekyll interprets and displays content, allowing for flexible, organized, and customizable page management.

Hide post from published

published: false

Allow liquid

When you try to serve your jekyll website you might encounter an error. Liquid Warning: Liquid syntax error This is because you’ve probably got a liquid or twig code snippet within your post.

All you need to fix this is to add that magic peice of front matter to allow you to render liquid and twig code on your posts:

render_with_liquid: false

Use a custom canonical

By default the canonical will be self referencing. You can override it with the follow front matter.

canonical_url: 'https://github.com/jekyll/jekyll-seo-tag/'

Use Mermaid

mermaid: true

Inspect liquid variables

{{ post | inspect }}

Compile SCSS to CSS

This is built in to Chirpy. Just running the serve command will watch and compile css to scss

bundle exec jekyll s

Create a custom Jekyll markdown tag

To create a custom tag in Jekyll where the value is set through the front matter of a post or page, you can modify the render method of the custom tag to access the front matter variables. Here’s how:

Step 1: Create the Custom Tag File

Go to your _plugins folder (create it if it doesn’t exist) and create a new Ruby file, like front_matter_tag.rb.

Step 2: Define the Custom Tag

In the new file, define your custom tag to pull a value from the front matter. Here’s an example:

module Jekyll
  class FrontMatterTag < Liquid::Tag
    def initialize(tag_name, text, tokens)
      super
      @key = text.strip # Get the front matter key from the tag
    end

    def render(context)
      # Access the front matter data
      page_data = context.registers[:page]
      # Get the value associated with the key from the front matter
      value = page_data[@key]

      # Render the output, or a default message if the value is not set
      if value
        "<div class='front-matter-value'>#{value}</div>"
      else
        "<div class='front-matter-value'>No value set for #{@key}</div>"
      end
    end
  end
end

Liquid::Template.register_tag('frontmatter', Jekyll::FrontMatterTag)

Explanation of the Code

@key: Stores the key you specify in the tag. context.registers[:page]: Accesses the current page or post’s front matter data. value = page_data[@key]: Gets the value associated with the key you defined in the front matter.

Step 3: Use the Custom Tag in Your Markdown Files

In the front matter of your markdown file, set the value for your custom key. For example:

---
title: My Blog Post
custom_value: This is a custom message from front matter.
---

In the content of your markdown file, use the tag with the front matter key:

{% frontmatter custom_value %}

Example Output With the example code, the output would look like this:

<div class='front-matter-value'>This is a custom message from front matter.</div>

If custom_value isn’t set in the front matter, it would output:

<div class='front-matter-value'>No value set for custom_value</div>

This setup allows you to use front matter values dynamically in your Jekyll posts and pages, making it easy to manage reusable content directly through your front matter.

Troubleshooting

Canonical is set to localhost

Build your site using the production environment variable should fix it

JEKYLL_ENV=production bundle exec jekyll b

Serve process wont start because its already running.

Find the process id to kill and kill it. kill running process

Once you have killed that old process you can run the s serve process again.

Missing home.min.js

npm install
npm run build

If you get an error saying jekyll post, not found you **may** need to install this missing gem. I found to fix this you need to re-install jekyll compose and add it to my gem file.

add code to your Gem File

gem 'jekyll-compose', group: [:jekyll_plugins]

Jekyll process still running

Sometimes a previous jekyll serve process can still be running. and you need to find it and stop it to run a new process.

Find the process id

ps -e | grep "ruby"

Kill process

Add the -9 to force kill

kill -9 123

More Resources

1. https://youtu.be/F8iOU1ci19Q
2. https://github.com/cotes2020/jekyll-theme-chirpy
3. https://jekyllrb.com/docs/step-by-step/01-setup/