awesome-python/website/data/category_intros/static-site-generators.md

Of the two Python static site generators here, Pelican builds your blog. Nikola also builds sites that aren't only a blog, and takes Jupyter notebooks as posts.

How to choose:

• A blog: Pelican
• A site with more than a blog, or no blog at all: Nikola
• Jupyter notebooks as posts: Nikola
• Themes written in Mako: Nikola

Pelican splits content into articles and pages: articles are dated, like blog posts, and pages hold content that rarely changes, like an About page. Start a project with pelican-quickstart. Then write each post as a Markdown or reStructuredText file in content/, with metadata headers at the top. While you write, pelican --autoreload --listen rebuilds the site on every change and serves it on localhost. Themes are Jinja2 templates. The default theme is plain HTML without styling, so start from a community theme or write your own. Add features with plugins you install with pip, which Pelican can discover on its own. It isn't only for blogs, though a site without one takes some theme and configuration changes.

Nikola started as a blog generator but supports most kinds of sites. It comes with batteries included: comments, tags, archives, feeds, multilingual support, image galleries, and code listings. Out of the box, it takes reStructuredText, Markdown, Jupyter notebooks, and HTML. Create a site with nikola init --demo, which runs a setup wizard. Write each post with nikola new_post -e, which adds the metadata headers for you. Posts default to reStructuredText; add -f markdown for Markdown. nikola build fills the output directory, and nikola serve --browser opens the site in your browser. For a server that rebuilds on every change, run nikola auto --browser. Themes are Mako or Jinja2 templates. For a site with no blog, follow its guide to building a site that isn't a blog.

Both write plain HTML files: Pelican's output is easy to host anywhere, and a Nikola site runs on any web server. For GitHub Pages, push your Pelican sources and let a GitHub Actions workflow build the site. Nikola's nikola github_deploy builds the site and pushes the output to a gh-pages branch. Moving off WordPress works with either: Pelican imports a WordPress XML export, and Nikola has nikola import_wordpress.