Pelican – A Python Static Site Generator

Pelican 4.11 released

2025-01-15T00:00:00+01:00

Pelican 4.11 is now available. This new release includes the following enhancements, fixes, and tweaks:

Add setting to selectively omit Typogrify filters
Add more blocks to the Simple theme’s base template, making it easier to create new themes by inheriting from the Simple theme
Fix auto-reload behavior upon changes to the theme, content or settings
Get current year from the SOURCE_DATE_EPOCH environment variable, if available
Add Python 3.13 to test matrix and remove Python 3.8
Require Typogrify 2.1+ and Pygments <2.19

For more information, please refer to the release page or the Release History section of the documentation. For the full list of changes, see: https://github.com/getpelican/pelican/compare/4.10.2...4.11.0

Upgrading from previous releases

Upgrading from Pelican 4.10.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

As always, we do everything we can to maximize backwards compatibility and ensure smooth Pelican upgrades. If you run into problems, please see the How to Get Help section of the documentation, and we will update this post with any upgrade tips contributed by the Pelican community.

Pelican 4.10 released

2024-09-16T00:00:00+02:00

Pelican 4.10 is now available. This new release includes the following enhancements, fixes, and tweaks:

Add setting to specify summary via paragraph count
Add new status to skip generation of a post
Add setting to append ref parameter to links in feeds
Configure logging handler via --log-handler CLI option
Resolve intra-site links in summaries
Warn when files are not processed due to disabled readers
Add Medium post importer
Improve GitHub Pages workflow
Improve code test coverage
Translate documentation into Simplified Chinese

Upgrading from previous releases

Upgrading from Pelican 4.9.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

Pelican 4.9 released

2023-11-15T00:00:00+01:00

Pelican 4.9 is now available. This new release includes the following enhancements, fixes, and tweaks:

