PELICAN(1) PELICAN PELICAN(1)
NAME
pelican - pelican documentation
Pelican is a static site generator, written in Python. Highlights
include:
o Write your content directly with your editor of choice in
reStructuredText or Markdown formats
o Includes a simple CLI tool to (re)generate your site
o Easy to interface with distributed version control systems and web
hooks
o Completely static output is easy to host anywhere
Ready to get started? Check out the Quickstart guide.
FEATURES
Pelican's feature highlights include:
o Articles (e.g., blog posts) and pages (e.g., "About", "Projects",
"Contact")
o Integration with external services
o Site themes (created using Jinja2 templates)
o Publication of articles in multiple languages
o Generation of Atom and RSS feeds
o Code syntax highlighting
o Import existing content from WordPress, Dotclear, or RSS feeds
o Fast rebuild times thanks to content caching and selective output
writing
o Extensible via a rich plugin ecosystem: Pelican Plugins
WHY THE NAME PELICAN ?
"Pelican" is an anagram for calepin, which means "notebook" in French.
;)
SOURCE CODE
You can access the source code at:
https://github.com/getpelican/pelican
HOW TO GET HELP, CONTRIBUTE, OR PROVIDE FEEDBACK
See our feedback and contribution submission guidelines.
DOCUMENTATION
Quickstart
Reading through all the documentation is highly recommended, but for
the truly impatient, following are some quick steps to get started.
Installation
Install Pelican (and optionally Markdown if you intend to use it) on
Python >=3.8.1 by running the following command in your preferred
terminal, prefixing with sudo if permissions warrant:
python -m pip install "pelican[markdown]"
Create a project
First, choose a name for your project, create an appropriately-named
directory for your site, and switch to that directory:
mkdir -p ~/projects/yoursite
cd ~/projects/yoursite
Create a skeleton project via the pelican-quickstart command, which
begins by asking some questions about your site:
pelican-quickstart
For questions that have default values denoted in brackets, feel free
to use the Return key to accept those default values [1]. When asked
for your URL prefix, enter your domain name as indicated (e.g.,
https://example.com).
Create an article
You cannot run Pelican until you have created some content. Use your
preferred text editor to create your first article with the following
content:
Title: My First Review
Date: 2010-12-03 10:20
Category: Review
Following is a review of my favorite mechanical keyboard.
Given that this example article is in Markdown format, save it as
~/projects/yoursite/content/keyboard-review.md.
Generate your site
From your project root directory, run the pelican command to generate
your site:
pelican content
Your site has now been generated inside the output/ directory. (You may
see a warning related to feeds, but that is normal when developing
locally and can be ignored for now.)
Preview your site
Open a new terminal session, navigate to your project root directory,
and run the following command to launch Pelican's web server:
pelican --listen
Preview your site by navigating to http://localhost:8000/ in your
browser.
Continue reading the other documentation sections for more detail, and
check out the Pelican wiki's Tutorials page for links to
community-published tutorials.
Footnotes
[1] You can help localize default fields by installing the optional
tzlocal module.
Installing Pelican
Pelican currently runs best on >=3.8.1; earlier versions of Python are
not supported.
You can install Pelican via several different methods. The simplest is
via Pip:
python -m pip install pelican
Or, if you plan on using Markdown:
python -m pip install "pelican[markdown]"
(Keep in mind that some operating systems will require you to prefix
the above command with sudo in order to install Pelican system-wide.)
While the above is the simplest method, the recommended approach is to
create a virtual environment for Pelican via virtualenv before
installing Pelican. Assuming you have virtualenv installed, you can
then open a new terminal session and create a new virtual environment
for Pelican:
virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
source bin/activate
Once the virtual environment has been created and activated, Pelican
can be installed via python -m pip install pelican as noted above.
Alternatively, if you have the project source, you can install Pelican
using the distutils method:
cd path-to-Pelican-source
python setup.py install
If you have Git installed and prefer to install the latest
bleeding-edge version of Pelican rather than a stable release, use the
following command:
python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"
Once Pelican is installed, you can run pelican --help to see basic
usage options. For more detail, refer to the Publish section.
Optional packages
If you plan on using Markdown as a markup format, you can install
Pelican with Markdown support:
python -m pip install "pelican[markdown]"
Typographical enhancements can be enabled in your settings file, but
first the requisite Typogrify library must be installed:
python -m pip install typogrify
Dependencies
When Pelican is installed, the following dependent Python packages
should be automatically installed without any action on your part:
o feedgenerator, to generate the Atom feeds
o jinja2, for templating support
o pygments, for syntax highlighting
o docutils, for supporting reStructuredText as an input format
o blinker, an object-to-object and broadcast signaling system
o unidecode, for ASCII transliterations of Unicode text utilities
o MarkupSafe, for a markup-safe string implementation
o python-dateutil, to read the date metadata
Upgrading
If you installed a stable Pelican release via Pip and wish to upgrade
to the latest stable release, you can do so by adding --upgrade:
python -m pip install --upgrade pelican
If you installed Pelican via distutils or the bleeding-edge method,
simply perform the same step to install the most recent version.
Kickstart your site
Once Pelican has been installed, you can create a skeleton project via
the pelican-quickstart command, which begins by asking some questions
about your site:
pelican-quickstart
If run inside an activated virtual environment, pelican-quickstart will
look for an associated project path inside $VIRTUAL_ENV/.project. If
that file exists and contains a valid directory path, the new Pelican
project will be saved at that location. Otherwise, the default is the
current working directory. To set the new project path on initial
invocation, use: pelican-quickstart --path /your/desired/directory
Once you finish answering all the questions, your project will consist
of the following hierarchy (except for pages -- shown in parentheses
below -- which you can optionally add yourself if you plan to create
non-chronological content):
yourproject/
>>> content
| >>> (pages)
>>> output
>>> tasks.py
>>> Makefile
>>> pelicanconf.py # Main settings file
>>> publishconf.py # Settings to use when ready to publish
The next step is to begin to adding content to the content folder that
has been created for you.
Writing content
Articles and pages
Pelican considers "articles" to be chronological content, such as posts
on a blog, and thus associated with a date.
The idea behind "pages" is that they are usually not temporal in nature
and are used for content that does not change very often (e.g., "About"
or "Contact" pages).
You can find sample content in the repository at samples/content/.
File metadata
Pelican tries to be smart enough to get the information it needs from
the file system (for instance, about the category of your articles),
but some information you need to provide in the form of metadata inside
your files.
If you are writing your content in reStructuredText format, you can
provide this metadata in text files via the following syntax (give your
file the .rst extension):
My super title
##############
:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds
Author and tag lists may be semicolon-separated instead, which allows
you to write authors and tags containing commas:
:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan
Pelican implements an extension to reStructuredText to enable support
for the abbr HTML tag. To use it, write something like this in your
post:
This will be turned into :abbr:`HTML (HyperText Markup Language)`.
You can also use Markdown syntax (with a file ending in .md, .markdown,
.mkd, or .mdown). Markdown generation requires that you first
explicitly install the Python-Markdown package, which can be done via
pip install Markdown.
Pelican also supports Markdown Extensions, which might have to be
installed separately if they are not included in the default Markdown
package and can be configured and loaded via the MARKDOWN setting.
Metadata syntax for Markdown posts should follow this pattern:
Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds
This is the content of my super blog post.
You can also have your own metadata keys (so long as they don't
conflict with reserved metadata keywords) for use in your templates.
The following table contains a list of reserved metadata keywords:
+------------+----------------------------+
|Metadata | Description |
+------------+----------------------------+
|title | Title of the article or |
| | page |
+------------+----------------------------+
|date | Publication date (e.g., |
| | YYYY-MM-DD HH:SS) |
+------------+----------------------------+
|modified | Modification date (e.g., |
| | YYYY-MM-DD HH:SS) |
+------------+----------------------------+
|tags | Content tags, separated by |
| | commas |
+------------+----------------------------+
|keywords | Content keywords, |
| | separated by commas (HTML |
| | content only) |
+------------+----------------------------+
|category | Content category (one only |
| | -- not multiple) |
+------------+----------------------------+
|slug | Identifier used in URLs |
| | and translations |
+------------+----------------------------+
|author | Content author, when there |
| | is only one |
+------------+----------------------------+
|authors | Content authors, when |
| | there are multiple |
+------------+----------------------------+
|summary | Brief description of |
| | content for index pages |
+------------+----------------------------+
|lang | Content language ID (en, |
| | fr, etc.) |
+------------+----------------------------+
|translation | If content is a |
| | translation of another |
| | (true or false) |
+------------+----------------------------+
|status | Content status: draft, |
| | hidden, or published |
+------------+----------------------------+
|template | Name of template to use to |
| | generate content (without |
| | extension) |
+------------+----------------------------+
|save_as | Save content to this |
| | relative file path |
+------------+----------------------------+
|url | URL to use for this |
| | article/page |
+------------+----------------------------+
Readers for additional formats (such as AsciiDoc) are available via
plugins, which you can find via the Pelican Plugins collection as well
as the legacy pelican-plugins repository.
Pelican can also process HTML files ending in .html and .htm. Pelican
interprets the HTML in a very straightforward manner, reading metadata
from meta tags, the title from the title tag, and the body out from the
body tag:
You can change period_archives.month in the for statement to
period_archives.year or period_archives.day as appropriate, depending
on the time period granularity desired.
Objects
Detail objects attributes that are available and useful in templates.
Not all attributes are listed here, this is a selection of attributes
considered useful in a template.
Article
The string representation of an Article is the source_path attribute.
+---------------------+----------------------------+
|Attribute | Description |
+---------------------+----------------------------+
|author | The Author of this |
| | article. |
+---------------------+----------------------------+
|authors | A list of Authors of this |
| | article. |
+---------------------+----------------------------+
|category | The Category of this |
| | article. |
+---------------------+----------------------------+
|content | The rendered content of |
| | the article. |
+---------------------+----------------------------+
|date | Datetime object |
| | representing the article |
| | date. |
+---------------------+----------------------------+
|date_format | Either default date format |
| | or locale date format. |
+---------------------+----------------------------+
|default_template | Default template name. |
+---------------------+----------------------------+
|in_default_lang | Boolean representing if |
| | the article is written in |
| | the default language. |
+---------------------+----------------------------+
|lang | Language of the article. |
+---------------------+----------------------------+
|locale_date | Date formatted by the |
| | date_format. |
+---------------------+----------------------------+
|metadata | Article header metadata |
| | dict. |
+---------------------+----------------------------+
|save_as | Location to save the |
| | article page. |
+---------------------+----------------------------+
|slug | Page slug. |
+---------------------+----------------------------+
|source_path | Full system path of the |
| | article source file. |
+---------------------+----------------------------+
|relative_source_path | Relative path from PATH to |
| | the article source file. |
+---------------------+----------------------------+
|status | The article status, can be |
| | any of 'published' or |
| | 'draft'. |
+---------------------+----------------------------+
|summary | Rendered summary content. |
+---------------------+----------------------------+
|tags | List of Tag objects. |
+---------------------+----------------------------+
|template | Template name to use for |
| | rendering. |
+---------------------+----------------------------+
|title | Title of the article. |
+---------------------+----------------------------+
|translations | List of translations |
| | Article objects. |
+---------------------+----------------------------+
|url | URL to the article page. |
+---------------------+----------------------------+
Author / Category / Tag
The string representation of those objects is the name attribute.
+----------+--------------------------+
|Attribute | Description |
+----------+--------------------------+
|name | Name of this object [1]. |
+----------+--------------------------+
|page_name | Author page name. |
+----------+--------------------------+
|save_as | Location to save the |
| | author page. |
+----------+--------------------------+
|slug | Page slug. |
+----------+--------------------------+
|url | URL to the author page. |
+----------+--------------------------+
[1] for Author object, coming from :authors: or AUTHOR.
Page
The string representation of a Page is the source_path attribute.
+---------------------+----------------------------+
|Attribute | Description |
+---------------------+----------------------------+
|author | The Author of this page. |
+---------------------+----------------------------+
|content | The rendered content of |
| | the page. |
+---------------------+----------------------------+
|date | Datetime object |
| | representing the page |
| | date. |
+---------------------+----------------------------+
|date_format | Either default date format |
| | or locale date format. |
+---------------------+----------------------------+
|default_template | Default template name. |
+---------------------+----------------------------+
|in_default_lang | Boolean representing if |
| | the article is written in |
| | the default language. |
+---------------------+----------------------------+
|lang | Language of the article. |
+---------------------+----------------------------+
|locale_date | Date formatted by the |
| | date_format. |
+---------------------+----------------------------+
|metadata | Page header metadata dict. |
+---------------------+----------------------------+
|save_as | Location to save the page. |
+---------------------+----------------------------+
|slug | Page slug. |
+---------------------+----------------------------+
|source_path | Full system path of the |
| | page source file. |
+---------------------+----------------------------+
|relative_source_path | Relative path from PATH to |
| | the page source file. |
+---------------------+----------------------------+
|status | The page status, can be |
| | any of 'published', |
| | 'hidden' or 'draft'. |
+---------------------+----------------------------+
|summary | Rendered summary content. |
+---------------------+----------------------------+
|tags | List of Tag objects. |
+---------------------+----------------------------+
|template | Template name to use for |
| | rendering. |
+---------------------+----------------------------+
|title | Title of the page. |
+---------------------+----------------------------+
|translations | List of translations |
| | Article objects. |
+---------------------+----------------------------+
|url | URL to the page. |
+---------------------+----------------------------+
Feeds
The feed variables changed in 3.0. Each variable now explicitly lists
ATOM or RSS in the name. ATOM is still the default. Old themes will
need to be updated. Here is a complete list of the feed variables:
AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
FEED_ATOM
FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS
Inheritance
Since version 3.0, Pelican supports inheritance from the simple theme,
so you can re-use the simple theme templates in your own themes.
If one of the mandatory files in the templates/ directory of your theme
is missing, it will be replaced by the matching template from the
simple theme. So if the HTML structure of a template in the simple
theme is right for you, you don't have to write a new template from
scratch.
You can also extend templates from the simple theme in your own themes
by using the {% extends %} directive as in the following example:
{% extends "!simple/index.html" %}
{% extends "index.html" %}
Example
With this system, it is possible to create a theme with just two files.
base.html
The first file is the templates/base.html template:
{% extends "!simple/base.html" %}
{% block head %}
{{ super() }}
{% endblock %}
1. On the first line, we extend the base.html template from the simple
theme, so we don't have to rewrite the entire file.
2. On the third line, we open the head block which has already been
defined in the simple theme.
3. On the fourth line, the function super() keeps the content
previously inserted in the head block.
4. On the fifth line, we append a stylesheet to the page.
5. On the last line, we close the head block.
This file will be extended by all the other templates, so the
stylesheet will be linked from all pages.
style.css
The second file is the static/css/style.css CSS stylesheet:
body {
font-family : monospace ;
font-size : 100% ;
background-color : white ;
color : #111 ;
width : 80% ;
min-width : 400px ;
min-height : 200px ;
padding : 1em ;
margin : 5% 10% ;
border : thin solid gray ;
border-radius : 5px ;
display : block ;
}
a:link { color : blue ; text-decoration : none ; }
a:hover { color : blue ; text-decoration : underline ; }
a:visited { color : blue ; }
h1 a { color : inherit !important }
h2 a { color : inherit !important }
h3 a { color : inherit !important }
h4 a { color : inherit !important }
h5 a { color : inherit !important }
h6 a { color : inherit !important }
pre {
margin : 2em 1em 2em 4em ;
}
#menu li {
display : inline ;
}
#post-list {
margin-bottom : 1em ;
margin-top : 1em ;
}
Download
You can download this example theme here.
pelican-themes
Description
pelican-themes is a command line tool for managing themes for Pelican.
See Themes for settings related to themes.
Usage
pelican-themes [-h] [-l] [-i theme path [theme path ...]]
[-r theme name [theme name ...]]
[-s theme path [theme path ...]] [-v] [--version]
Optional arguments:
-h, --help
Show the help and exit
-l, --list
Show the themes already installed
-i theme_path, --install theme_path
One or more themes to install
-r theme_name, --remove theme_name
One or more themes to remove
-s theme_path, --symlink theme_path
Same as --install, but create a symbolic link instead of copying
the theme. Useful for theme development
-v, --verbose
Verbose output
--version
Print the version of this script
Examples
Listing the installed themes
With pelican-themes, you can see the available themes by using the -l
or --list option:
$ pelican-themes -l
notmyidea
two-column@
simple
$ pelican-themes --list
notmyidea
two-column@
simple
In this example, we can see there are three themes available:
notmyidea, simple, and two-column.
two-column is followed by an @ because this theme is not copied to the
Pelican theme path, but is instead just linked to it (see Creating
symbolic links for details about creating symbolic links).
Note that you can combine the --list option with the -v or --verbose
option to get more verbose output, like this:
$ pelican-themes -v -l
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple
Installing themes
You can install one or more themes using the -i or --install option.
This option takes as argument the path(s) of the theme(s) you want to
install, and can be combined with the --verbose option:
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
~/Dev/Python/pelican-themes/martyalchin \
--verbose
# pelican-themes -vi ~/Dev/Python/pelican-themes/two-column
Removing themes
The pelican-themes command can also remove themes from the Pelican
themes path. The -r or --remove option takes as argument the name(s) of
the theme(s) you want to remove, and can be combined with the --verbose
option.
# pelican-themes --remove two-column
# pelican-themes -r martyachin notmyidea-cmd -v
Creating symbolic links
pelican-themes can also install themes by creating symbolic links
instead of copying entire themes into the Pelican themes path.
To symbolically link a theme, you can use the -s or --symlink, which
works exactly as the --install option:
# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
In this example, the two-column theme is now symbolically linked to the
Pelican themes path, so we can use it, but we can also modify it
without having to reinstall it after each modification.
This is useful for theme development:
$ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ firefox /tmp/out/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-column/static/css/main.css
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-column/static/img/bg.png
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ vim ~/Dev/Pelican/pelican-themes/two-column/templates/index.html
$ pelican ~/Blog/content -o /tmp/out -t two-column
Doing several things at once
The --install, --remove and --symlink options are not mutually
exclusive, so you can combine them in the same command line to do more
than one operation at time, like this:
# pelican-themes --remove notmyidea-cms two-column \
--install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
--symlink ~/Dev/Python/pelican-themes/two-column \
--verbose
In this example, the theme notmyidea-cms is replaced by the theme
notmyidea-cms-fr
Importing an existing site
Description
pelican-import is a command-line tool for converting articles from
other software to reStructuredText or Markdown. The supported import
formats are:
o Blogger XML export
o Dotclear export
o Tumblr API
o WordPress XML export
o RSS/Atom feed
The conversion from HTML to reStructuredText or Markdown relies on
Pandoc. For Dotclear, if the source posts are written with Markdown
syntax, they will not be converted (as Pelican also supports Markdown).
NOTE:
Unlike Pelican, Wordpress supports multiple categories per article.
These are imported as a comma-separated string. You have to resolve
these manually, or use a plugin such as More Categories that enables
multiple categories per article.
Dependencies
pelican-import has some dependencies not required by the rest of
Pelican:
o BeautifulSoup4 and lxml, for WordPress and Dotclear import. Can be
installed like any other Python package (pip install BeautifulSoup4
lxml).
o Feedparser, for feed import (pip install feedparser).
o Pandoc, see the Pandoc site for installation instructions on your
operating system.
Usage
pelican-import [-h] [--blogger] [--dotclear] [--tumblr] [--wpfile] [--feed]
[-o OUTPUT] [-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--wp-custpost]
[--wp-attach] [--disable-slugs] [-b BLOGNAME]
input|api_key
Positional arguments
+--------+-----------------------------------+
|input | The input file to read |
+--------+-----------------------------------+
|api_key | (Tumblr only) api_key can be |
| | obtained from |
| | https://www.tumblr.com/oauth/apps |
+--------+-----------------------------------+
Optional arguments
-h, --help
Show this help message and exit
--blogger
Blogger XML export (default: False)
--dotclear
Dotclear export (default: False)
--tumblr
Tumblr API (default: False)
--wpfile
WordPress XML export (default: False)
--feed Feed to parse (default: False)
-o OUTPUT, --output OUTPUT
Output path (default: content)
-m MARKUP, --markup MARKUP
Output markup format: rst, markdown, or asciidoc (default:
rst)
--dir-cat
Put files in directories with categories name (default:
False)
--dir-page
Put files recognised as pages in "pages/" sub- directory
(blogger and wordpress import only) (default: False)
--filter-author
Import only post from the specified author
--strip-raw
Strip raw HTML code that can't be converted to markup such as
flash embeds or iframes (wordpress import only) (default:
False)
--wp-custpost
Put wordpress custom post types in directories. If used with
--dir-cat option directories will be created as
"/post_type/category/" (wordpress import only)
--wp-attach
Download files uploaded to wordpress as attachments. Files
will be added to posts as a list in the post header and links
to the files within the post will be updated. All files will
be downloaded, even if they aren't associated with a post.
Files will be downloaded with their original path inside the
output directory, e.g.
"output/wp-uploads/date/postname/file.jpg". (wordpress
import only) (requires an internet connection)
--disable-slugs
Disable storing slugs from imported posts within output. With
this disabled, your Pelican URLs may not be consistent with
your original posts. (default: False)
-b BLOGNAME, --blogname=BLOGNAME
Blog name used in Tumblr API
Examples
For Blogger:
$ pelican-import --blogger -o ~/output ~/posts.xml
For Dotclear:
$ pelican-import --dotclear -o ~/output ~/backup.txt
For Tumblr:
$ pelican-import --tumblr -o ~/output --blogname=
For WordPress:
$ pelican-import --wpfile -o ~/output ~/posts.xml
Tests
To test the module, one can use sample files:
o for WordPress:
https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
o for Dotclear:
http://media.dotaddict.org/tda/downloads/lorem-backup.txt
Frequently Asked Questions (FAQ)
Here are some frequently asked questions about Pelican.
What's the best way to communicate a problem, question, or suggestion?
Please read our feedback guidelines.
How can I help?
There are several ways to help out. First, you can communicate any
Pelican suggestions or problems you might have via Pelican Discussions.
Please first check the existing list of discussions and issues (both
open and closed) in order to avoid submitting topics that have already
been covered before.
If you want to contribute, please fork the Git repository, create a new
feature branch, make your changes, and issue a pull request. Someone
will review your changes as soon as possible. Please refer to the How
to Contribute section for more details.
You can also contribute by creating themes and improving the
documentation.
Is the Pelican settings file mandatory?
Configuration files are optional and are just an easy way to configure
Pelican. For basic operations, it's possible to specify options while
invoking Pelican via the command line. See pelican --help for more
information.
Changes to the settings file take no effect
When experimenting with different settings (especially the metadata
ones) caching may interfere and the changes may not be visible. In such
cases, ensure that caching is disabled via LOAD_CONTENT_CACHE = False
or use the --ignore-cache command-line switch.
I'm creating my own theme. How do I use Pygments for syntax highlighting?
Pygments adds some classes to the generated content. These classes are
used by themes to style code syntax highlighting via CSS. Specifically,
you can customize the appearance of your syntax highlighting via the
.highlight pre class in your theme's CSS file. To see how various
styles can be used to render Django code, for example, use the style
selector drop-down at top-right on the Pygments project demo site.
You can use the following example commands to generate a starting CSS
file from a Pygments built-in style (in this case, "monokai") and then
copy the generated CSS file to your new theme:
pygmentize -S monokai -f html -a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/
Don't forget to import your pygment.css file from your main CSS file.
How do I create my own theme?
Please refer to Themes.
I want to use Markdown, but I got an error.
If you try to generate Markdown content without first installing the
Markdown library, you may see a message that says No valid files found
in content. Markdown is not a hard dependency for Pelican, so if you
have content in Markdown format, you will need to explicitly install
the Markdown library. You can do so by typing the following command,
prepending sudo if permissions require it:
python -m pip install markdown
Can I use arbitrary metadata in my templates?
Yes. For example, to include a modified date in a Markdown post, one
could include the following at the top of the article:
Modified: 2012-08-08
For reStructuredText, this metadata should of course be prefixed with a
colon:
:Modified: 2012-08-08
This metadata can then be accessed in templates such as article.html
via:
{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}
If you want to include metadata in templates outside the article
context (e.g., base.html), the if statement should instead be:
{% if article and article.modified %}
How do I assign custom templates on a per-page basis?
It's as simple as adding an extra line of metadata to any page or
article that you want to have its own template. For example, this is
how it would be handled for content in reST format:
:template: template_name
For content in Markdown format:
Template: template_name
Then just make sure your theme contains the relevant template file
(e.g. template_name.html).
How can I override the generated URL of a specific page or article?
Include url and save_as metadata in any pages or articles that you want
to override the generated URL. Here is an example page in reST format:
Override url/save_as page
#########################
:url: override/url/
:save_as: override/url/index.html
With this metadata, the page will be written to override/url/index.html
and Pelican will use the URL override/url/ to link to this page.
How can I use a static page as my home page?
The override feature mentioned above can be used to specify a static
page as your home page. The following Markdown example could be stored
in content/pages/home.md:
Title: Welcome to My Site
URL:
save_as: index.html
Thank you for visiting. Welcome!
If the original blog index is still wanted, it can then be saved in a
different location by setting INDEX_SAVE_AS = 'blog_index.html' for the
'index' direct template.
What if I want to disable feed generation?
To disable feed generation, all feed settings should be set to None.
All but three feed settings already default to None, so if you want to
disable all feed generation, you only need to specify the following
settings:
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
The word None should not be surrounded by quotes. Please note that None
and '' are not the same thing.
I'm getting a warning about feeds generated without SITEURL being set
properly
RSS and Atom feeds require all URL links to be absolute. In order to
properly generate links in Pelican you will need to set SITEURL to the
full path of your site.
Feeds are still generated when this warning is displayed, but links
within may be malformed and thus the feed may not validate.
Can I force Atom feeds to show only summaries instead of article content?
Instead of having to open a separate browser window to read articles,
the overwhelming majority of folks who use feed readers prefer to read
content within the feed reader itself. Mainly for that reason, Pelican
does not support restricting Atom feeds to only contain summaries.
Unlike Atom feeds, the RSS feed specification does not include a
separate content field, so by default Pelican publishes RSS feeds that
only contain summaries (but can optionally be set to instead publish
full content RSS feeds). So the default feed generation behavior
provides users with a choice: subscribe to Atom feeds for full content
or to RSS feeds for just the summaries.
Is Pelican only suitable for blogs?
No. Pelican can be easily configured to create and maintain any type of
static site. This may require a little customization of your theme and
Pelican configuration. For example, if you are building a launch site
for your product and do not need tags on your site, you could remove
the relevant HTML code from your theme. You can also disable generation
of tag-related pages via:
TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''
Why does Pelican always write all HTML files even with content caching
enabled?
In order to reliably determine whether the HTML output is different
before writing it, a large part of the generation environment including
the template contexts, imported plugins, etc. would have to be saved
and compared, at least in the form of a hash (which would require
special handling of unhashable types), because of all the possible
combinations of plugins, pagination, etc. which may change in many
different ways. This would require a lot more processing time and
memory and storage space. Simply writing the files each time is a lot
faster and a lot more reliable.
However, this means that the modification time of the files changes
every time, so a rsync based upload will transfer them even if their
content hasn't changed. A simple solution is to make rsync use the
--checksum option, which will make it compare the file checksums in a
much faster way than Pelican would.
How to process only a subset of all articles?
It is often useful to process only e.g. 10 articles for debugging
purposes. This can be achieved by explicitly specifying only the
filenames of those articles in ARTICLE_PATHS. A list of such filenames
could be found using a command similar to cd content; find -name '*.md'
| head -n 10.
My tag cloud is missing/broken since I upgraded Pelican
In an ongoing effort to streamline Pelican, tag cloud generation has
been moved out of Pelican core and into a separate plugin. See the
Plugins documentation for further information about the Pelican plugin
system.
Since I upgraded Pelican my pages are no longer rendered
Pages were available to themes as lowercase pages and uppercase PAGES.
To bring this inline with the Templates and Variables section, PAGES
has been removed. This is quickly resolved by updating your theme to
iterate over pages instead of PAGES. Just replace:
{% for pg in PAGES %}
with something like:
{% for pg in pages %}
How can I stop Pelican from trying to parse my static files as content?
Pelican's article and page generators run before it's static generator.
That means if you use a setup similar to the default configuration,
where a static source directory is defined inside a *_PATHS setting,
all files that have a valid content file ending (.html, .rst, .md, ...)
will be treated as articles or pages before they get treated as static
files.
To circumvent this issue either use the appropriate *_EXCLUDES setting
or disable the offending reader via READERS if you don't need it.
Why is [arbitrary Markdown syntax] not supported?
Pelican does not directly handle Markdown processing and instead
delegates that task to the Python-Markdown project, the core of which
purposefully follows the original Markdown syntax rules and not the
myriad Markdown "flavors" that have subsequently propagated. That said,
Python-Markdown is quite modular, and the syntax you are looking for
may be provided by one of the many available Markdown Extensions.
Alternatively, some folks have created Pelican plugins that support
Markdown variants, so that may be your best choice if there is a
particular variant you want to use when writing your content.
Tips
Here are some tips about Pelican that you might find useful.
Custom 404 Pages
When a browser requests a resource that the web server cannot find, the
web server usually displays a generic "File not found" (404) error page
that can be stark and unsightly. One way to provide an error page that
matches the theme of your site is to create a custom 404 page (not an
article), such as this Markdown-formatted example stored in
content/pages/404.md:
Title: Not Found
Status: hidden
Save_as: 404.html
The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?
The next step is to configure your web server to display this custom
page instead of its default 404 page. For Nginx, add the following to
your configuration file's location block:
error_page 404 /404.html;
For Apache:
ErrorDocument 404 /404.html
For Amazon S3, first navigate to the Static Site Hosting menu in the
bucket settings on your AWS console. From there:
Error Document: 404.html
Publishing to GitHub Pages
If you use GitHub for your Pelican site you can publish your site to
GitHub Pages for free. Your site will be published to
https://.github.io if it's a user or organization site or to
https://.github.io/ if it's a project site. It's
also possible to use a custom domain with GitHub Pages.
There are two ways to publish a site to GitHub Pages:
1. Publishing from a branch: run pelican locally and push the output
directory to a special branch of your GitHub repo. GitHub will then
publish the contents of this branch to your GitHub Pages site.
2. Publishing with a custom GitHub Actions workflow: just push the
source files of your Pelican site to your GitHub repo's default
branch and have a custom GitHub Actions workflow run pelican for you
to generate the output directory and publish it to your GitHub Pages
site. This way you don't need to run pelican locally. You can even
edit your site's source files using GitHub's web interface and any
changes that you commit will be published.
Publishing a Project Site to GitHub Pages from a Branch
To publish a Pelican site as a Project Page you need to push the
content of the output dir generated by Pelican to a repository's
gh-pages branch on GitHub.
The excellent ghp-import, which can be installed with pip, makes this
process really easy.
For example, if the source of your Pelican site is contained in a
GitHub repository, and if you want to publish that Pelican site in the
form of Project Pages to this repository, you can then use the
following:
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push origin gh-pages
The ghp-import output command updates the local gh-pages branch with
the content of the output directory (creating the branch if it doesn't
already exist). The git push origin gh-pages command updates the remote
gh-pages branch, effectively publishing the Pelican site.
NOTE:
The github target of the Makefile (and the gh_pages task of
tasks.py) created by the pelican-quickstart command publishes the
Pelican site as Project Pages, as described above.
Publishing a User Site to GitHub Pages from a Branch
To publish a Pelican site in the form of User Pages, you need to push
the content of the output dir generated by Pelican to the master branch
of your .github.io repository on GitHub.
Again, you can take advantage of ghp-import:
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master
The git push command pushes the local gh-pages branch (freshly updated
by the ghp-import command) to the elemoine.github.io repository's
master branch on GitHub.
NOTE:
To publish your Pelican site as User Pages, feel free to adjust the
github target of the Makefile.
Another option for publishing to User Pages is to generate the output
files in the root directory of the project.
For example, your main project folder is .github.io and you
can create the Pelican project in a subdirectory called Pelican. Then
from inside the Pelican folder you can run:
$ pelican content -o .. -s pelicanconf.py
Now you can push the whole project .github.io to the master
branch of your GitHub repository:
$ git push origin master
(assuming origin is set to your remote repository).
Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
Pelican comes with a custom workflow for publishing a Pelican site. To
use it:
1. Enable GitHub Pages in your repo: go to Settings -> Pages and choose
GitHub Actions for the Source setting.
2. Commit a .github/workflows/pelican.yml file to your repo with these
contents:
name: Deploy to GitHub Pages
on:
push:
branches: ["main"]
workflow_dispatch:
jobs:
deploy:
uses: "getpelican/pelican/.github/workflows/github_pages.yml@master"
permissions:
contents: "read"
pages: "write"
id-token: "write"
with:
settings: "publishconf.py"
3. Go to the Actions tab in your repo
(https://github.com///actions) and you should
see a Deploy to GitHub Pages action running.
4. Once the action completes you should see your Pelican site deployed
at your repo's GitHub Pages URL: https://.github.io for a
user or organization site or
https://.github.io/> for a project site.
Notes:
o You don't need to set SITEURL in your Pelican settings: the workflow
will set it for you
o You don't need to commit your --output / OUTPUT_PATH directory
(output/) to git: the workflow will run pelican to build the output
directory for you on GitHub Actions
See GitHub's docs about reusable workflows for more information.
A number of optional inputs can be added to the with: block when
calling the workflow:
+-------------+----------+--------------------+--------+-----------+
|Name | Required | Description | Type | Default |
+-------------+----------+--------------------+--------+-----------+
|settings | Yes | The path to your | string | |
| | | Pelican settings | | |
| | | file (pelican's | | |
| | | --settings | | |
| | | option), for | | |
| | | example: | | |
| | | "publishconf.py" | | |
+-------------+----------+--------------------+--------+-----------+
|requirements | No | The Python | string | "pelican" |
| | | requirements to | | |
| | | install, for | | |
| | | example to enable | | |
| | | markdown and | | |
| | | typogrify use: | | |
| | | "pelican[markdown] | | |
| | | typogrify" or if | | |
| | | you have a | | |
| | | requirements file: | | |
| | | "-r | | |
| | | requirements.txt" | | |
+-------------+----------+--------------------+--------+-----------+
|output-path | No | Where to output | string | "output/" |
| | | the generated | | |
| | | files (pelican's | | |
| | | --output option) | | |
+-------------+----------+--------------------+--------+-----------+
For example:
with:
settings: "publishconf.py"
requirements: "pelican[markdown] typogrify"
output-path: "__output__/"
Custom 404 Pages
GitHub Pages will display the custom 404 page described above, as noted
in the relevant GitHub docs.
Update your site on each commit
To automatically update your Pelican site on each commit, you can
create a post-commit hook. For example, you can add the following to
.git/hooks/post-commit:
pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
Copy static files to the root of your site
To use a custom domain with GitHub Pages, you need to put the domain of
your site (e.g., blog.example.com) inside a CNAME file at the root of
your site. To do this, create the content/extra/ directory and add a
CNAME file to it. Then use the STATIC_PATHS setting to tell Pelican to
copy this file to your output directory. For example:
STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}
Note: use forward slashes, /, even on Windows.
You can also use the EXTRA_PATH_METADATA mechanism to place a
favicon.ico or robots.txt at the root of any site.
How to add YouTube or Vimeo Videos
The easiest way is to paste the embed code of the video from these
sites directly into your source content.
Alternatively, you can also use Pelican plugins like liquid_tags,
pelican_youtube, or pelican_vimeo to embed videos in your content.
Moreover, markup languages like reST and Markdown have plugins that let
you embed videos in the markup. You can use reST video directive for
reST or mdx_video plugin for Markdown.
Develop Locally Using SSL
Here's how you can set up your local pelican server to support SSL.
First, create a self-signed certificate and key using openssl (this
creates cert.pem and key.pem):
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
And use this command to launch the server (the server starts within
your output directory):
python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem
If you are using develop-server.sh, add this to the top:
CERT="$BASEDIR/cert.pem"
KEY="$BASEDIR/key.pem"
and modify the pelican.server line as follows:
$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &
Contributing and feedback guidelines
There are many ways to contribute to Pelican. You can improve the
documentation, add missing features, and fix bugs (or just report
them). You can also help out by reviewing and commenting on existing
issues.
Don't hesitate to fork Pelican and submit an issue or pull request on
GitHub. When doing so, please consider the following guidelines.
Filing issues
o Before you submit a new issue, try asking for help first.
o If determined to create a new issue, first search Pelican Discussions
and existing issues (open and closed) to see if your question has
already been answered previously.
How to get help
Before you ask for help, please make sure you do the following:
1. Read the documentation thoroughly. If in a hurry, at least use the
search field that is provided at top-left on the documentation
pages. Make sure you read the docs for the Pelican version you are
using.
2. Use a search engine (e.g., DuckDuckGo, Google) to search for a
solution to your problem. Someone may have already found a solution,
perhaps in the form of a 'plugins or a specific combination of
settings.
3. Try reproducing the issue in a clean environment, ensuring you are
using:
o latest Pelican release (or an up-to-date Git clone of Pelican master)
o latest releases of libraries used by Pelican
o no plugins or only those related to the issue
NOTE: The most common sources of problems are anomalies in (1) themes,
(2) plugins, (3) settings files, and (4) make/invoke automation
wrappers. If you can't reproduce your problem when using the following
steps to generate your site, then the problem is almost certainly with
one of the above-listed elements (and not Pelican itself):
cd ~/projects/your-site
git clone https://github.com/getpelican/pelican ~/projects/pelican
pelican content -s ~/projects/pelican/samples/pelican.conf.py -t ~/projects/pelican/pelican/themes/notmyidea
If you can generate your site without problems using the steps above,
then your problem is unlikely to be caused by Pelican itself, and
therefore please consider reaching out to the maintainers of the
plugins/theme you are using instead of raising the topic with the
Pelican core community.
If despite the above efforts you still cannot resolve your problem, be
sure to include in your inquiry the following information, preferably
in the form of links to content uploaded to a paste service, GitHub
repository, or other publicly-accessible location:
o Describe what version of Pelican you are running (output of pelican
--version or the HEAD commit hash if you cloned the repo) and how
exactly you installed it (the full command you used, e.g. python -m
pip install pelican).
o If you are looking for a way to get some end result, prepare a
detailed description of what the end result should look like
(preferably in the form of an image or a mock-up page) and explain in
detail what you have done so far to achieve it.
o If you are trying to solve some issue, prepare a detailed description
of how to reproduce the problem. If the issue cannot be easily
reproduced, it cannot be debugged by developers or volunteers.
Describe only the minimum steps necessary to reproduce it (no extra
plugins, etc.).
o Upload your settings file or any other custom code that would enable
people to reproduce the problem or to see what you have already tried
to achieve the desired end result.
o Upload detailed and complete output logs and backtraces (remember to
add the --debug flag: pelican --debug content [...])
Once the above preparation is ready, you can post your query as a new
thread in Pelican Discussions. Remember to include all the information
you prepared.
Contributing code
Before you submit a contribution, please ask whether it is desired so
that you don't spend a lot of time working on something that would be
rejected for a known reason. Consider also whether your new feature
might be better suited as a 'plugins -- you can ask for help to make
that determination.
Also, if you intend to submit a pull request to address something for
which there is no existing issue, there is no need to create a new
issue and then immediately submit a pull request that closes it. You
can submit the pull request by itself.
Using Git and GitHub
o Create a new branch specific to your change (as opposed to making
your commits in the master branch).
o Don't put multiple unrelated fixes/features in the same branch / pull
request. For example, if you're working on a new feature and find a
bugfix that doesn't require your new feature, make a new distinct
branch and pull request for the bugfix. Similarly, any proposed
changes to code style formatting should be in a completely separate
pull request.
o Add a RELEASE.md file in the root of the project that contains the
release type (major, minor, patch) and a summary of the changes that
will be used as the release changelog entry. For example:
Release type: minor
Reload browser window upon changes to content, settings, or theme
o Check for unnecessary whitespace via git diff --check before
committing.
o First line of your commit message should start with present-tense
verb, be 50 characters or less, and include the relevant issue
number(s) if applicable. Example: Ensure proper PLUGIN_PATH
behavior. Refs #428. If the commit completely fixes an existing bug
report, please use Fixes #585 or Fix #585 syntax (so the relevant
issue is automatically closed upon PR merge).
o After the first line of the commit message, add a blank line and then
a more detailed explanation (when relevant).
o Squash your commits to eliminate merge commits and ensure a clean and
readable commit history.
o After you have issued a pull request, the continuous integration (CI)
system will run the test suite on all supported Python versions and
check for code style compliance. If any of these checks fail, you
should fix them. (If tests fail on the CI system but seem to pass
locally, ensure that local test runs aren't skipping any tests.)
Contribution quality standards
o Adhere to the project's code style standards. See: Development
Environment
o Ensure your code is compatible with the officially-supported Python
releases.
o Add docs and tests for your changes. Undocumented and untested
features will not be accepted.
o Run all the tests on all versions of Python supported by Pelican to
ensure nothing was accidentally broken.
Check out our Git Tips page or ask for help if you need assistance or
have any questions about these guidelines.
Setting up the development environment
While there are many ways to set up one's development environment, the
following instructions will utilize Pip and PDM. These tools facilitate
managing virtual environments for separate Python projects that are
isolated from one another, so you can use different packages (and
package versions) for each.
Please note that Python >=3.8.1 is required for Pelican development.
(Optional) If you prefer to install PDM once for use with multiple
projects, you can install it via:
curl -sSL https://pdm.fming.dev/install-pdm.py | python3 -
Point your web browser to the Pelican repository and tap the Fork
button at top-right. Then clone the source for your fork and add the
upstream project as a Git remote:
mkdir ~/projects
git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican
cd ~/projects/pelican
git remote add upstream https://github.com/getpelican/pelican.git
While PDM can dynamically create and manage virtual environments, we're
going to manually create and activate a virtual environment:
mkdir ~/virtualenvs && cd ~/virtualenvs
python3 -m venv pelican
source ~/virtualenvs/pelican/*/activate
Install the needed dependencies and set up the project:
python -m pip install invoke
invoke setup
Your local environment should now be ready to go!
Development
Once Pelican has been set up for local development, create a topic
branch for your bug fix or feature:
git checkout -b name-of-your-bugfix-or-feature
Now you can make changes to Pelican, its documentation, and/or other
aspects of the project.
Running the test suite
Each time you make changes to Pelican, there are two things to do
regarding tests: check that the existing tests pass, and add tests for
any new features or bug fixes. The tests are located in pelican/tests,
and you can run them via:
invoke tests
(For more on Invoke, see invoke -l to list tasks, or
https://pyinvoke.org for documentation.)
In addition to running the test suite, it is important to also ensure
that any lines you changed conform to code style guidelines. You can
check that via:
invoke lint
If code style violations are found in lines you changed, correct those
lines and re-run the above lint command until they have all been fixed.
You do not need to address style violations, if any, for code lines you
did not touch.
After making your changes and running the tests, you may see a test
failure mentioning that "some generated files differ from the expected
functional tests output." If you have made changes that affect the HTML
output generated by Pelican, and the changes to that output are
expected and deemed correct given the nature of your changes, then you
should update the output used by the functional tests. To do so, make
sure you have both en_EN.utf8 and fr_FR.utf8 locales installed, and
then run the following command:
invoke update-functional-tests
You may also find that some tests are skipped because some dependency
(e.g., Pandoc) is not installed. This does not automatically mean that
these tests have passed; you should at least verify that any skipped
tests are not affected by your changes.
You should run the test suite under each of the supported versions of
Python. This is best done by creating a separate Python environment
for each version. Tox is a useful tool to automate running tests
inside virtualenv environments.
Building the docs
If you make changes to the documentation, you should build and inspect
your changes before committing them:
invoke docserve
Open http://localhost:8000 in your browser to review the documentation.
While the above task is running, any changes you make and save to the
documentation should automatically appear in the browser, as it
live-reloads when it detects changes to the documentation source files.
Plugin development
To create a new Pelican plugin, please refer to the plugin template
repository for detailed instructions.
If you want to contribute to an existing Pelican plugin, follow the
steps above to set up Pelican for local development, and then create a
directory to store cloned plugin repositories:
mkdir -p ~/projects/pelican-plugins
Assuming you wanted to contribute to the Simple Footnotes plugin, you
would first browse to the Simple Footnotes repository on GitHub and tap
the Fork button at top-right. Then clone the source for your fork and
add the upstream project as a Git remote:
git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes
cd ~/projects/pelican-plugins/simple-footnotes
git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git
Install the needed dependencies and set up the project:
invoke setup
Create a topic branch for your plugin bug fix or feature:
git checkout -b name-of-your-bugfix-or-feature
After writing new tests for your plugin changes, run the plugin test
suite and check for code style compliance via:
invoke tests
invoke lint
If style violations are found, many of them can be addressed
automatically via:
invoke format
If style violations are found even after running the above
auto-formatters, you will need to make additional manual changes until
invoke lint no longer reports any code style violations.
Submitting your changes
Assuming linting validation and tests pass, add a RELEASE.md file in
the root of the project that contains the release type (major, minor,
patch) and a summary of the changes that will be used as the release
changelog entry. For example:
Release type: patch
Fix browser reloading upon changes to content, settings, or theme
Commit your changes and push your topic branch:
git add .
git commit -m "Your detailed description of your changes"
git push origin name-of-your-bugfix-or-feature
Finally, browse to your repository fork on GitHub and submit a pull
request.
Logging tips
Try to use logging with appropriate levels.
For logging messages that are not repeated, use the usual Python way:
# at top of file
import logging
logger = logging.getLogger(__name__)
# when needed
logger.warning("A warning with %s formatting", arg_to_be_formatted)
Do not format log messages yourself. Use %s formatting in messages and
pass arguments to logger. This is important, because the Pelican logger
will preprocess some arguments, such as exceptions.
Limiting extraneous log messages
If the log message can occur several times, you may want to limit the
log to prevent flooding. In order to do that, use the extra keyword
argument for the logging message in the following format:
logger.warning("A warning with %s formatting", arg_to_be_formatted,
extra={'limit_msg': 'A generic message for too many warnings'})
Optionally, you can also set 'limit_args' as a tuple of arguments in
extra dict if your generic message needs formatting.
Limit is set to 5, i.e, first four logs with the same 'limit_msg' are
outputted normally but the fifth one will be logged using 'limit_msg'
(and 'limit_args' if present). After the fifth, corresponding log
messages will be ignored.
For example, if you want to log missing resources, use the following
code:
for resource in resources:
if resource.is_missing:
logger.warning(
'The resource %s is missing', resource.name,
extra={'limit_msg': 'Other resources were missing'})
The log messages will be displayed as follows:
WARNING: The resource prettiest_cat.jpg is missing
WARNING: The resource best_cat_ever.jpg is missing
WARNING: The resource cutest_cat.jpg is missing
WARNING: The resource lolcat.jpg is missing
WARNING: Other resources were missing
Outputting traceback in the logs
If you're logging inside an except block, you may want to provide the
traceback information as well. You can do that by setting exc_info
keyword argument to True during logging. However, doing so by default
can be undesired because tracebacks are long and can be confusing to
regular users. Try to limit them to --debug mode like the following:
try:
some_action()
except Exception as e:
logger.error('Exception occurred: %s', e,
exc_info=settings.get('DEBUG', False))
Pelican internals
This section describe how Pelican works internally. As you'll see, it's
quite simple, but a bit of documentation doesn't hurt. :)
You can also find in the Some history about Pelican section an excerpt
of a report the original author wrote with some software design
information.
Overall structure
What Pelican does is take a list of files and process them into some
sort of output. Usually, the input files are reStructuredText and
Markdown files, and the output is a blog, but both input and output can
be anything you want.
The logic is separated into different classes and concepts:
o Writers are responsible for writing files: .html files, RSS feeds,
and so on. Since those operations are commonly used, the object is
created once and then passed to the generators.
o Readers are used to read from various formats (HTML, Markdown and
reStructuredText for now, but the system is extensible). Given a
file, they return metadata (author, tags, category, etc.) and content
(HTML-formatted).
o Generators generate the different outputs. For instance, Pelican
comes with ArticlesGenerator and PageGenerator. Given a
configuration, they can do whatever they want. Most of the time, it's
generating files from inputs.
o Pelican also uses templates, so it's easy to write your own theme.
The syntax is Jinja2 and is very easy to learn, so don't hesitate to
jump in and build your own theme.
How to implement a new reader?
Is there an awesome markup language you want to add to Pelican? Well,
the only thing you have to do is to create a class with a read method
that returns HTML content and some metadata.
Take a look at the Markdown reader:
from pelican.readers import BaseReader
from pelican.utils import pelican_open
from markdown import Markdown
class MarkdownReader(BaseReader):
enabled = True
def read(self, source_path):
"""Parse content and metadata of markdown files"""
with pelican_open(source_path) as text:
md_extensions = {'markdown.extensions.meta': {},
'markdown.extensions.codehilite': {}}
md = Markdown(extensions=md_extensions.keys(),
extension_configs=md_extensions)
content = md.convert(text)
metadata = {}
for name, value in md.Meta.items():
name = name.lower()
meta = self.process_metadata(name, value[0])
metadata[name] = meta
return content, metadata
Simple, isn't it?
If your new reader requires additional Python dependencies, then you
should wrap their import statements in a try...except block. Then
inside the reader's class, set the enabled class attribute to mark
import success or failure. This makes it possible for users to continue
using their favourite markup method without needing to install modules
for formats they don't use.
How to implement a new generator?
Generators have two important methods. You're not forced to create
both; only the existing ones will be called.
o generate_context, that is called first, for all the generators. Do
whatever you have to do, and update the global context if needed.
This context is shared between all generators, and will be passed to
the templates. For instance, the PageGenerator generate_context
method finds all the pages, transforms them into objects, and
populates the context with them. Be careful not to output anything
using this context at this stage, as it is likely to change by the
effect of other generators.
o generate_output is then called. And guess what is it made for? Oh,
generating the output. :) It's here that you may want to look at the
context and call the methods of the writer object that is passed as
the first argument of this function. In the PageGenerator example,
this method will look at all the pages recorded in the global context
and output a file on the disk (using the writer method write_file)
for each page encountered.
Some history about Pelican
WARNING:
This page comes from a report the original author (Alexis Metaireau)
wrote right after writing Pelican, in December 2010. The information
may not be up-to-date.
Pelican is a simple static blog generator. It parses markup files
(Markdown or reStructuredText for now) and generates an HTML folder
with all the files in it. I've chosen to use Python to implement
Pelican because it seemed to be simple and to fit to my needs. I did
not wanted to define a class for each thing, but still wanted to keep
my things loosely coupled. It turns out that it was exactly what I
wanted. From time to time, thanks to the feedback of some users, it
took me a very few time to provide fixes on it. So far, I've
re-factored the Pelican code by two times; each time took less than 30
minutes.
Use case
I was previously using WordPress, a solution you can host on a web
server to manage your blog. Most of the time, I prefer using markup
languages such as Markdown or reStructuredText to type my articles. To
do so, I use vim. I think it is important to let the people choose the
tool they want to write the articles. In my opinion, a blog manager
should just allow you to take any kind of input and transform it to a
weblog. That's what Pelican does. You can write your articles using the
tool you want, and the markup language you want, and then generate a
static HTML weblog. [image]
To be flexible enough, Pelican has template support, so you can easily
write your own themes if you want to.
Design process
Pelican came from a need I have. I started by creating a single file
application, and I have make it grow to support what it does by now. To
start, I wrote a piece of documentation about what I wanted to do.
Then, I created the content I wanted to parse (the reStructuredText
files) and started experimenting with the code. Pelican was 200 lines
long and contained almost ten functions and one class when it was first
usable.
I have been facing different problems all over the time and wanted to
add features to Pelican while using it. The first change I have done
was to add the support of a settings file. It is possible to pass the
options to the command line, but can be tedious if there is a lot of
them. In the same way, I have added the support of different things
over time: Atom feeds, multiple themes, multiple markup support, etc.
At some point, it appears that the "only one file" mantra was not good
enough for Pelican, so I decided to rework a bit all that, and split
this in multiple different files.
I've separated the logic in different classes and concepts:
o writers are responsible of all the writing process of the files.
They are responsible of writing .html files, RSS feeds and so on.
Since those operations are commonly used, the object is created once,
and then passed to the generators.
o readers are used to read from various formats (Markdown and
reStructuredText for now, but the system is extensible). Given a
file, they return metadata (author, tags, category, etc) and content
(HTML formatted).
o generators generate the different outputs. For instance, Pelican
comes with an ArticlesGenerator and PagesGenerator, into others.
Given a configuration, they can do whatever you want them to do. Most
of the time it's generating files from inputs (user inputs and
files).
I also deal with contents objects. They can be Articles, Pages, Quotes,
or whatever you want. They are defined in the contents.py module and
represent some content to be used by the program.
In more detail
Here is an overview of the classes involved in Pelican. [image]
The interface does not really exist, and I have added it only to
clarify the whole picture. I do use duck typing and not interfaces.
Internally, the following process is followed:
o First of all, the command line is parsed, and some content from the
user is used to initialize the different generator objects.
o A context is created. It contains the settings from the command line
and a settings file if provided.
o The generate_context method of each generator is called, updating the
context.
o The writer is created and given to the generate_output method of each
generator.
I make two calls because it is important that when the output is
generated by the generators, the context will not change. In other
words, the first method generate_context should modify the context,
whereas the second generate_output method should not.
Then, it is up to the generators to do what the want, in the
generate_context and generate_content method. Taking the
ArticlesGenerator class will help to understand some others concepts.
Here is what happens when calling the generate_context method:
o Read the folder "path", looking for restructured text files, load
each of them, and construct a content object (Article) with it. To do
so, use Reader objects.
o Update the context with all those articles.
Then, the generate_content method uses the context and the writer to
generate the wanted output.
Release history
4.9.1 - 2023-11-15
o Ensure tzdata dependency is installed on Windows
4.9.0 - 2023-11-12
o Upgrade code to new minimum supported Python version: 3.8
o Settings support for pathlib.Path (#2758)
o Various improvements to Simple theme (#2976 & #3234)
o Use Furo as Sphinx documentation theme (#3023)
o Default to 100 articles maximum in feeds (#3127)
o Add period_archives common context variable (#3148)
o Use watchfiles as the file-watching backend (#3151)
o Add GitHub Actions workflow for GitHub Pages (#3189)
o Allow dataclasses in settings (#3204)
o Switch build tool to PDM instead of Setuptools/Poetry (#3220)
o Provide a plugin_enabled Jinja test for themes (#3235)
o Preserve connection order in Blinker (#3238)
o Remove social icons from default notmyidea theme (#3240)
o Remove unreliable WRITE_SELECTED feature (#3243)
o Importer: Report broken embedded video links when importing from
Tumblr (#3177)
o Importer: Remove newline addition when iterating Photo post types
(#3178)
o Importer: Force timestamp conversion in Tumblr importer to be UTC
with offset (#3221)
o Importer: Use tempfile for intermediate HTML file for Pandoc (#3221)
o Switch linters to Ruff (#3223)
4.8.0 - 2022-07-11
o Use JSON values for extra settings in Invoke tasks template (#2994)
o Add content tag for links, which can help with things like Twitter
social cards (#3001)
o Improve word count behavior when generating summary (#3002)
4.7.2 - 2022-02-09
o Fix incorrect parsing of parameters specified via -e /
--extra-settings option flags (#2938)
o Add categories.html template to default theme (#2973)
o Document how to use plugins to inject content (#2922)
4.7.1 - 2021-10-12
o Extend rich logging to server component (#2927)
o Fix an issue where metadata flagged to be discarded was being cached
(#2926)
o Adjust suffix in server to allow redirection when needed (#2931)
o Add MIME types for web fonts (#2929)
o Distribute sample data used to run tests (#2935)
o Add Python 3.10 to test matrix
4.7.0 - 2021-10-01
o Improve default theme rendering on mobile and other small screen
devices (#2914)
o Add support for hidden articles (#2866)
o Improve word count behavior when generating summary CJK & other
locales (#2864)
o Add progress spinner during generation (#2869) and richer logging
(#2897), both via Rich
o Invoke tasks serve and livereload now auto-open a web browser
pointing to the locally-served web site (#2764)
o Support some date format codes used by ISO dates (#2902)
o Document how to add a new writer (#2901)
4.6.0 - 2021-03-23
o Add new URL pattern to PAGINATION_PATTERNS for the last page in the
list (#1401)
o Speed up livereload Invoke task via caching (#2847)
o Ignore None return value from get_generators signal (#2850)
o Relax dependency minimum versions and remove upper bounds
4.5.4 - 2021-01-04
Replace plugin definitions in settings with string representations
after registering, so they can be cached correctly (#2828).
4.5.3 - 2020-12-01
Fix a mistake made in PR #2821
4.5.2 - 2020-11-22
Improve logging of generators and writer loaders
4.5.1 - 2020-11-02
o Refactor intra-site link discovery in order to match more
permissively (#2646)
o Fix plugins running twice in auto-reload mode (#2817)
o Add notice to use from pelican import signals instead of import
pelican.signals (#2805)
4.5.0 - 2020-08-20
o Add namespace plugin support; list plugins via pelican-plugins
command
o Override settings via -e / --extra-settings CLI option flags
o Add settings for custom Jinja globals and tests
o Customize article summary ellipsis via SUMMARY_END_SUFFIX setting
o Customize Typogrify dash handling via new TYPOGRIFY_DASHES setting
o Support Unicode when generating slugs
o Support Asciidoc .adoc file generation in Pelican importer
o Improve user experience when pelican --listen web server is quit
o Improve Invoke tasks template
o Include tests in source distributions
o Switch CI from Travis to GitHub Actions
o Remove support for Python 2.7
4.2.0 - 2019-10-17
o Support inline SVGs; don't treat titles in SVGs as HTML titles
o Add category to feeds (in addition to tags)
o Improve content metadata field docs
o Add docs for including other Markdown/reST files in content
4.1.3 - 2019-10-09
o Fix quick-start docs regarding pelican --listen
o Set default listen address to 127.0.0.1
o Add extra/optional Markdown dependency to setup.py
o Use correct SSH port syntax for rsync in tasks.py
o Place all deprecated settings handling together
o Add related project URLs for display on PyPI
o Skip some tests on Windows that can't pass due to filesystem
differences
4.1.2 - 2019-09-23
Fix pelican.settings.load_source to avoid caching issues - PR #2621
4.1.1 - 2019-08-23
o Add AutoPub to auto-publish releases on PR merge
o Add CSS classes for reStructuredText figures
o Pass argv to Pelican main entrypoint
o Set default content status to a blank string rather than None
4.1.0 - 2019-07-14
o Live browser reload upon changed files (provided via Invoke task)
o Add pyproject.toml, managed by Poetry
o Support for invoking python -m pelican
o Add relative source path attribute to content
o Allow directories in EXTRA_PATH_METADATA
o Add all_articles variable to period pages (for recent posts
functionality)
o Improve debug mode output
o Remove blank or duplicate summaries from Atom feed
o Fix bugs in pagination, pelican-import, pelican-quickstart, and feed
importer
4.0.1 (2018-11-30)
o Refactor pelican.server logging
o Fix bug in which all static files were processed as "draft"
o Bug fixes for Invoke/Makefile automation, Importer, and other
miscellanea
If upgrading from 3.7.x or earlier, please note that slug-related
settings in 4.0+ use {slug} and/or {lang} rather than %s. If %s-style
settings are encountered, Pelican will emit a warning and fall back to
the default setting. Some user-submitted themes might try to format
setting values but fail upon site build with a TypeError. In such
cases, the theme needs to be updated. For example, instead of
TAG_FEED_ATOM|format(tag.slug), use TAG_FEED_ATOM.format(slug=tag.slug)
4.0.0 (2018-11-13)
o Replace develop_server.sh script with pelican --listen
o Improved copy/link behavior for large static files (e.g., videos)
o New {static} syntax to link to static content; content linked to by
{static} and {attach} is automatically copied over even if not in
STATIC_PATHS
o Pages can now have draft status
o Show current settings via new --print-settings flag
o All settings for slugs now use {slug} and/or {lang} rather than %s.
If %s-style settings are encountered, Pelican will emit a warning and
fallback to the default setting.
o New signals: feed_generated and page_generated_write_page
o Replace Fabric with Invoke and fabfile.py template with tasks.py
o Replace PAGINATED_DIRECT_TEMPLATES by PAGINATED_TEMPLATES, extending
control over pagination to all templates and making page size
variable
o Replace SLUG_SUBSTITUTIONS (and friends) by SLUG_REGEX_SUBSTITUTIONS
for more finegrained control
o '{base_name}' value in PAGINATION_PATTERNS setting no longer strips
'bar' from 'foo/bar.html' (unless 'bar' == 'index').
o ARTICLE_ORDER_BY and PAGE_ORDER_BY now also affect 1) category, tag
and author pages 2) feeds 3) draft and hidden articles and pages
o New ARTICLE_TRANSLATION_ID and PAGE_TRANSLATION_ID settings to
specify metadata attributes used to identify/disable translations
o Make the HTML reader parse multiple occurrences of metadata tags as a
list
o New Blogger XML backup importer
o Wordpress importer now updates file links to point to local copies if
the files were downloaded with --wp-attach.
o Importer no longer inserts extra newlines, to prevent breaking of
HTML attributes.
o Pelican server now prioritises foo.html and foo/index.html over foo/
when resolving foo.
3.7.1 (2017-01-10)
o Fix locale issues in Quickstart script
o Specify encoding for README and CHANGELOG in setup.py
3.7.0 (2016-12-12)
o Atom feeds output in addition to
o Atom feeds use for the original publication date and
for modifications
o Simplify Atom feed ID generation and support URL fragments
o Produce category feeds with category-specific titles
o RSS feeds now default to summary instead of full content; set
RSS_FEED_SUMMARY_ONLY = False to revert to previous behavior
o Replace MD_EXTENSIONS with MARKDOWN setting
o Replace JINJA_EXTENSIONS with more-robust JINJA_ENVIRONMENT setting
o Improve summary truncation logic to handle special characters and
tags that span multiple lines, using HTML parser instead of regular
expressions
o Include summary when looking for intra-site link substitutions
o Link to authors and index via {author}name and {index} syntax
o Override widget names via LINKS_WIDGET_NAME and SOCIAL_WIDGET_NAME
o Add INDEX_SAVE_AS option to override default index.html value
o Remove PAGES context variable for themes in favor of pages
o SLUG_SUBSTITUTIONS now accepts 3-tuple elements, allowing URL slugs
to contain non-alphanumeric characters
o Tag and category slugs can be controlled with greater precision using
the TAG_SUBSTITUTIONS and CATEGORY_SUBSTITUTIONS settings
o Author slugs can be controlled with greater precision using the
AUTHOR_SUBSTITUTIONS setting
o DEFAULT_DATE can be defined as a string
o Use mtime instead of ctime when DEFAULT_DATE = 'fs'
o Add --fatal=errors|warnings option for use with continuous
integration
o When using generator-level caching, ensure previously-cached files
are processed instead of just new files.
o Add Python and Pelican version information to debug output
o Improve compatibility with Python 3.5
o Comply with and enforce PEP8 guidelines
o Replace tables in settings documentation with data:: directives
3.6.3 (2015-08-14)
o Fix permissions issue in release tarball
3.6.2 (2015-08-01)
o Fix installation errors related to Unicode in tests
o Don't show pagination in notmyidea theme if there's only one page
o Make hidden pages available in context
o Improve URLWrapper comparison
3.6.0 (2015-06-15)
o Disable caching by default in order to prevent potential confusion
o Improve caching behavior, replacing pickle with cpickle
o Allow Markdown or reST content in metadata fields other than summary
o Support semicolon-separated author/tag lists
o Improve flexibility of article sorting
o Add --relative-urls argument
o Support devserver listening on addresses other than localhost
o Unify HTTP server handlers to pelican.server throughout
o Handle intra-site links to draft posts
o Move tag_cloud from core to plugin
o Load default theme's external resources via HTTPS
o Import drafts from WordPress XML
o Improve support for Windows users
o Enhance logging and test suite
o Clean up and refactor codebase
o New signals: all_generators_finalized and page_writer_finalized
3.5.0 (2014-11-04)
o Introduce ARTICLE_ORDER_BY and PAGE_ORDER_BY settings to control the
order of articles and pages.
o Include time zone information in dates rendered in templates.
o Expose the reader name in the metadata for articles and pages.
o Add the ability to store static files along with content in the same
directory as articles and pages using {attach} in the path.
o Prevent Pelican from raising an exception when there are duplicate
pieces of metadata in a Markdown file.
o Introduce the TYPOGRIFY_IGNORE_TAGS setting to add HTML tags to be
ignored by Typogrify.
o 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.
o Ensure feed generation is correctly disabled during quickstart
configuration.
o Fix PAGE_EXCLUDES and ARTICLE_EXCLUDES from incorrectly matching
sub-directories.
o Introduce STATIC_EXCLUDE setting to add static file excludes.
o Fix an issue when using PAGINATION_PATTERNS while RELATIVE_URLS is
enabled.
o Fix feed generation causing links to use the wrong language for month
names when using other locales.
o Fix an issue where the authors list in the simple template wasn't
correctly formatted.
o Fix an issue when parsing non-string URLs from settings.
o Improve consistency of debug and warning messages.
3.4.0 (2014-07-01)
o Speed up content generation via new caching mechanism
o Add selective post generation (instead of always building entire
site)
o Many documentation improvements, including switching to prettier RtD
theme
o Add support for multiple content and plugin paths
o Add :modified: metadata field to complement :date:. Used to specify
the last date and time an article was updated independently from the
date and time it was published.
o Add support for multiple authors via new :authors: metadata field
o Watch for changes in static directories when in auto-regeneration
mode
o Add filters to limit log output when desired
o Add language support to drafts
o Add SLUGIFY_SOURCE setting to control how post slugs are generated
o Fix many issues relating to locale and encoding
o Apply Typogrify filter to post summary
o Preserve file metadata (e.g. time stamps) when copying static files
to output
o Move AsciiDoc support from Pelican core into separate plugin
o Produce inline links instead of reference-style links when importing
content
o Improve handling of IGNORE_FILES setting behavior
o Properly escape symbol characters in tag names (e.g., C++)
o Minor tweaks for Python 3.4 compatibility
o Add several new signals
3.3.0 (2013-09-24)
o Drop Python 3.2 support in favor of Python 3.3
o Add Fabfile so Fabric can be used for workflow automation instead of
Make
o OUTPUT_RETENTION setting can be used to preserve metadata (e.g., VCS
data such as .hg and .git) from being removed from output directory
o Tumblr import
o Improve logic and consistency when cleaning output folder
o Improve documentation versioning and release automation
o Improve pagination flexibility
o Rename signals for better consistency (some plugins may need to be
updated)
o Move metadata extraction from generators to readers; metadata
extraction no longer article-specific
o Deprecate FILES_TO_COPY in favor of STATIC_PATHS and
EXTRA_PATH_METADATA
o Summaries in Markdown posts no longer include footnotes
o Remove unnecessary whitespace in output via lstrip_blocks Jinja
parameter
o Move PDF generation from core to plugin
o Replace MARKUP setting with READERS
o Add warning if img tag is missing alt attribute
o Add support for {} in relative links syntax, besides ||
o Add support for {tag} and {category} relative links
o Add a content_written signal
3.2.1 and 3.2.2
o Facilitate inclusion in FreeBSD Ports Collection
3.2 (2013-04-24)
o Support for Python 3!
o Override page save-to location from meta-data (enables using a static
page as the site's home page, for example)
o Time period archives (per-year, per-month, and per-day archives of
posts)
o Posterous blog import
o Improve WordPress blog import
o Migrate plugins to separate repository
o Improve HTML parser
o Provide ability to show or hide categories from menu using
DISPLAY_CATEGORIES_ON_MENU option
o Auto-regeneration can be told to ignore files via IGNORE_FILES
setting
o Improve post-generation feedback to user
o For multilingual posts, use meta-data to designate which is the
original and which is the translation
o Add .mdown to list of supported Markdown file extensions
o Document-relative URL generation (RELATIVE_URLS) is now off by
default
3.1 (2012-12-04)
o Importer now stores slugs within files by default. This can be
disabled with the --disable-slugs option.
o Improve handling of links to intra-site resources
o Ensure WordPress import adds paragraphs for all types of line endings
in post content
o Decode HTML entities within WordPress post titles on import
o Improve appearance of LinkedIn icon in default theme
o Add GitHub and Google+ social icons support in default theme
o Optimize social icons
o Add FEED_ALL_ATOM and FEED_ALL_RSS to generate feeds containing all
posts regardless of their language
o Split TRANSLATION_FEED into TRANSLATION_FEED_ATOM and
TRANSLATION_FEED_RSS
o Different feeds can now be enabled/disabled individually
o Allow for blank author: if AUTHOR setting is not set, author won't
default to ${USER} anymore, and a post won't contain any author
information if the post author is empty
o Move LESS and Webassets support from Pelican core to plugin
o The DEFAULT_DATE setting now defaults to None, which means that
articles won't be generated unless date metadata is specified
o Add FILENAME_METADATA setting to support metadata extraction from
filename
o Add gzip_cache plugin to compress common text files into a .gz file
within the same directory as the original file, preventing the server
(e.g. Nginx) from having to compress files during an HTTP call
o Add support for AsciiDoc-formatted content
o Add USE_FOLDER_AS_CATEGORY setting so that feature can be toggled
on/off
o Support arbitrary Jinja template files
o Restore basic functional tests
o New signals: generator_init, get_generators, and
article_generate_preread
3.0 (2012-08-08)
o Refactored the way URLs are handled
o Improved the English documentation
o Fixed packaging using setuptools entrypoints
o Added typogrify support
o Added a way to disable feed generation
o Added support for DIRECT_TEMPLATES
o Allow multiple extensions for content files
o Added LESS support
o Improved the import script
o Added functional tests
o Rsync support in the generated Makefile
o Improved feed support (easily pluggable with Feedburner for instance)
o Added support for abbr in reST
o Fixed a bunch of bugs :-)
2.8 (2012-02-28)
o Dotclear importer
o Allow the usage of Markdown extensions
o Themes are now easily extensible
o Don't output pagination information if there is only one page
o Add a page per author, with all their articles
o Improved the test suite
o Made the themes easier to extend
o Removed Skribit support
o Added a pelican-quickstart script
o Fixed timezone-related issues
o Added some scripts for Windows support
o Date can be specified in seconds
o Never fail when generating posts (skip and continue)
o Allow the use of future dates
o Support having different timezones per language
o Enhanced the documentation
2.7 (2011-06-11)
o Use logging rather than echoing to stdout
o Support custom Jinja filters
o Compatibility with Python 2.5
o Added a theme manager
o Packaged for Debian
o Added draft support
2.6 (2011-03-08)
o Changes in the output directory structure
o Makes templates easier to work with / create
o Added RSS support (was Atom-only)
o Added tag support for the feeds
o Enhance the documentation
o Added another theme (brownstone)
o Added translations
o Added a way to use cleaner URLs with a rewrite url module (or
equivalent)
o Added a tag cloud
o Added an autoreloading feature: the blog is automatically regenerated
each time a modification is detected
o Translate the documentation into French
o Import a blog from an RSS feed
o Pagination support
o Added Skribit support
2.5 (2010-11-20)
o Import from WordPress
o Added some new themes (martyalchin / wide-notmyidea)
o First bug report!
o Linkedin support
o Added a FAQ
o Google Analytics support
o Twitter support
o Use relative URLs, not static ones
2.4 (2010-11-06)
o Minor themes changes
o Add Disqus support (so we have comments)
o Another code refactoring
o Added config settings about pages
o Blog entries can also be generated in PDF
2.3 (2010-10-31)
o Markdown support
2.2 (2010-10-30)
o Prettify output
o Manages static pages as well
2.1 (2010-10-30)
o Make notmyidea the default theme
2.0 (2010-10-30)
o Refactoring to be more extensible
o Change into the setting variables
1.2 (2010-09-28)
o Added a debug option
o Added per-category feeds
o Use filesystem to get dates if no metadata is provided
o Add Pygments support
1.1 (2010-08-19)
o First working version
AUTHOR
Justin Mayer
COPYRIGHT
2010-2024
4 April 11, 2024 PELICAN(1)