getpelican.com

What is Pelican?

Pelican is a static site generator written in Python. You write content in Markdown or reStructuredText, and Pelican turns it into a complete website of HTML files. It requires no database and no server-side logic, so the result is a folder of static files you can host almost anywhere—including free static hosting services.

What you get out of the box

The project describes a fairly complete publishing toolkit rather than a minimal converter:

• Content in Markdown or reStructuredText, with code syntax highlighting via Pygments.
• Support for both chronological content (articles, blog posts) and standalone static pages.
• Themes built with Jinja2 templates, plus a plugin ecosystem for extending behavior.
• Atom and RSS feeds generated automatically.
• Multi-language publication of articles.
• Importers for existing content from WordPress, Dotclear, or RSS feeds.
• Fast rebuilds through content caching and selective output writing.

Who it suits

Pelican fits developers and technical writers who are comfortable in a terminal and want their site to live in version control alongside their writing. A typical reader scenario: a programmer who already knows Python, wants a personal blog or project documentation site, and would rather run one command than maintain a database, CMS admin panel, and security patches. The quickstart reflects that workflow—install Pelican and Markdown with pip, run pelican-quickstart to generate a project skeleton, drop a Markdown file into the content folder, then preview locally with pelican -r -l at http://localhost:8000/.

Trade-offs to weigh

Because everything is static, there is no comment system, search, or content editing interface unless you add external services or plugins yourself. Publishing means running a build and uploading the output, not clicking "publish" in a browser. If you prefer writing in a web editor or want non-technical collaborators to contribute without touching files, a hosted CMS will be less friction. If you value speed, portability, and keeping content as plain text, Pelican's model is a good fit.

If you are deciding between static generators, the practical criterion is your existing toolchain: Pelican is the natural choice when Python is already part of your environment, since plugins, themes, and customization all assume it. Start with the official quickstart at Pelican and build one small site before migrating anything substantial.

How do I install and set up a new Pelican site from scratch?

Pelican is a Python-based static site generator: it turns Markdown or reStructuredText files into a finished website with no database and no server-side code. Setup happens in four steps — install, scaffold, write, preview — and the whole process takes only a few minutes if Python and pip are already on your machine.

Install Pelican and Markdown

Pelican itself does not parse Markdown out of the box, so install the Markdown extra alongside it:

python -m pip install "pelican[markdown]"

If you plan to write in reStructuredText instead, you can skip the Markdown extra, but most newcomers find Markdown more familiar.

Create the project skeleton

Make a folder for the site and run the built-in quickstart wizard inside it:

mkdir -p ~/projects/yoursite
cd ~/projects/yoursite
pelican-quickstart