Upgrade code to new minimum supported Python version: 3.8
Settings support for pathlib.Path (#2758)
Various improvements to Simple theme (#2976 & #3234)
Use Furo as Sphinx documentation theme (#3023)
Default to 100 articles maximum in feeds (#3127)
Add period_archives common context variable (#3148)
Use watchfiles as the file-watching backend (#3151)
Add GitHub Actions workflow for GitHub Pages (#3189)
Allow dataclasses in settings (#3204)
Switch build tool to PDM instead of Setuptools/Poetry (#3220)
Provide a plugin_enabled Jinja test for themes (#3235)
Preserve connection order in Blinker (#3238)
Remove social icons from default notmyidea theme (#3240)
Remove unreliable WRITE_SELECTED feature (#3243)
Importer: Report broken embedded video links when importing from Tumblr (#3177)
Importer: Remove newline addition when iterating Photo post types (#3178)
Importer: Force timestamp conversion in Tumblr importer to be UTC with offset (#3221)
Importer: Use tempfile for intermediate HTML file for Pandoc (#3221)
Switch linters to Ruff (#3223)

Upgrading from previous releases

Upgrading from Pelican 4.8.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

New Pelican Site, Docs Theme, and Discussions

2022-09-15T00:00:00+02:00

✨ New Pelican Web Site ✨

Pelican has a brand-new, custom-built web site! 🦄

The previous design served the Pelican community well for many years, but it was time for it to be replaced with a design that is more modern and responsive on mobile devices. Check it out on a phone and marvel at its glory!

We also took this opportunity to switch the canonical domain from blog.getpelican.com to the root getpelican.com domain, with the blog now available at https://getpelican.com/blog/.

Many sincere thanks to Luca Fedrizzi for his excellent work on the new web site. 🥇

✨ New Documentation Theme ✨

In a similar fashion, the default ReadTheDocs theme for Pelican’s documentation served us well but was overdue to be replaced with a more modern and responsive theme. We chose the excellent Furo theme by Pradyun Gedam, and it is a wonderful complement to the new Pelican web site design.

We extend our gratitude to Paolo Melchiorre for his pull request that implemented this welcome change. 👍

✨ Pelican Discussions ✨

IRC will always have a place in our hearts, but it was never the most accessible channel for the Pelican community. Even more experienced folks often found it a cumbersome place to get help and interact with other Pelican users, so was time to find a more appropriate solution.

We have therefore set up Pelican Discussions, which is now the best place for the Pelican community to exchange ideas, ask questions, and propose suggestions. Please visit the initial discussion and post a comment introducing yourself and your Pelican site(s). We’d love to hear from you!

We are excited that the Pelican community now has a better place to have asynchronous discussions. At some point we will most likely set up an officially-supported space on Matrix for real-time conversations.

Pelican 4.8 released

2022-07-11T00:00:00+02:00

Pelican 4.8 is now available. This new release includes the following enhancements, fixes, and tweaks:

Use JSON values for extra settings in Invoke tasks template (#2994)
Add content tag for links, which can help with things like Twitter social cards (#3001)
Improve word count behavior when generating summary (#3002)

Upgrading from previous releases

Upgrading from Pelican 4.7.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

Pelican 4.7 released

2021-10-01T00:00:00+02:00

Pelican 4.7 is now available. This new release includes the following enhancements, fixes, and tweaks:

Improve default theme rendering on mobile and other small screen devices (#2914)
Add support for hidden articles (#2866)
Improve word count behavior when generating summary CJK & other locales (#2864)
Add progress spinner during generation (#2869) and richer logging (#2897), both via Rich
Invoke tasks serve and livereload now auto-open a web browser pointing to the locally-served web site (#2764)
Support some date format codes used by ISO dates (#2902)
Document how to add a new writer (#2901)

For more info, please refer to the release page or the Release History section of the documentation. For the full list of changes, see: https://github.com/getpelican/pelican/compare/4.6.0...4.7.0

Upgrading from previous releases

Upgrading from Pelican 4.6.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

Pelican 4.6 released

2021-03-23T00:00:00+01:00

Pelican 4.6 is now available. Thanks to Tom Adler’s contribution, this release contains a new feature that allows for more SEO-friendly index pages, whereby /page-1/ contains the oldest articles, with newer articles placed on /page-2/, /page-3/, etc. That way, the names of the previous article index pages do not change every time a new index page is generated. Cool URLs don’t change!

To enable this feature, first add a pagination pattern for -1 to your Pelican settings file. For example:

PAGINATION_PATTERNS = (
    (1, "{base_name}/page-1/", "{base_name}/page-1/index.html"),
    (2, "{base_name}/page-{number}/", "{base_name}/page-{number}/index.html"),
    (-1, "{base_name}/", "{base_name}/index.html"),
)

You will also benefit from changing other settings to match the intended behavior. For example:

DEFAULT_PAGINATION = 5
DEFAULT_ORPHANS = 4
ARTICLE_ORDER_BY = "date"
REVERSE_ARCHIVE_ORDER = True
NEWEST_FIRST_ARCHIVES = True

In your theme’s index.html and tag.html templates, change the object_list loop to object_list[::-1] to reverse the order of the article list:

{% for article in articles_page.object_list[::-1] %}

Make sure the pagination links below the list are changed to reflect the switched direction of “next” vs. “previous” articles. For example:

{% if articles_page.has_next() %}
    <a class="pagination-item newer" href="{{ SITEURL }}/{{ articles_next_page.url }}">next</a>
    {% else %}
    <span class="pagination-item newer">next</span>
{% endif %}
{% if articles_page.has_previous() %}
    <a class="pagination-item older" href="{{ SITEURL }}/{{ articles_previous_page.url }}">previous</a>
    {% else %}
    <span class="pagination-item older">previous</span>
{% endif %}

While this is general guidance and will apply differently depending on your chosen theme, hopefully the above helps you get further along experimenting with this new feature.

This new release also includes the following enhancements, fixes, and tweaks:

Speed up livereload Invoke task via caching (#2847)
Ignore None return value from get_generators signal (#2850)
Relax dependency minimum versions and remove upper bounds

For more info, please refer to the release page or the Release History section of the documentation. For the full list of changes, see: https://github.com/getpelican/pelican/compare/4.5.4...4.6.0

Upgrading from previous releases

Upgrading from Pelican 4.5.x should be smooth and require few (if any) changes to your environment. If upgrading from a previous release, review the other release announcements on this site to better understand what action might be necessary.

Migrating Plugins to New Organization

2021-02-15T00:00:00+01:00

So you want to help migrate a plugin? Great!

If the plugin you want to migrate is located in the legacy monolithic Pelican Plugins repository:

Create an issue at the legacy monolithic Pelican Plugins repository and ask a maintainer to create a corresponding new repository under the new Pelican Plugins organization and invite you to join it.

If, on the other hand, you are migrating a plugin from a personal repository:

Create an issue at the legacy monolithic Pelican Plugins repository, include a link to the personal repository, and ask a maintainer for assistance with the next steps.

Initial Setup (By Maintainer)

Create new repository via: https://github.com/organizations/pelican-plugins/repositories/new

repository name should not contain the word “pelican”
add description (example: “Pelican plugin that adds a table of contents to articles”)
set to Public
do not check the box marked: “Initialize this repository with a README”
do not add a README, .gitignore, or license file

Once the repository has been created:

Settings > Environments > New environment > Name: Deployment
Settings > Pull Requests > check: Always suggest updating pull request branches
Settings > Pull Requests > check: Automatically delete head branches
Invite collaborators: Settings > Collaborators and teams > Manage access > Add people (button)

In order to ensure package publication automation functions correctly, be sure to log into PyPI and add a trusted publisher: https://pypi.org/manage/account/publishing/

The following is performed on the maintainer’s workstation. Replace related-posts below with the name of the to-be-migrated plugin.

Clone the legacy monolithic repository:

cd ~/projects/pelican-plugins/
git clone https://github.com/getpelican/pelican-plugins related-posts-legacy
cd related-posts-legacy

Filter existing commits related to the plugin via git-filter-repo (which on MacOS can be installed via brew install git-filter-repo, or if you have Pipx installed, via pipx install git-filter-repo):

git filter-repo --path related_posts/ --path-rename related_posts/:
git log --reverse  # copy full day+date+timestamp of first commit

Create a new (empty) repository with an initial empty commit, using the above date:

mkdir ../related-posts && cd ../related-posts
git init --initial-branch=main
GIT_COMMITTER_DATE="Wed Apr 10 19:12:31 2013 -0400" GIT_COMMITTER_NAME="Original Author Name" GIT_COMMITTER_EMAIL="original_author@email.tld" git commit --allow-empty -m "Initial commit" --date="$GIT_COMMITTER_DATE" --author="$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>"

Add the new repository as the origin remote and push the initial commit:

git remote add origin git@github.com:pelican-plugins/related-posts.git
git push origin main

Add legacy plugin clone as a remote and pull contents into new branch:

git remote add legacy ../related-posts-legacy
git fetch legacy master
git checkout -b migrate --track legacy/master

Rebase legacy plugin commits on top of new initial commit and push:

git rebase --committer-date-is-author-date main
git push origin migrate

Updating the Plugin

Once a maintainer has created the new (empty) repository and pushed existing commits into a new migrate branch, clone the new repository to your workstation and switch to that branch:

git clone git@github.com:pelican-plugins/related-posts.git ~/projects/pelican-plugins/related-posts
cd ~/projects/pelican-plugins/related-posts
git switch migrate

Create the new directory structure and move the plugin code contents to it:

mkdir -p pelican/plugins/related_posts
git mv *.py pelican/plugins/related_posts/
git commit --no-verify -m "Convert to namespace plugin filesystem layout"

Review the Pelican Plugin CookieCutter Template docs and use the template to generate a fresh project. Here we’ll use the Pipx-based method to ephemerally invoke Cruft to generate a new plugin from the template:

cd ~
pipx run cruft create https://github.com/getpelican/cookiecutter-pelican-plugin

Guidance follows for answering the Cookiecutter questions you will be asked. Except for plugin_name, description, authors, keywords, license, and dev_status, you should be able to just hit the Return key to accept the provided default value.

plugin_name: For multiple-word names, put a space in between words and use title case. Should not contain the word “pelican”. Ex: Related Posts
repo_name: For multiple-word names, use a hyphen — not an underscore. Ex: related-posts
package_name: Hyphens should be converted to underscores here. Ex: related_posts
distribution_name: Prefixed with pelican-. Ex: pelican-related-posts
version: Leave as 0.0.0 default value, which will be incremented automatically via AutoPub upon initial distribution release.
description: Copy & paste description from repository’s About section
authors: Review source code and commit history to determine primary author, if any. Ask a maintainer if not clear. Ex: {name = "Jane Smith", email = "jane@example.com"}
keywords: Add relevant keywords, including "pelican" and "plugin". Ex: "pelican", "plugin", "table", "contents"
readme: Name of the README file. Ex: README.md
contributing: Name of the README file. Ex: CONTRIBUTING.md
license: Choose the same license as the original plugin.
repo_url: URL to the repository. Ex: https://github.com/pelican-plugins/related-posts
dev_status: Development status. Best to choose 5 - Production/Stable unless there’s a good reason not to. Ex: 5
tests_exist: Whether tests currently exist for this plugin.
python_version: Minimum Python version. Best to choose 3.9+. Ex: ~=3.9
pelican_version: Minimum Pelican version. Best to choose 4.5+. Ex: >=4.5

Copy over the new files generated by the plugin template, none of which presumably exist in the existing repository:

cd ~/projects/pelican-plugins/
mv ~/related-posts ~/projects/pelican-plugins/related-posts-new
cp -R related-posts-new/{.editorconfig,.gitignore,.github,.pre-commit-config.yaml,CONTRIBUTING.md,pyproject.toml,tasks.py} related-posts/

Create a virtual environment and set up the project:

cd ~/projects/pelican-plugins/related-posts
python -m venv ~/virtualenvs/related-posts
source ~/virtualenvs/related-posts/bin/activate
python -m pip install --upgrade pip invoke
invoke setup

Add any plugin dependencies to the pyproject.toml file via pdm add […] and adjust them in pyproject.toml to ensure they are in alphabetical order. Then install those added dependencies via:

pdm update

Compare the old and new README files, merging them such that the relevant parts of the template-generated README are present — particularly the build/PyPI status badges and the Installation and Contributing sections.

Are there any tests? If not, now might be a good time to copy over the generated test file and then add some:

cp related-posts-new/pelican/plugins/related_posts/test_related_posts.py related-posts/pelican/plugins/related_posts/test_related_posts.py

Confirm that the plugin is detected and registered:

pelican-plugins

Run the test suite and ensure there are no failures or errors:

invoke tests

Test that the plugin actually works by building it and installing the packaged distribution:

pdm build
pip install dist/pelican-related-posts-0.0.0.tar.gz

Fix functional issues, if any, and then commit Python code fixes with appropriate commit message(s):

git add [...]
git commit --no-verify

Ensure code has been modernized for Python 3.9+, review the changed files, modify as necessary, and commit:

pipx run pyupgrade --py39-plus pelican/plugins/related_posts/*.py
git add [...]
git commit --no-verify -m "Modernize code for Python 3.9+"

Make sure the GitHub Actions CI/CD workflow refers to the repository’s actual primary branch name (e.g., main):

grep github\.ref .github/workflows/main.yml

Add and commit the new files related to code style:

git add .editorconfig .pre-commit-config.yaml tasks.py .github
git commit --no-verify -m "Add code style and CI/CD configuration"

Apply code style formatting, ensure linting passes, and commit any code style changes:

inv ruff --fix
inv format
inv lint
git add [...]
git commit -m "Apply code style conventions to project"

Add and commit pyproject.toml and .gitignore:

git add pyproject.toml .gitignore
git commit -m "Add pyproject file to project"

Add and commit README changes and the CONTRIBUTING file:

git add README.md CONTRIBUTING.md
git commit -m "Update README and add CONTRIBUTING"

Link to current version of the plugin template via Cruft:

git add .cruft.json
git commit -m "Link to upstream plugin template via Cruft"

Assuming all new and changed files have been committed, push the branch and submit a pull request:

git push origin migrate

Clean Up

Remove section from .git/config that is no longer needed:

git remote remove legacy

Remove legacy clone and generated template files:

cd ~/projects/pelican-plugins/
trash related-posts-legacy related-posts-new

Add a note at the top of the legacy plugin README in the deprecated monolithic repository indicating that the plugin has migrated. 🎉

Pelican 4.5 released

2020-08-20T00:00:00+02:00

Pelican 4.5 is now available. Its marquee feature is support for “namespace” plugins, which means any plugin listed under the new Pelican Plugins organization can be installed via Pip, after which Pelican should automatically detect and enable the new plugin.

This also means that Pelican projects can specify and pin plugin versions, which helps ensure plugin updates do not cause unexpected problems building your site. For example, here we define a project’s Pelican and plugin versions via Poetry and pyproject.toml:

[tool.poetry.dependencies]
pelican = "^4.5"
pelican-simple-footnotes = "^1.0"
pelican-sitemap = "^1.0"
pelican-webring = "^1.0"

If one of the above plugins introduces a breaking change in v2.0, for example, there shouldn’t be any related disruption since above we have effectively pinned plugin versions to: >= 1.0, <2.0

This new release also includes the following enhancements, fixes, and tweaks:

List registered plugins via pelican-plugins command
Override settings via -e / --extra-settings CLI option flags
Add settings for custom Jinja globals and tests
Customize article summary ellipsis via SUMMARY_END_SUFFIX setting
Customize Typogrify dash handling via new TYPOGRIFY_DASHES setting
Support Unicode when generating slugs
Support Asciidoc .adoc file generation in Pelican importer
Improve user experience when pelican --listen web server is quit
Improve Invoke tasks template
Include tests in source distributions
Switch CI from Travis to GitHub Actions
Remove support for Python 2.7

For more info, please refer to the release page or the Release History section of the documentation. For a more comprehensive list of changes, please review the respective milestone for this release. For the full list of changes, see: https://github.com/getpelican/pelican/compare/4.2.0...4.5.0

Upgrading from previous releases

First, since Python 2.7 support has been dropped, ensure you are using Python 3.6+.

Next, if your site uses any Pelican plugins:

Have all your plugins been migrated to the new Pelican Plugins organization? If so, you can Pip-install those plugins, comment out the PLUGINS variable in your settings file, and ensure your site builds properly. If everything seems to be in order, you can remove the PLUGINS setting as well as any local plugin folders that contain legacy plugins.
If you are using one or more plugins that have not yet been migrated to the new Pelican Plugins organization, this is a great opportunity to contribute to Pelican by assisting with plugin migration. Create a new issue at the legacy plugin repo and communicate which plugin you would like to help migrate, after which a Pelican maintainer will guide you through the process.
If you want to use a mix of namespace & legacy plugins, or if you prefer to manually specify plugins instead of relying on Pelican’s automatic detection, you can use the PLUGINS setting as described in the How to Use Plugins documentation.
Importing from pelican.signals is deprecated. If your plugin uses that pattern, please notify the plugin author to update the code to use from pelican import signals or import pelican.plugins.signals instead.

Pelican Sprint — Fall 2019

2019-10-18T00:00:00+02:00

In the spirit of Hacktoberfest, we will be conducting an informal sprint on Sunday, 20 October. One of the goals for this sprint is to migrate plugins from the current monolithic repository to individual, community-shared repositories. The following issues will provide some historical background for those who want to learn more:

https://github.com/getpelican/pelican/issues/1488

https://github.com/getpelican/pelican-plugins/issues/425

Please join us via IRC this Sunday! Due to time differences, some folks will start earlier than others, so please be patient and stick around even if there isn't much activity there.

Looking forward to collaborating with you!

Pelican 4.1 released

2019-07-14T00:00:00+02:00

Pelican 4.1 has been released and includes the following enhancements, fixes, and tweaks:

Live browser reload upon changed files (provided via Invoke task)
Add pyproject.toml, managed by Poetry
Support for invoking python -m pelican
Add relative source path attribute to content
Allow directories in EXTRA_PATH_METADATA
Add all_articles variable to period pages (for recent posts functionality)
Improve debug mode output
Remove blank or duplicate summaries from Atom feed
Fix bugs in pagination, pelican-import, pelican-quickstart, and feed importer

Pelican 4.0 released

2018-11-13T00:00:00+01:00

Pelican 4.0 has been released, including many enhancements, fixes, and tweaks. Highlights include:

Replace develop_server.sh script with pelican --listen
Improved copy/link behavior for large static files (e.g., videos)
New {static} syntax to link to static content
Pages can now have draft status
Show current settings via new --print-settings flag
Replace Fabric’s fabfile.py with Invoke’s task.py
Importer improvements

Upgrading from previous releases

You may see deprecation warnings for certain settings. If that occurs, please change the specified setting to the new setting mentioned in the deprecation message.

Due to Python-Markdown changes, Markdown users must ensure they are using version < 3.0 or >= 3.1 to ensure proper rendering of code blocks.

Some user-submitted themes use positional argument formatting on object-related feed URLs, which will cause sites to fail to build with: "TypeError: not all arguments converted during string formatting". In that case, the theme needs to be updated. For example, substitute TAG_FEED_ATOM|format(tag.slug) with TAG_FEED_ATOM.format(slug=tag.slug). Affected variables include:

CATEGORY_FEED_ATOM
CATEGORY_FEED_ATOM_URL
CATEGORY_FEED_RSS
CATEGORY_FEED_RSS_URL
AUTHOR_FEED_ATOM
AUTHOR_FEED_ATOM_URL
AUTHOR_FEED_RSS
AUTHOR_FEED_RSS_URL
TAG_FEED_ATOM
TAG_FEED_ATOM_URL
TAG_FEED_RSS

Pelican 3.7 released

2016-12-12T00:00:00+01:00

Pelican 3.7 has been released, incorporating a year and a half worth of enhancements and bug fixes.

To see highlights, please refer to the release page or the Release History section of the documentation. For a more comprehensive list of changes, please review the respective milestone for this release. For the full list of changes, see: https://github.com/getpelican/pelican/compare/3.6.3...3.7.0

Upgrading from previous releases

Unlike Atom, the RSS feed specification does not contain a <content> field and only contains a <summary> field. Pelican previously put the full content in this field, which could cause odd behavior in feed readers that only expected a summary. For this reason, RSS feeds in Pelican 3.7 will by default only contain article summaries. To revert to the previous full-content behavior, either use Atom (which supports both <summary> and <content> fields) or set: RSS_FEED_SUMMARY_ONLY = False

If you have defined MD_EXTENSIONS in your settings file, you will see deprecation warnings since that setting has been replaced by the MARKDOWN setting in Pelican 3.7. Refer to the corresponding entry in the Settings documentation to see the new default value and replace any existing MD_EXTENSIONS settings with your preferred customized variation of the MARKDOWN setting.

Themes originally had access to two identical context variables: PAGES and pages. This redundancy was removed in Pelican 3.7, so any themes that use PAGES will need to be updated to use pages instead.

JINJA_EXTENSIONS has been replaced by the JINJA_ENVIRONMENT setting. Any plugins that refer to the former setting will need to be updated. Refer to the corresponding entry in the Settings documentation for more information.

Pelican 3.6 released

2015-06-15T00:00:00+02:00

Pelican 3.6 has been released. Highlights of the improvements contained in this release follow below.

For those who are new to Pelican, please refer to the Quickstart Guide. There is also a Tutorials page available, which also includes a link to a Pelican installation screencast.

Highlights

Disable caching by default in order to prevent potential confusion
Improve caching behavior, replacing pickle with cpickle
Allow Markdown or reST content in metadata fields other than summary
Support semicolon-separated author/tag lists
Improve flexibility of article sorting
Add --relative-urls argument
Support devserver listening on addresses other than localhost
Unify HTTP server handlers to pelican.server throughout
Handle intra-site links to draft posts
Move tag_cloud from core to plugin
Load default theme's external resources via HTTPS
Import drafts from WordPress XML
Improve support for Windows users
Enhance logging and test suite
Clean up and refactor codebase
New signals: all_generators_finalized and page_writer_finalized

For a full list of changes, see: https://github.com/getpelican/pelican/compare/3.5.0...3.6.0

Upgrading from previous releases

Content generation caching is now disabled by default. If you have a large site with many articles/pages and notice that site generation takes longer than you would prefer, follow these two steps:

Delete the cache folder, if it exists

Add the following to your settings file:

CACHE_CONTENT = True
LOAD_CONTENT_CACHE = True

While we do everything we can to maximize backwards compatibility and ensure smooth Pelican upgrades, it's possible that you may encounter un-anticipated wrinkles. If you run into problems, please see the How to Get Help section of the documentation, and we will update this post with any upgrade tips contributed by the Pelican community.

Pelican 3.5 released

2014-11-20T00:00:00+01:00

Today we are pleased to announce the release of Pelican 3.5. Highlights of the improvements contained in this release follow below.

For those who are new to Pelican, please refer to the Quickstart Guide. There is also a Tutorials page available, which currently includes a link to a Pelican installation screencast.

Highlights

Introduce ARTICLE_ORDER_BY and PAGE_ORDER_BY settings to control the order of articles and pages.
Include time zone information in dates rendered in templates.
Expose the reader name in the metadata for articles and pages.
Allow storing static files in the same directory as content source files, without causing the raw content sources to be published.
Introduce the {attach} internal link syntax for placing a static file in the same output directory as the document that links to it.
Prevent Pelican from raising an exception when there are duplicate pieces of metadata in a Markdown file.
Introduce the TYPOGRIFY_IGNORE_TAGS setting to add HTML tags to be ignored by Typogrify.
Add the ability to use - in date formats to strip leading zeros. For example, %-d/%-m/%y will now result in the date 9/8/12.
Ensure feed generation is correctly disabled during quickstart configuration.
Fix PAGE_EXCLUDES and ARTICLE_EXCLUDES from incorrectly matching sub-directories.
Introduce STATIC_EXCLUDE setting to add static file excludes.
Fix an issue when using PAGINATION_PATTERNS while RELATIVE_URLS is enabled.
Fix feed generation causing links to use the wrong language for month names when using other locales.
Fix an issue where the authors list in the simple template wasn't correctly formatted.
Fix an issue when parsing non-string URLs from settings.
Improve consistency of debug and warning messages.

For a full list of changes, see: https://github.com/getpelican/pelican/compare/3.4.0...3.5.0

Upgrading from previous releases

While we do everything we can to maximize backwards compatibility and ensure smooth Pelican upgrades, it's possible that you may encounter un-anticipated wrinkles. If you run into problems, please reach out via the #pelican channel on IRC, and we will update this post with any upgrade tips contributed by the Pelican community.

Pelican 3.4 released

2014-07-01T00:00:00+02:00

Today we are pleased to announce the release of Pelican 3.4, which is one of the more significant updates Pelican has ever seen. Take a look at the changelog and the Pelican 3.4 milestone issues list to see all the features, fixes, and miscellaneous improvements that are included in this release.

Major highlights

Faster rebuild times

Thanks to a new caching mechanism and selective output writing, rebuilding a site can take just a few seconds. Tinkering with posts and themes is now even easier.

Fixed locale and encoding issues

Finally URLs can include, for example, localized month names.

Improved documentation, both in style and content

The documentation has been ported to the new ReadTheDocs theme, including a functional search bar and a navigation side panel. A quickstart section is now provided to jump-start your Pelican experience.

Support for multiple post authors

The new :authors: metadata field makes it possible to easily manage multi-user sites.

Upgrading from previous releases

While we do everything we can to maximize backwards compatibility and ensure smooth Pelican upgrades, it's possible that you may encounter un-anticipated wrinkles. If you run into problems, please reach out via the #pelican channel on IRC, and we will update this post with any upgrade tips contributed by the Pelican community.

I18N Subsites plugin released

2014-02-05T00:00:00+01:00

Pelican has supported article and page translations since version 2.6. However, this functionality does not include translations of themes or the site name, something many have asked for.

The new I18N Subsites plugin makes it simple to:

override settings for each language, e.g. SITENAME or MENUITEMS
translate and localize themes using jinja2.ext.i18n
automatically create translated subsites such as http://example.com/fr/

The new plugin is available in the Pelican plugin repository.

A demo site has been put up to showcase the plugin. You can use the demo site source as a reference for using the plugin in your own site.

Although this plugin has been tested, it is quite possible that you will find some bugs or inconvenient behavior as it is very new. Do not hesitate to file an issue!

Finally, I would like to thank the Pelican developers for implementing and designing Pelican so well that making this plugin was straightforward, fast, and fun.

Pelican 3.3 released

2013-09-24T00:00:00+02:00

Today we are pleased to announce the release of Pelican 3.3. Highlights of the improvements contained in this release follow below.

For those who are new to Pelican, please refer to the Getting Started Guide. There is also a Tutorials page available, which currently includes a link to a Pelican installation screencast.

Highlights

Python 3.3 support

Following up on the last release's support for Python 3.2, this new version of Pelican now supports Python 3.3. In order to do so, support for Python 3.2 unfortunately had to be dropped.

Cross-platform automation via Fabric

Pelican has traditionally included a make-based workflow that works well enough for POSIX-based systems but at the expense of Windows users. In order to improve cross-platform publishing automation, Pelican 3.3 includes support for Fabric, a Python-based automation framework.

Retain certain files in output

Some folks apply version control to their output directories, the metadata for which is obliterated when using the DELETE_OUTPUT_DIRECTORY directive. Pelican 3.3 includes a new OUTPUT_RETENTION setting which allows you to define arbitrary files/folders that should be retained during the aforementioned output cleaning process (e.g., .hg, .git, et cetera).

Tumblr import

Tumblr posts can now be imported into Pelican sites.

Refactoring, fixes, and improvements

Pelican 3.3 includes a significant number of other improvements, as indicated by the long list of items in the changelog and the Pelican 3.3 milestone issues list.

Upgrade notes

While we do everything we can to maximize backwards compatibility and ensure smooth Pelican upgrades, it's possible that you may encounter un-anticipated wrinkles. Following are a few notes that may help:

The FILES_TO_COPY setting has been deprecated, so replace it with the STATIC_PATHS and EXTRA_PATH_METADATA settings. Refer to the corresponding entries in the Settings section of the docs for more information.
Due to minor changes to the plugin API, some plugins may not function properly if they are not updated accordingly. Most (if not all) of the plugins in the official Pelican Plugins Repository have already been updated, but externally-hosted plugins may not be. If you are heavily dependent on such a plugin, consider holding off on upgrading to Pelican 3.3 until you are certain that your desired plugins will function correctly.
PDF generation has been moved out of core and into a separate plugin. If you previously relied on this feature, please be sure to retrieve, install, and configure the new plugin from the Pelican Plugins Repository.
There is a new warning for <img> tags without alt="" attributes, which are important for accessibility reasons. Please consider adding these attributes to your <img> tags in order to improve accessibility (and eliminate the warnings).
The syntax for linking to source content has been changed in order to ensure compatibility with Markdown and reST extensions. For example, the new syntax for Markdown: [a link relative to content root]({filename}/article1.md) The previous |filename|/article1.md syntax will continue to be supported for backwards compatibility.

We will keep the above list updated with any additional items as we find them, so please let us know if we missed anything.

Using Pelican with Heroku

2013-07-25T00:00:00+02:00

Using Pelican with Heroku couldn't be easier. We have recently been working on a buildpack allowing you to publish your Pelican site directly to Heroku.

This allows you to host your Pelican site on the Heroku platform with very little effort. Simply create a Heroku application and push your repository to it.

You don't need to deal with generating the HTML with the Pelican command — the buildpack takes care of this. Just push a git repository with the pelicanconf.py file in the root directory.

To enable the Heroku buildpack for existing sites, run:

heroku buildpacks:set https://github.com/getpelican/heroku-buildpack-pelican

Alternatively, for those of you switching to Heroku, you can use the following command to create your Pelican site on Heroku.

heroku create myapp --buildpack https://github.com/getpelican/heroku-buildpack-pelican

Pelican 3.2 released

2013-04-24T00:00:00+02:00

Today we are pleased to announce the release of Pelican 3.2. Highlights of the improvements contained in this release follow below.

For those who are new to Pelican, please refer to the Getting Started Guide. There is also a Tutorials page available, which currently includes a link to a Pelican installation screencast.

Highlights

Python 3 support

As noted in Pelican's Unified Codebase, this new version of Pelican includes support for Python 3. All tests currently pass on Python 3.2, and we expect the same for Python 3.3 in the near future. (Pelican interacts with a number of third-party components that have not yet been fully updated for Python 3.3 compatibility.)

Override page save-to location from meta-data

Instead of blog or a site with dated articles, some people want to use Pelican to publish sites with non-chronological content. Pelican 3.2 enables this by providing a way to override the save-to location from within a page's meta-data, so for example, you can have a pages/index.md file that will replace your site root's index.html.

Time period archives

For folks who use date-based URL schemes such as /2013/04/23/my-post/, you can now create per-year and per-month archives that will appear at /2013/ and /2013/04/, respectively.

Posterous blog import

With Posterous shutting down on April 30th, this release offers the timely ability to import an existing Posterous blog. There are only a few days remaining, so if you have a Posterous blog and want to import it into a Pelican-powered site, please act quickly!

Separate Pelican plugins repository

Pelican plugins have been moved out of the core Pelican repository and into their own repository. This allows us to focus on the Pelican core while simultaneously encouraging the community to extend Pelican's functionality in the form of modular plugins.

Refactoring, fixes, and improvements

There have been a large number of improvements under the hood. While not an exhaustive list, the Pelican 3.2 milestone issues should provide a good overview of the many enhancements that are part of this release.

Upgrade notes

Add from __future__ import unicode_literals near the top of your settings file.
As noted above, Pelican plugins are now located in their own repository. If you currently use any plugins bundled with Pelican 3.1.1 or earlier, you should follow the instructions located in the Pelican plugins repository to re-enable those plugins.
Document-relative URL generation is now off by default. If you previously relied on this feature and fully understand its potential disadvantages, you can re-enable it by adding RELATIVE_URLS = True to your settings file.
The CSS class generated by the reST and Markdown processors was unified into a single highlight class. If you find that your code syntax highlighting has disappeared after upgrading, ensure that any instances of codehilite in your CSS are replaced with highlight.
Support for Python 2.6 has been dropped as of Pelican 3.2. For those running on distros that do not have a more recent version of Python available, one possible solution is to compile Python 2.7.x and use it from within a virtualenv (e.g., via virtualenv -p $HOME/bin/python2.7 pelican).

We will keep the above list updated with any additional items as we find them.

Special thanks

As evidenced by our growing THANKS file, there were many people who contributed to this release. A few folks deserve special mention for the many hours they put into this new version of Pelican:

Dirk Makowski added support for Python 3, including provisional ports for third-party components such as Typogrify and SmartyPants.

W. Trevor King has undertaken a significant refactoring of the Pelican core, improving a wide swath of the codebase that will continue to surface in future versions of Pelican.

Deniz Turgut (Avaris) contributed so many features and fixes to this release that it would be silly to even try to list them. He's put so much work into Pelican that one of the maintainers insisted that he set up a Gittip profile (which Deniz did under much duress), to which an anonymous donor has already made a sizeable contribution. If you want to thank Deniz for his hard work, please consider doing the same. It would be great to see him on the "Top Receivers" list next week!

Staying in touch

2013 has been a busy year so far, as evidenced by both the number of commits to Pelican as well as the lack of updates here on the Pelican blog. (^_^) We'll do our best to post more frequently in the months to come, both here on the blog and also via the @getpelican Twitter account.

Pelican's Unified Codebase

2013-04-16T00:00:00+02:00

In this post by Dirk Makowski, he explains how he added preliminary Python 3.x support to the forthcoming Pelican 3.2 release.

When referring to Pelican's "unified" codebase, this means the code runs without changes (or requiring 2to3) on both Python 2.x and 3.x. Specifically, this unified codebase is tested on Python 2.7 and 3.2.

At the time of this writing all tests pass, whether manually invoked via python -m unittest discover within manually-created virtual environments or via tox, which automatically creates virtual environments for Python 2.7 and 3.2 and runs tests on both Python versions:

74 tests, 9 skips, no errors

During my first attempt to port Pelican to Python 3, I had used 2to3 and manually applied corrections to achieve syntactical correctness. But as the tests showed, more subtle bugs in the encoding of strings remained (e.g. outputting b'...' instead of '...'). Also, the code was suitable for Python 3 only and would not run properly on Python 2.

Building on the lessons learned with 2to3, the current in-development version of Pelican now provides a single codebase for Python 2 and 3. The following section lists some hints about what had to be changed in order to achieve this. These hints may also be valuable for anyone who wants to contribute new Pelican features or bug fixes, since all Pelican code submissions must now run on both Python versions.

Unification

Assume every string and literal is Unicode (import unicode_literals):
- Do not use prefix u'.
- Do not encode/decode strings in the middle. Follow the code to the source (or target) of a string and encode/decode at the first/last possible point.
- In other words, write your functions to expect and to return Unicode.
- Encode/decode strings if the source is a Python function that is known to handle this badly, e.g., strftime() in Python 2.
Use new syntax: print function, "except ... as e" (not comma) etc.
Refactor method calls like dict.iteritems(), xrange() etc. in a way that runs without code change in both Python versions.
Do not use magic method __unicode()__ in new classes. Use only __str()__ and decorate the class with @python_2_unicode_compatible.
Do not start int literals with a zero. This is a syntax error in Py3k.
Unfortunately I did not find an octal notation that is valid in both Pythons. Use decimal instead.
use six, e.g.:
- isinstance(.., basestring) -> isinstance(.., six.string_types)
- isinstance(.., unicode) -> isinstance(.., six.text_type)
setlocale() in Python 2 bails when we give the locale name as Unicode, and since we are using from __future__ import unicode_literals, we do that everywhere! As a workaround, I enclosed the localename with str(); in Python 2 this casts the name to a byte string, and in Python 3 this should do nothing, because the locale name is already in Unicode.
Kept range() almost everywhere as-is (2to3 suggests list(range())) — just changed it where I felt necessary.
Changed xrange() back to range(), so it is valid in both Python versions.

About External Libraries

Core

Pelican core depends on feedgenerator. To run on Py3k, you will need feedgenerator 1.5, which also now has a unified codebase and is available on PyPI.

BeautifulSoup had to be upgraded to bs4 (only bs4 supports Py3k), which has some consequences:

To parse XML (e.g., which the WordPress importer does), the lxml package is now required.
bs4 does not have convertEntities anymore.

Plugins

On Python 2 you still can use all plugins and their dependencies as they are. But if you want to use Pelican plugins on Python 3, you must seek out and install compatible packages yourself.

For Typogrify and SmartyPants, on which Typogrify depends, I provide ready-made 2to3'd code:

For webassets, I also have 2to3'd code available:

https://github.com/dmdm/webassets/tree/py3k

But webassets still has issues. One is that the less-css compiler is not correctly invoked when I build the blog (e.g., with make html); I have to manually invoke the compiler afterwards:

lessc themes/pymblog/static/less/pymblog.less > output/theme/css/pymblog.css

Be aware that the 2to3'd code of aforementioned libraries runs on Python 3 only.

Testing

Testing on Python 2 is straightforward.

On Python 3, if you have installed the Python 3.x-compatible versions of the plugins, like shown in the previous chapter, manual testing with python -m unittest discover is also straightforward.

However, you must tell tox to use those Py3k libraries. If you forget this, tox will pull the regular packages from PyPI and the tests will fail.

Tell tox about the local packages thusly: enter the source directory of SmartyPants and run tox there. Do this again for Typogrify and webassets. SmartyPants and Typogrify do not have real tests, and webassets will fail noisily, but as a result we get these libraries neatly packaged in tox's distshare directory. And this is what we need to order to run tox for Pelican.

See also the comments in tox.ini for more detail.

Pelican 3.1 released

2012-12-03T00:00:00+01:00

Pelican development has progressed steadily over the last few months, and we're pleased to announce the release of version 3.1, which can be obtained via Crate.io or GitHub. This release contains some exciting new features; following is a summary of changes since the last 3.0.1 release.

Easier intra-site linking

Whether linking from one post to another or including locally-hosted images on a page, linking to intra-site resources has been significantly enhanced. In addition to improving reliability, it's now possible to link to a resource in your source content hierarchy instead of the generated hierarchy.

Find more information here: http://docs.getpelican.com/en/3.1.1/getting_started.html#linking-to-internal-content

Metadata extraction from filename

There is a new FILENAME_METADATA setting that adds support for metadata extraction from the filename via regular expressions. For example, if you would like to extract both the date and the post slug from the filename, you could set your FILENAME_METADATA setting to something like: '(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

Web asset processing moved to separate plugin

We are trying to move non-essential features out of the Pelican core and instead make them available as plugins. Web asset management is an example of this effort — we don't think this is a core component of Pelican, but it's still a useful feature and remains available to those who want to use it.

New gzip cache plugin

The gzip cache plugin allows generated text files to be compressed once during site generation and thus served without needing any server-side compression. This obviates the need for the web server to compress these text files on-the-fly, which can result in lower web server CPU utilization.

Basic functional tests restored

We now have a way to fully test Pelican's output, which helps us understand whether code changes break Pelican's intended behavior (for developers and for end users) while we are developing new features.

Template pages

If you want to generate custom pages besides your blog entries, you can use any Jinja template file with a path pointing to the file and the destination path for the generated file. For instance, if you have a blog with three static pages — a list of books, your resume, and a contact page — you could set them up via:

TEMPLATE_PAGES = {'src/books.html': 'dest/books.html',
                  'src/resume.html': 'dest/resume.html',
                  'src/contact.html': 'dest/contact.html'}

Feed improvements

The FEED_ALL_ATOM and FEED_ALL_RSS directives have been introduced as distinct from their FEED_ATOM and FEED_RSS brethren. The former show entries in all available language translations, while the latter only include entries written in the site's primary language.

Use folders as category

Until now, Pelican made the assumption that the folders used to organize your content should be used as the respective categories of the articles contained within. You now can configure this behavior via the USE_FOLDER_AS_CATEGORY setting.

New signals

Plugins now have additional signals at their disposal:

We now provide a generator_init signal that is sent when the generator is initialized. You'll receive the generator as an argument.
get_generators is invoked in Pelican.get_generator_classes and can return a Generator or several generators in a tuple or list. This is useful when you want to add your own generators.
article_generate_preread is invoked before an article is read in ArticlesGenerator.generate_context. Use this if the code needs to do something before every article is parsed.

Minor enhancements and fixes

Empty value for the AUTHOR setting is now allowed
Improved WordPress importing
Generated content doesn't contain as much blank lines as it did previously
New icon for Google+ and improvements to many others
Many small documentation and bug fixes not described here

On the horizon

We are working on moving plugins out of the main Pelican repository and into a separate repository.
We would like to implement measures designed to speed up site generation in order to reduce processing time.
In order to provide more regular updates on development progress, we intend to publish blog posts on a more frequent basis.

That's all for now. More to come soon! :-)

Pelican 3.0 released

2012-08-08T00:00:00+02:00

Today marks the release of Pelican 3.0! Some of the new features include:

Improved URL structure flexibility
Support for Typogrify
Support for LESS CSS
New development server script for previewing auto-regenerated changes
Improved recognition of alternate content filename extensions
... and much more!

Feel free to check out the package listing on PyPI or the project source at GitHub. If you want to give Pelican a spin, check out the Getting Started section of the Pelican Documentation.

Thanks to all the folks who helped out with testing, reporting bugs, fixing bugs, contributing features, and improving the documentation. Pelican's third major release would not be the same without you!

Pelican now has a blog of its own!

2012-07-23T00:00:00+02:00

Since Alexis started working on the project almost two years ago, a bunch of happy hackers have joined the effort to make Pelican an even better tool. Among these contributors are Kyle, Justin, and tBunnyMan, all of whom have done an amazing job recently.

We thought having a project blog would be a good way to keep users and developers updated on the status of Pelican's development.

We have version 3.0 coming soon with a lot of niceties that will hopefully be ready by the end of the week. Kyle is working on Py3k support for integration after 3.0, and we are getting rid of old things that don't make sense anymore for 3.0, so expect some changes. :)