Skip to content

Toolkit to make transferring a Jekyll website to Astro simple!

License

Notifications You must be signed in to change notification settings

humanwhocodes/astro-jekyll

Repository files navigation

Astro Jekyll Compatibility Package

by Nicholas C. Zakas

If you find this useful, please consider supporting my work with a donation.

Description

Allows Astro to understand Markdown formatted in the manner that Jekyll to make transitioning from Jekyll to Astro easier.

See the example-site folder for an example.

Requirements

  • Node.js v18+
  • Astro v2.0+

Installation

Install using [npm][npm] or [yarn][yarn]:

npm install @humanwhocodes/astro-jekyll

# or

yarn add @humanwhocodes/astro-jekyll

Usage

This package exports the following:

  • parseJekyllDateTime() - a utility function to convert Jekyll-formatted datetime strings into JavaScript Date objects.
  • formatJekyllPermalink() - a utility function to populate a Jekyll permalink string with post information.
  • formatJekyllPost() - a function that returns a function you can use to format posts using Jekyll frontmatter.

Import into your Astro project:

import {
    parseJekyllDateTime,
    formatJekyllPermalink,
    formatJekyllPost
} from "@humanwhocodes/astro-jekyll";

In general, you'll probably only ever need formatJekyllPost(), which you use after calling getCollection(), like this:

import { CollectionEntry, getCollection } from 'astro:content';	
    
const posts = (await getCollection('blog'))
    .map(formatJekyllPost());

Each CollectionEntry object is then populated with the Jekyll-style frontmatter and ready to be used elsewhere in Astro.

By default, formatJekyllPost() assumes a permalink format of /blog/:year/:month/:title. You can change it by passing in a custom permalink format:

import { CollectionEntry, getCollection } from 'astro:content';	
    
const posts = (await getCollection('blog'))
    .map(formatJekyllPost({
        permalink: "/snippets/:short_year/:month/:title/"
    }));

The first part of the permalink (in this case, snippets) is assumed to be the directory your [...slug].astro file is in and will be stripped off. It's only used for proper placement in the string and to make it easy to copy-paste permalinks directly from Jekyll.

The following placeholders are supported:

  • :year
  • :short_year
  • :month
  • :i_month
  • :day
  • :i_day
  • :hour
  • :minute
  • :second
  • :title
  • :slug

Pull requests gratefully accepted for adding the remaining Jekyll placeholders.

License

Apache 2.0