Jekyll Gotchas and Solutions: A Personal Reference

technical

A personal reference for Jekyll setup issues and solutions. Consider it a note to future self.

Jekyll Setup Reference

This is my personal reference for Jekyll setup issues and solutions I’ve encountered. Consider it a “note to future self.”

Directory Structure

my-blog/
├── _posts/             # Blog posts
├── _drafts/           # Draft posts (no date in filename needed)
├── _includes/         # Reusable components
│   └── head.html      # <head> section, includes MathJax
├── _layouts/          # Template files
├── assets/            # Static files
│   └── images/        # Image files
├── public/            # Theme assets
│   ├── css/          # CSS files
│   └── js/           # JavaScript files
└── _config.yml       # Site configuration

MathJax Setup

Where to Put MathJax Configuration

The MathJax configuration goes in _includes/head.html. Here’s my working setup:

<!-- MathJax Configuration -->
<script>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']],
      macros: {
        vec: ['{\\mathbf{#1}}', 1],
        RR: ['{\\mathbb{R}^{#1}}', 1],
      }
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>
<script id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
</script>

Math Display Tips

  1. The Colon Issue: Always add empty lines before and after display math blocks. This won’t work:
Here's a formula:
$$ f(x) = x^2 $$

Instead, use empty lines:

Here's a formula:

$$ f(x) = x^2 $$
  1. Local Macro Definitions: You can define macros locally in a post:
$\gdef\newmacro{\mathcal{N}}$

Images in Jekyll

Including Images

Basic markdown syntax:

![Alt text](/assets/images/post-specific-folder/image.png)

For centered images with captions (flexible, inline styling):

<div style="display: flex; flex-direction: column; align-items: center; margin: 50px auto; max-width: 800px;">
    <img src="assets/images/post-specific-folder/image.png"
         alt="Alt text"
         width="600" />
    <span style="font-style: italic; font-size: 14px; color: grey; margin-top: 10px;">
        Image caption here
    </span>
</div>

Image Best Practices

Front Matter Reference

Common front matter options:

---
layout: post
title: "Your Post Title"
date: 2024-11-18
categories: [category1, category2]
tags: [tag1, tag2]
excerpt: "Custom excerpt for the post"
permalink: "/custom-url.html"
---

Local Development

Common commands:

# Serve locally with draft posts and live reloading (local)
bundle exec jekyll serve --drafts --livereload

# Build site
bundle exec jekyll build

# Update dependencies
bundle update

Theme Customization

Important Files and Directories

Custom text boxes

Every non lanyon style goes in public/css/custom.css. For example this is how we style a definition block:

.definition{
    margin: 1em 0;
    padding: 1em;
    border-left: 0px solid #33c17a;
    background-color: #f8f9fa;
}

Draft Posts

Font Customization

Method 1: Modify Google Fonts in head.html

In _includes/head.html, find and modify the Google Fonts link:

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=PT+Serif:400,400italic,700%7CPT+Sans:400">

Method 2: Update CSS Variables

In public/css/lanyon.css, find and modify these sections:

/* Default font settings */
html {
  font-family: "PT Serif", Georgia, "Times New Roman", serif;
}

/* Headings */
h1, h2, h3, h4, h5, h6 {
  font-family: "PT Sans", Helvetica, Arial, sans-serif;
  font-weight: 400;
  color: #313131;
  letter-spacing: -.025rem;
}

Some tested combinations:

Tips

← All posts