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#
- Create a new Astro project and install
astro-theme-university. - Move your Markdown content into Astro content collections.
- Convert any kramdown-specific syntax to standard Markdown.
- Replace Liquid tags and includes with Astro components.
- Move images into
src/assets/orpublic/. - 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:
- Attribute lists like
{: .my-class}— these have no Markdown equivalent. Use an MDX component or raw HTML instead. - Table of contents with
{:toc}— use an Astro component or a remark plugin. - Footnote syntax — standard Markdown footnotes (
[^1]) work, but check the exact syntax matches.
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:
src/assets/— images here are processed and optimised by Astro’s built-in image pipeline. Import them in your components.public/— files here are copied as-is to the build output. Use this for files that shouldn’t be processed.
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.