Migrating from Jekyll

Jekyll is a static site generator built on Ruby.

Key Similarities between Jekyll and Astro

Jekyll and Astro share some similarities that will help you migrate your project:

Both Jekyll and Astro are static-site generators, commonly used to create blogs.
Both Jekyll and Astro allow you to write your content in Markdown and HTML. Jekyll and Astro both provide some special frontmatter YAML properties for page layout and unpublished draft posts. You can continue to use your existing Markdown files in Astro.
Both Jekyll and Astro use file-based routing for creating pages from your blog posts. Astro provides a special src/pages/ directory for all pages and posts. Jekyll uses a similar special folder called _posts/ for your Markdown blog posts, however your site pages can exist elsewhere. Creating new blog posts should feel familiar.

Key Differences between Jekyll and Astro

When you rebuild your Jekyll site in Astro, you will notice some important differences:

As Jekyll is primarily a blogging platform, several blog features are built-in that you may have to build yourself in Astro. Or, choose a blog starter template theme that includes these features. For example, Jekyll has built-in support for tags and categories which you will find in several Astro blog themes, but is not included in a minimal Astro project.
Jekyll uses Liquid templates for reusable layout elements and templating. Astro uses JSX-like .astro files for templating and components. Any .astro file can be a component, a layout or an entire page, and can import and render any other Astro components. You can also build using other UI framework components (e.g. React, Svelte, Vue, Solid) as well as content or metadata from other files in your project, such as Markdown or MDX.

Switch from Jekyll to Astro

To convert a Jekyll blog to Astro, start with our blog theme starter template, or explore more community blog themes in our theme showcase.

You can pass a --template argument to the create astro command to start a new Astro project with one of our official starters. Or, you can start a new project from any existing Astro repository on GitHub.

npm create astro@latest -- --template blog

pnpm create astro@latest --template blog

yarn create astro --template blog

Bring your existing Markdown files as content to create Markdown pages, using an Astro Markdown layout instead of a Liquid template.

Much of your existing HTML page content can be converted into Astro pages, and you will additionally be able to use variables, JSX-like expressions and component imports directly in your HTML templating.

Astro does not have a permalink property that accepts placeholders. You may need to read more about Astro’s page routing if you want to keep your existing URL structure. Or, consider setting redirects at a host like Netlify.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on astro.new. You’ll find a link to each project’s GitHub repository, as well as one-click links to open a working project in StackBlitz, CodeSandbox and Gitpod online development environments.