Skip to main content

Migrating from Jekyll

If you’re coming from a Jekyll site, this guide covers the key steps and differences. The content structure maps closely, so migration is mostly mechanical, but a few concepts differ.

High-level steps

  1. Create a new Astro project and install astro-theme-university.
  2. Move your Markdown content into Astro content collections.
  3. Convert any kramdown-specific syntax to standard Markdown.
  4. Replace Liquid tags and includes with Astro components.
  5. Move images into src/assets/ or public/.
  6. Update frontmatter to match the new schema.

Content collections replace _posts

In Jekyll, posts live in _posts/ with date-prefixed filenames. In Astro, you define a content collection with a schema and put your files in src/content/<collection>/.

# Jekyll
_posts/2024-03-15-my-post.md

# Astro
src/content/posts/my-post.md

The date and slug are handled through frontmatter rather than the filename. See content collections for the full setup.

Frontmatter changes

Jekyll uses a layout field in frontmatter to select a layout. In Astro, layouts are applied in the page template that renders the collection, not in the content file itself. Remove the layout field from your frontmatter.

# Jekyll
---
layout: post
title: My post
date: 2024-03-15
---
# Astro
---
title: My post
date: 2024-03-15
---

Kramdown to standard Markdown

Jekyll’s default Markdown processor, kramdown, supports some non-standard syntax. Common things to update:

Liquid tags become Astro components

Jekyll uses Liquid template tags like {% include %} and {% for %}. In Astro, these are replaced by component imports and standard JavaScript:

# Jekyll
{% include figure.html src="photo.jpg" alt="A photo" %}

# Astro (in an .astro file)
import Figure from "../components/Figure.astro";
<Figure src="photo.jpg" alt="A photo" />

The same applies in Markdown/MDX content files: import components at the top and use them inline.

Data files

Jekyll’s _data/ directory (YAML/JSON files accessed via site.data) has no direct equivalent. Instead, create TypeScript modules and import them:

// src/data/team.ts
export const team = [
  { name: "Alice", role: "Researcher" },
  { name: "Bob", role: "Developer" },
];

Images

In Jekyll, images typically live in an assets/ or images/ directory and are referenced with site-relative paths. In Astro, you have two options:

No Gemfile

Dependencies are managed through package.json with npm or pnpm instead of a Gemfile. The theme is installed as a regular npm package.