The wizard asks a series of questions — site title, author, language, timezone, and your URL prefix. Enter your real domain (for example, https://example.com) when prompted for the URL prefix, because that value is baked into feeds and absolute links. It also asks whether you want Makefile and Fabric task files; accepting both gives you the make devserver and make publish shortcuts later.

Write your first article

Create a file at content/keyboard-review.md. Pelican reads metadata from the top of the file, followed by a blank line and the body:

Title: My First Review
Date: 2010-12-03 10:20
Category: Review

Following is a review of my favorite mechanical keyboard.

The Title and Date fields are the minimum you need; Category, Tags, Slug, and Lang are optional but useful once the site grows.

Preview and rebuild

pelican -r -l

The -l flag starts a local server and -r watches your content folder for changes, so edits appear on refresh. Open http://localhost:8000/ in a browser. When you are ready to deploy, pelican content writes the finished HTML into the output/ directory, which you can upload to any static host.

What you get, and where the trade-offs are

The main trade-off is that Pelican is a command-line tool aimed at people comfortable editing text files and running a build step. If you want a browser-based editor and no local toolchain, a hosted CMS will suit you better. Pelican also assumes you will handle deployment yourself — it generates files, it does not host them.

A practical next step: read the official documentation before customizing, since the quickstart deliberately hides settings such as SITEURL, OUTPUT_PATH, and theme selection that you will want to change before going live. If you prefer a different language ecosystem, Hugo and Jekyll solve the same problem with Go and Ruby respectively, and are worth comparing if your team already works in one of those languages.

Can I migrate my existing WordPress or Dotclear blog to Pelican?

Yes. Pelican's documented features include importing existing content from WordPress, Dotclear, or RSS feeds. That means you can bring over posts and pages rather than rebuilding them by hand, then let Pelican generate the site as static HTML.

What the migration covers

Pelican's importer is the starting point, not the whole job. Expect to handle a few things yourself:

• Content conversion. Pelican writes in reStructuredText or Markdown, so imported HTML from WordPress or Dotclear may need cleanup to fit that workflow.
• Media and links. Images, uploads and internal links often need re-pointing to the new file layout.
• Templates. Pelican themes use Jinja2, so an existing WordPress theme will not carry over; you choose or build a Pelican theme instead.
• URLs and feeds. Pelican generates Atom and RSS feeds, but old permalinks may need redirects to avoid breaking search traffic.
• Plugins. If your old blog depended on WordPress plugins, check whether Pelican's plugin ecosystem has an equivalent.

A practical migration path

1. Install Pelican with Markdown support: python -m pip install "pelican[markdown]".
2. Create a project folder and run pelican-quickstart, entering your domain as the URL prefix.
3. Run the WordPress, Dotclear or RSS importer against an export of your old site.
4. Preview locally with pelican -r -l at http://localhost:8000/ and fix formatting, media and links.
5. Set up redirects from old URLs, then publish.

Who this suits

This route fits writers and developers comfortable with Python tooling who want a fast, database-free site and are willing to spend an afternoon on cleanup. If you rely heavily on WordPress plugins, comments, or a visual page builder, the migration cost is higher and may outweigh the benefit. Start by exporting your WordPress content and running the importer on a copy, so you can judge the cleanup work before committing.

How do I preview my Pelican site locally while writing content?

Run pelican -r -l from your project directory. Pelican builds the site, starts a local web server at http://localhost:8000/, and watches your content and templates for changes so the preview refreshes as you write. That is the standard local preview loop described in Pelican's own quickstart on Pelican – A Python Static Site Generator.

What each flag does

The -r flag is what makes the workflow practical for writing. Instead of re-running the build after every edit, you leave one terminal open, save your Markdown or reStructuredText file, and reload the browser. Pelican's content caching and selective output writing keep these rebuilds fast, which matters once a site grows past a handful of articles.

A concrete writing session

1. Open a terminal in your project folder, for example ~/projects/yoursite.
2. Run pelican -r -l.
3. In another window, edit content/keyboard-review.md or add a new file with a Title, Date and Category header.
4. Save, then refresh http://localhost:8000/ to see the result.
5. When you are done, stop the server with Ctrl+C and run a normal pelican content build before publishing.

Points worth knowing

The local server is for your own machine only; it is not a deployment step. Because the preview reflects your real templates and settings, it is the right place to catch theme problems, broken internal links and feed output before anything goes live. If a change does not appear, check the terminal for build errors first — a malformed metadata header is a common cause of a page silently not regenerating.

For anyone migrating existing material, the same preview loop lets you verify imported WordPress, Dotclear or RSS content before committing to it. Pelican documents the full option set in its docs, linked from Pelican – A Python Static Site Generator.

What plugins are available to extend Pelican's functionality?

Pelican's extension model is its plugin ecosystem, and the site points to a dedicated Pelican Plugins index rather than listing every plugin on the main page. That index is where you browse what is available; the core page only confirms that extensibility exists and links out to it.

How to think about what you'll find

Plugins typically hook into Pelican's build pipeline — reading content, transforming it, or generating extra output — so the practical categories you should expect to search for are:

• Content handling — extra markup, front-matter behaviour, or importers beyond the built-in WordPress/Dotclear/RSS options.
• Output and feeds — sitemaps, alternate feed formats, or extra generated files.
• Presentation — helpers that feed into Jinja2 themes, such as asset pipelines or syntax-highlighting tweaks.
• Integrations — pushing builds or content to external services, which the feature list already gestures at.

A concrete way to choose

Suppose you run a small Python blog and want a sitemap plus better code blocks. Rather than installing plugins speculatively, start from the official index, filter to plugins that state compatibility with your Pelican version, and add one at a time so a broken build is easy to attribute. Check each plugin's repository activity before adopting it — a plugin that hasn't been touched in years is a maintenance liability even if it still works today.

For background on writing your own, the documentation linked from Pelican covers the plugin interface; the general Python packaging guides at Python are useful if you intend to publish one.

How does Pelican handle multilingual content and RSS feeds?

Pelican treats multilingual publishing as a first-class feature rather than an add-on. You write separate content files for each language, and Pelican generates parallel versions of your articles and pages, so a French post and its English counterpart are distinct source files that share a translation relationship. The same mechanism produces Atom and RSS feeds, which Pelican generates automatically from your chronological content.

Multilingual content

• Each translated article is its own file, tagged with a language in its metadata. Pelican then builds one site tree per language.
• You can configure a default language and a list of supported languages in your settings file; the site root typically serves the default language, with other languages under their own paths.
• The practical trade-off is duplication: you maintain every translation by hand and must keep dates, slugs and cross-links consistent. Pelican handles the routing and feed generation, not the translation itself.
• This suits documentation sites, personal blogs and small editorial projects where a human writes each language version. It is less suited to machine-translated content at scale, where a CMS with translation workflows may fit better.

Feeds

Pelican generates Atom and RSS feeds as part of the normal build. Because feeds are derived from the same chronological content model as your articles, a multilingual site naturally gets per-language feeds, and readers subscribing to one language do not see the others. Feeds are static files, so there is no server-side feed service to run or pay for.

A concrete scenario

Suppose you run a personal blog in English and Spanish. You create content/keyboard-review.md and content/keyboard-review.es.md, set the language metadata on each, and run a preview build. Pelican renders both article pages, both index pages and both feeds. Your English readers subscribe to the English feed and never see the Spanish posts. When you edit one translation, you rebuild and only the affected output changes, since Pelican caches content and writes selectively.

How it compares

Next step

Install Pelican with Markdown support, run pelican-quickstart, and create two versions of one short article in different languages with a Lang field in each. Build once and inspect the output directory: you will see the per-language folders and feed files, which tells you quickly whether the file-per-translation model matches how you actually work. If you prefer writing in reStructuredText or want a broader comparison of Python-based generators, the official documentation at Pelican covers settings and themes in detail.