Skip to content

README.md

Latest commit

 

History

History
166 lines (121 loc) · 4.68 KB

README.md

File metadata and controls

166 lines (121 loc) · 4.68 KB

Jekyll Tools

This repository contains a collection of tools to assist with managing Jekyll projects. These tools are designed to automate one-off tasks when working with Jekyll sites; generally when migrating or making changes to site layout.

Prerequisites

  • Python 3.6 or higher

Setup

  1. Clone or download this repository to your local machine.

  2. Ensure you have Python installed on your system.

  3. Run the provided setup.sh script to set up a virtual environment and install dependencies:

    ./setup.sh

    This script will:

    • Create a virtual environment in the venv directory.
    • Install the required dependencies inside the virtual environment.

  4. Activate the virtual environment:

    • On macOS/Linux: 
      source venv/bin/activate
    • On Windows: 
      venv\Scripts\activate

    Once activated, you can run the scripts with all dependencies properly configured.

Tools Included

add_redirects.py

This script is designed to add redirect_from entries to the front matter of Jekyll posts based on the current permalink format defined in the site's _config.yml.

Usage

  1. Navigate to the directory containing the script:

    cd jekyll-tools

  2. Backup your _posts directory: Before running the script, create a backup of your _posts directory to avoid accidental data loss, as the script modifies files in place.

  3. Run the script with the path to your Jekyll site directory:

    python add_redirects.py /path/to/your/jekyll/site

    Replace /path/to/your/jekyll/site with the actual path to your Jekyll site directory.

  4. When finished, deactivate the virtual environment:

    deactivate

How It Works

  • The script reads the _config.yml file in your Jekyll site directory to determine the permalink format.
  • It scans all Markdown files in the _posts directory.
  • For each post, it generates the current permalink based on the format and adds it to the redirect_from field in the front matter if it is not already present.

Example

Given a _config.yml file with the following permalink format:

permalink: /:year/:month/:title/

And a post file named 2023-10-01-example-post.md with the following front matter:

---
title: Example Post
categories: blog
---

The script will add the following redirect_from entry:

---
title: Example Post
categories: blog
redirect_from:
  - /2023/10/example-post/
---

Notes

  • The script assumes that post filenames follow the YYYY-MM-DD-title.md format.
  • Existing redirect_from entries will not be duplicated.
  • Backup your _posts directory before running the script, as it modifies files in place.

set_link_category.py

This script adds a link_category front matter entry to all posts in the _posts directory of a Jekyll site. The value is set to the first category in the categories list if it exists and link_category is not already set.

The link_category can then be used to include a single category in a post's permalink, rather than including all categories as jekyll does when using categories.

Usage

  1. Navigate to the directory containing the script:

    cd jekyll-tools

  2. Backup your _posts directory: Before running the script, create a backup of your _posts directory to avoid accidental data loss, as the script modifies files in place.

  3. Run the script with the path to your Jekyll site directory:

    python set_link_category.py /path/to/your/jekyll/site

    Replace /path/to/your/jekyll/site with the actual path to your Jekyll site directory.

  4. When finished, deactivate the virtual environment:

    deactivate

How It Works

  • The script scans all Markdown files in the _posts directory.
  • For each post, it checks if the front matter contains a categories list.
  • If a categories list exists, it sets the link_category field to the first category in the list, provided link_category is not already set.

Example

Given a post file named 2023-10-01-example-post.md with the following front matter:

---
title: Example Post
categories:
  - blog
  - tutorials
---

The script will add the following link_category entry:

---
title: Example Post
categories:
  - blog
  - tutorials
link_category: blog
---

Notes

  • Posts without a categories list or with an empty categories list will be skipped.
  • Existing link_category entries will not be overwritten.
  • Backup your _posts directory before running the script, as it modifies files in place.

License

This project is licensed under the MIT License. See the LICENSE file for details.