Migrating from Pelican

Pelican is an open-source static site generator built on Python.

Key Similarities between Pelican and Astro

Section titled Key Similarities between Pelican and Astro

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

  • Pelican and Astro are both static-site generators, ideally suited to content-focused websites like blogs.

  • Pelican and Astro both have built-in support for writing in Markdown, including frontmatter YAML properties for page metadata. However, Astro has very few reserved frontmatter properties compared to Pelican. Even though many of your existing Pelican frontmatter properties will not be “special” in Astro, you can continue to use your existing Markdown files and frontmatter values.

Key Differences between Pelican and Astro

Section titled Key Differences between Pelican and Astro

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

  • Pelican supports writing content in Markdown and reStructured Text (.rst). Astro supports creating pages from Markdown and MDX files, but does not support reStructured Text.

  • Pelican uses HTML files and Jinja syntax for templating. Astro syntax is a JSX-like superset of HTML. All valid HTML is valid .astro syntax.

  • Pelican was designed to build content-rich websites like blogs and has some built-in, blog features that you would have to build yourself in Astro. Instead, Astro offers some of these features included in an official blog theme.

Switch from Pelican to Astro

Section titled Switch from Pelican to Astro

To convert a Pelican documentation site to Astro, start with our official Starlight docs theme starter template, or explore more community 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.

Terminal window
npm create astro@latest -- --template starlight

Bring your existing Markdown content files to create Markdown pages. You can still take advantage of file-based routing by copying these documents from Pelican’s content/ folder into src/pages/ in Astro. You may wish to read about Astro’s project structure to learn where files should be located.

Pelican may have handled much of your site layout and metadata for you. You may wish to read about building Astro Layouts as Markdown page wrappers to see how to manage templating yourself in Astro, including your page <head>.

To convert other types of sites, such as a portfolio or a blog, 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.

Community Resources

Section titled Community Resources
  • Add your own!

More migration guides