'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PELICAN" "1" "Apr 11, 2024" "4" "PELICAN"
.SH NAME
pelican \- pelican documentation
.sp
Pelican is a static site generator, written in \fI\%Python\fP\&. Highlights include:
.INDENT 0.0
.IP \(bu 2
Write your content directly with your editor of choice in \fI\%reStructuredText\fP
or \fI\%Markdown\fP formats
.IP \(bu 2
Includes a simple CLI tool to (re)generate your site
.IP \(bu 2
Easy to interface with distributed version control systems and web hooks
.IP \(bu 2
Completely static output is easy to host anywhere
.UNINDENT
.sp
Ready to get started? Check out the \fI\%Quickstart\fP guide.
.SH FEATURES
.sp
Pelican’s feature highlights include:
.INDENT 0.0
.IP \(bu 2
Articles (e.g., blog posts) and pages (e.g., \(dqAbout\(dq, \(dqProjects\(dq, \(dqContact\(dq)
.IP \(bu 2
Integration with external services
.IP \(bu 2
Site themes (created using \fI\%Jinja2\fP templates)
.IP \(bu 2
Publication of articles in multiple languages
.IP \(bu 2
Generation of Atom and RSS feeds
.IP \(bu 2
Code syntax highlighting
.IP \(bu 2
Import existing content from WordPress, Dotclear, or RSS feeds
.IP \(bu 2
Fast rebuild times thanks to content caching and selective output writing
.IP \(bu 2
Extensible via a rich plugin ecosystem: \fI\%Pelican Plugins\fP
.UNINDENT
.SH WHY THE NAME "PELICAN"?
.sp
\(dqPelican\(dq is an anagram for \fIcalepin\fP, which means \(dqnotebook\(dq in French. ;)
.SH SOURCE CODE
.sp
You can access the source code at: \fI\%https://github.com/getpelican/pelican\fP
.SH HOW TO GET HELP, CONTRIBUTE, OR PROVIDE FEEDBACK
.sp
See our \fI\%feedback and contribution submission guidelines\fP\&.
.SH DOCUMENTATION
.SS Quickstart
.sp
Reading through all the documentation is highly recommended, but for the truly
impatient, following are some quick steps to get started.
.SS Installation
.sp
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 \fBsudo\fP if permissions warrant:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install \(dqpelican[markdown]\(dq
.EE
.UNINDENT
.UNINDENT
.SS Create a project
.sp
First, choose a name for your project, create an appropriately\-named directory
for your site, and switch to that directory:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mkdir \-p ~/projects/yoursite
cd ~/projects/yoursite
.EE
.UNINDENT
.UNINDENT
.sp
Create a skeleton project via the \fBpelican\-quickstart\fP command, which begins
by asking some questions about your site:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pelican\-quickstart
.EE
.UNINDENT
.UNINDENT
.sp
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.,
\fBhttps://example.com\fP).
.SS Create an article
.sp
You cannot run Pelican until you have created some content. Use your preferred
text editor to create your first article with the following content:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Title: My First Review
Date: 2010\-12\-03 10:20
Category: Review
Following is a review of my favorite mechanical keyboard.
.EE
.UNINDENT
.UNINDENT
.sp
Given that this example article is in Markdown format, save it as
\fB~/projects/yoursite/content/keyboard\-review.md\fP\&.
.SS Generate your site
.sp
From your project root directory, run the \fBpelican\fP command to generate your site:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pelican content
.EE
.UNINDENT
.UNINDENT
.sp
Your site has now been generated inside the \fBoutput/\fP directory. (You may see
a warning related to feeds, but that is normal when developing locally and can
be ignored for now.)
.SS Preview your site
.sp
Open a new terminal session, navigate to your project root directory, and
run the following command to launch Pelican\(aqs web server:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pelican \-\-listen
.EE
.UNINDENT
.UNINDENT
.sp
Preview your site by navigating to \fI\%http://localhost:8000/\fP in your browser.
.sp
Continue reading the other documentation sections for more detail, and check
out the Pelican wiki\(aqs \fI\%Tutorials\fP page for links to community\-published
tutorials.
.SS Footnotes
.IP [1] 5
You can help localize default fields by installing the
optional \fI\%tzlocal\fP
module.
.SS Installing Pelican
.sp
Pelican currently runs best on >=3.8.1; earlier versions of Python are not supported.
.sp
You can install Pelican via several different methods. The simplest is via \fI\%Pip\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install pelican
.EE
.UNINDENT
.UNINDENT
.sp
Or, if you plan on using Markdown:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install \(dqpelican[markdown]\(dq
.EE
.UNINDENT
.UNINDENT
.sp
(Keep in mind that some operating systems will require you to prefix the above
command with \fBsudo\fP in order to install Pelican system\-wide.)
.sp
While the above is the simplest method, the recommended approach is to create a
virtual environment for Pelican via \fI\%virtualenv\fP before installing Pelican.
Assuming you have \fI\%virtualenv\fP installed, you can then open a new terminal
session and create a new virtual environment for Pelican:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
source bin/activate
.EE
.UNINDENT
.UNINDENT
.sp
Once the virtual environment has been created and activated, Pelican can be
installed via \fBpython \-m pip install pelican\fP as noted above. Alternatively, if you
have the project source, you can install Pelican using the distutils method:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
cd path\-to\-Pelican\-source
python setup.py install
.EE
.UNINDENT
.UNINDENT
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install \-e \(dqgit+https://github.com/getpelican/pelican.git#egg=pelican\(dq
.EE
.UNINDENT
.UNINDENT
.sp
Once Pelican is installed, you can run \fBpelican \-\-help\fP to see basic usage
options. For more detail, refer to the \fI\%Publish\fP section.
.SS Optional packages
.sp
If you plan on using \fI\%Markdown\fP as a
markup format, you can install Pelican with Markdown support:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install \(dqpelican[markdown]\(dq
.EE
.UNINDENT
.UNINDENT
.sp
Typographical enhancements can be enabled in your settings file, but first the
requisite \fI\%Typogrify\fP library must be
installed:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install typogrify
.EE
.UNINDENT
.UNINDENT
.SS Dependencies
.sp
When Pelican is installed, the following dependent Python packages should be
automatically installed without any action on your part:
.INDENT 0.0
.IP \(bu 2
\fI\%feedgenerator\fP, to generate the
Atom feeds
.IP \(bu 2
\fI\%jinja2\fP, for templating support
.IP \(bu 2
\fI\%pygments\fP, for syntax highlighting
.IP \(bu 2
\fI\%docutils\fP, for supporting
reStructuredText as an input format
.IP \(bu 2
\fI\%blinker\fP, an object\-to\-object and
broadcast signaling system
.IP \(bu 2
\fI\%unidecode\fP, for ASCII
transliterations of Unicode text
utilities
.IP \(bu 2
\fI\%MarkupSafe\fP, for a markup\-safe
string implementation
.IP \(bu 2
\fI\%python\-dateutil\fP, to read
the date metadata
.UNINDENT
.SS Upgrading
.sp
If you installed a stable Pelican release via \fI\%Pip\fP and wish to upgrade to
the latest stable release, you can do so by adding \fB\-\-upgrade\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install \-\-upgrade pelican
.EE
.UNINDENT
.UNINDENT
.sp
If you installed Pelican via distutils or the bleeding\-edge method, simply
perform the same step to install the most recent version.
.SS Kickstart your site
.sp
Once Pelican has been installed, you can create a skeleton project via the
\fBpelican\-quickstart\fP command, which begins by asking some questions about
your site:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pelican\-quickstart
.EE
.UNINDENT
.UNINDENT
.sp
If run inside an activated virtual environment, \fBpelican\-quickstart\fP will
look for an associated project path inside \fB$VIRTUAL_ENV/.project\fP\&. 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:
\fBpelican\-quickstart \-\-path /your/desired/directory\fP
.sp
Once you finish answering all the questions, your project will consist of the
following hierarchy (except for \fIpages\fP — shown in parentheses below — which
you can optionally add yourself if you plan to create non\-chronological
content):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
yourproject/
├── content
│ └── (pages)
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py # Main settings file
└── publishconf.py # Settings to use when ready to publish
.EE
.UNINDENT
.UNINDENT
.sp
The next step is to begin to adding content to the \fIcontent\fP folder that has
been created for you.
.SS Writing content
.SS Articles and pages
.sp
Pelican considers \(dqarticles\(dq to be chronological content, such as posts on a
blog, and thus associated with a date.
.sp
The idea behind \(dqpages\(dq is that they are usually not temporal in nature and are
used for content that does not change very often (e.g., \(dqAbout\(dq or \(dqContact\(dq
pages).
.sp
You can find sample content in the repository at \fBsamples/content/\fP\&.
.SS File metadata
.sp
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.
.sp
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
\fB\&.rst\fP extension):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.sp
Author and tag lists may be semicolon\-separated instead, which allows
you to write authors and tags containing commas:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan
.EE
.UNINDENT
.UNINDENT
.sp
Pelican implements an extension to reStructuredText to enable support for the
\fBabbr\fP HTML tag. To use it, write something like this in your post:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
This will be turned into :abbr:\(gaHTML (HyperText Markup Language)\(ga.
.EE
.UNINDENT
.UNINDENT
.sp
You can also use Markdown syntax (with a file ending in \fB\&.md\fP, \fB\&.markdown\fP,
\fB\&.mkd\fP, or \fB\&.mdown\fP). Markdown generation requires that you first
explicitly install the \fI\%Python\-Markdown\fP package, which can be done via \fBpip
install Markdown\fP\&.
.sp
Pelican also supports \fI\%Markdown Extensions\fP, which might have to be installed
separately if they are not included in the default \fBMarkdown\fP package and can
be configured and loaded via the \fBMARKDOWN\fP setting.
.sp
Metadata syntax for Markdown posts should follow this pattern:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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.
.EE
.UNINDENT
.UNINDENT
.sp
You can also have your own metadata keys (so long as they don\(aqt conflict with
reserved metadata keywords) for use in your templates. The following table
contains a list of reserved metadata keywords:
.TS
box center;
l|l.
T{
Metadata
T} T{
Description
T}
_
T{
\fBtitle\fP
T} T{
Title of the article or page
T}
_
T{
\fBdate\fP
T} T{
Publication date (e.g., \fBYYYY\-MM\-DD HH:SS\fP)
T}
_
T{
\fBmodified\fP
T} T{
Modification date (e.g., \fBYYYY\-MM\-DD HH:SS\fP)
T}
_
T{
\fBtags\fP
T} T{
Content tags, separated by commas
T}
_
T{
\fBkeywords\fP
T} T{
Content keywords, separated by commas (HTML content only)
T}
_
T{
\fBcategory\fP
T} T{
Content category (one only — not multiple)
T}
_
T{
\fBslug\fP
T} T{
Identifier used in URLs and translations
T}
_
T{
\fBauthor\fP
T} T{
Content author, when there is only one
T}
_
T{
\fBauthors\fP
T} T{
Content authors, when there are multiple
T}
_
T{
\fBsummary\fP
T} T{
Brief description of content for index pages
T}
_
T{
\fBlang\fP
T} T{
Content language ID (\fBen\fP, \fBfr\fP, etc.)
T}
_
T{
\fBtranslation\fP
T} T{
If content is a translation of another (\fBtrue\fP or \fBfalse\fP)
T}
_
T{
\fBstatus\fP
T} T{
Content status: \fBdraft\fP, \fBhidden\fP, or \fBpublished\fP
T}
_
T{
\fBtemplate\fP
T} T{
Name of template to use to generate content (without extension)
T}
_
T{
\fBsave_as\fP
T} T{
Save content to this relative file path
T}
_
T{
\fBurl\fP
T} T{
URL to use for this article/page
T}
.TE
.sp
Readers for additional formats (such as \fI\%AsciiDoc\fP) are available via plugins,
which you can find via the \fI\%Pelican Plugins\fP collection as well as the legacy
\fI\%pelican\-plugins\fP repository.
.sp
Pelican can also process HTML files ending in \fB\&.html\fP and \fB\&.htm\fP\&. Pelican
interprets the HTML in a very straightforward manner, reading metadata from
\fBmeta\fP tags, the title from the \fBtitle\fP tag, and the body out from the
\fBbody\fP tag:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
.EE
.UNINDENT
.UNINDENT
.sp
You can change \fBperiod_archives.month\fP in the \fBfor\fP statement to
\fBperiod_archives.year\fP or \fBperiod_archives.day\fP as appropriate, depending
on the time period granularity desired.
.SS Objects
.sp
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.
.SS Article
.sp
The string representation of an Article is the \fIsource_path\fP attribute.
.TS
box center;
l|l.
T{
Attribute
T} T{
Description
T}
_
T{
author
T} T{
The \fI\%Author\fP of
this article.
T}
_
T{
authors
T} T{
A list of \fI\%Authors\fP
of this article.
T}
_
T{
category
T} T{
The \fI\%Category\fP
of this article.
T}
_
T{
content
T} T{
The rendered content of the article.
T}
_
T{
date
T} T{
Datetime object representing the article date.
T}
_
T{
date_format
T} T{
Either default date format or locale date format.
T}
_
T{
default_template
T} T{
Default template name.
T}
_
T{
in_default_lang
T} T{
Boolean representing if the article is written
in the default language.
T}
_
T{
lang
T} T{
Language of the article.
T}
_
T{
locale_date
T} T{
Date formatted by the \fIdate_format\fP\&.
T}
_
T{
metadata
T} T{
Article header metadata \fIdict\fP\&.
T}
_
T{
save_as
T} T{
Location to save the article page.
T}
_
T{
slug
T} T{
Page slug.
T}
_
T{
source_path
T} T{
Full system path of the article source file.
T}
_
T{
relative_source_path
T} T{
Relative path from \fI\%PATH\fP to the article source file.
T}
_
T{
status
T} T{
The article status, can be any of \(aqpublished\(aq or
\(aqdraft\(aq.
T}
_
T{
summary
T} T{
Rendered summary content.
T}
_
T{
tags
T} T{
List of \fI\%Tag\fP
objects.
T}
_
T{
template
T} T{
Template name to use for rendering.
T}
_
T{
title
T} T{
Title of the article.
T}
_
T{
translations
T} T{
List of translations
\fI\%Article\fP objects.
T}
_
T{
url
T} T{
URL to the article page.
T}
.TE
.SS Author / Category / Tag
.sp
The string representation of those objects is the \fIname\fP attribute.
.TS
box center;
l|l.
T{
Attribute
T} T{
Description
T}
_
T{
name
T} T{
Name of this object [1]\&.
T}
_
T{
page_name
T} T{
Author page name.
T}
_
T{
save_as
T} T{
Location to save the author page.
T}
_
T{
slug
T} T{
Page slug.
T}
_
T{
url
T} T{
URL to the author page.
T}
.TE
.IP [1] 5
for Author object, coming from \fI:authors:\fP or \fIAUTHOR\fP\&.
.SS Page
.sp
The string representation of a Page is the \fIsource_path\fP attribute.
.TS
box center;
l|l.
T{
Attribute
T} T{
Description
T}
_
T{
author
T} T{
The \fI\%Author\fP of
this page.
T}
_
T{
content
T} T{
The rendered content of the page.
T}
_
T{
date
T} T{
Datetime object representing the page date.
T}
_
T{
date_format
T} T{
Either default date format or locale date format.
T}
_
T{
default_template
T} T{
Default template name.
T}
_
T{
in_default_lang
T} T{
Boolean representing if the article is written
in the default language.
T}
_
T{
lang
T} T{
Language of the article.
T}
_
T{
locale_date
T} T{
Date formatted by the \fIdate_format\fP\&.
T}
_
T{
metadata
T} T{
Page header metadata \fIdict\fP\&.
T}
_
T{
save_as
T} T{
Location to save the page.
T}
_
T{
slug
T} T{
Page slug.
T}
_
T{
source_path
T} T{
Full system path of the page source file.
T}
_
T{
relative_source_path
T} T{
Relative path from \fI\%PATH\fP to the page source file.
T}
_
T{
status
T} T{
The page status, can be any of \(aqpublished\(aq, \(aqhidden\(aq or
\(aqdraft\(aq.
T}
_
T{
summary
T} T{
Rendered summary content.
T}
_
T{
tags
T} T{
List of \fI\%Tag\fP
objects.
T}
_
T{
template
T} T{
Template name to use for rendering.
T}
_
T{
title
T} T{
Title of the page.
T}
_
T{
translations
T} T{
List of translations
\fI\%Article\fP objects.
T}
_
T{
url
T} T{
URL to the page.
T}
.TE
.SS Feeds
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.SS Inheritance
.sp
Since version 3.0, Pelican supports inheritance from the \fBsimple\fP theme, so
you can re\-use the \fBsimple\fP theme templates in your own themes.
.sp
If one of the mandatory files in the \fBtemplates/\fP directory of your theme is
missing, it will be replaced by the matching template from the \fBsimple\fP
theme. So if the HTML structure of a template in the \fBsimple\fP theme is right
for you, you don\(aqt have to write a new template from scratch.
.sp
You can also extend templates from the \fBsimple\fP theme in your own themes by
using the \fB{% extends %}\fP directive as in the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% extends \(dq!simple/index.html\(dq %}
{% extends \(dqindex.html\(dq %}
.EE
.UNINDENT
.UNINDENT
.SS Example
.sp
With this system, it is possible to create a theme with just two files.
.SS base.html
.sp
The first file is the \fBtemplates/base.html\fP template:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% extends \(dq!simple/base.html\(dq %}
{% block head %}
{{ super() }}
{% endblock %}
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 1. 3
On the first line, we extend the \fBbase.html\fP template from the \fBsimple\fP
theme, so we don\(aqt have to rewrite the entire file.
.IP 2. 3
On the third line, we open the \fBhead\fP block which has already been defined
in the \fBsimple\fP theme.
.IP 3. 3
On the fourth line, the function \fBsuper()\fP keeps the content previously
inserted in the \fBhead\fP block.
.IP 4. 3
On the fifth line, we append a stylesheet to the page.
.IP 5. 3
On the last line, we close the \fBhead\fP block.
.UNINDENT
.sp
This file will be extended by all the other templates, so the stylesheet will
be linked from all pages.
.SS style.css
.sp
The second file is the \fBstatic/css/style.css\fP CSS stylesheet:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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 ;
}
.EE
.UNINDENT
.UNINDENT
.SS Download
.sp
You can download this example theme \fBhere\fP\&.
.SS pelican\-themes
.SS Description
.sp
\fBpelican\-themes\fP is a command line tool for managing themes for Pelican. See
\fI\%Themes\fP for settings related to themes.
.SS Usage
.nf
pelican\-themes [\-h] [\-l] [\-i theme path [theme path ...]]
.in +2
[\-r theme name [theme name ...]]
[\-s theme path [theme path ...]] [\-v] [\-\-version]
.in -2
.fi
.sp
.SS Optional arguments:
.INDENT 0.0
.TP
.B \-h\fP,\fB \-\-help
Show the help and exit
.TP
.B \-l\fP,\fB \-\-list
Show the themes already installed
.TP
.BI \-i \ theme_path\fR,\fB \ \-\-install \ theme_path
One or more themes to install
.TP
.BI \-r \ theme_name\fR,\fB \ \-\-remove \ theme_name
One or more themes to remove
.TP
.BI \-s \ theme_path\fR,\fB \ \-\-symlink \ theme_path
Same as \fB\-\-install\fP, but create a symbolic link instead of copying the theme.
Useful for theme development
.TP
.B \-v\fP,\fB \-\-verbose
Verbose output
.TP
.B \-\-version
Print the version of this script
.UNINDENT
.SS Examples
.SS Listing the installed themes
.sp
With \fBpelican\-themes\fP, you can see the available themes by using the \fB\-l\fP
or \fB\-\-list\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican\-themes \-l
notmyidea
two\-column@
simple
$ pelican\-themes \-\-list
notmyidea
two\-column@
simple
.EE
.UNINDENT
.UNINDENT
.sp
In this example, we can see there are three themes available: \fBnotmyidea\fP,
\fBsimple\fP, and \fBtwo\-column\fP\&.
.sp
\fBtwo\-column\fP is followed by an \fB@\fP because this theme is not copied to
the Pelican theme path, but is instead just linked to it (see \fI\%Creating
symbolic links\fP for details about creating symbolic links).
.sp
Note that you can combine the \fB\-\-list\fP option with the \fB\-v\fP or
\fB\-\-verbose\fP option to get more verbose output, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ 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 \(ga/home/skami/Dev/Python/pelican\-themes/two\-column\(aq)
/usr/local/lib/python2.6/dist\-packages/pelican\-2.6.0\-py2.6.egg/pelican/themes/simple
.EE
.UNINDENT
.UNINDENT
.SS Installing themes
.sp
You can install one or more themes using the \fB\-i\fP or \fB\-\-install\fP option.
This option takes as argument the path(s) of the theme(s) you want to install,
and can be combined with the \fB\-\-verbose\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-\-install ~/Dev/Python/pelican\-themes/notmyidea\-cms \-\-verbose
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-\-install ~/Dev/Python/pelican\-themes/notmyidea\-cms\e
~/Dev/Python/pelican\-themes/martyalchin \e
\-\-verbose
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-vi ~/Dev/Python/pelican\-themes/two\-column
.EE
.UNINDENT
.UNINDENT
.SS Removing themes
.sp
The \fBpelican\-themes\fP command can also remove themes from the Pelican themes
path. The \fB\-r\fP or \fB\-\-remove\fP option takes as argument the name(s) of the
theme(s) you want to remove, and can be combined with the \fB\-\-verbose\fP option.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-\-remove two\-column
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-r martyachin notmyidea\-cmd \-v
.EE
.UNINDENT
.UNINDENT
.SS Creating symbolic links
.sp
\fBpelican\-themes\fP can also install themes by creating symbolic links instead
of copying entire themes into the Pelican themes path.
.sp
To symbolically link a theme, you can use the \fB\-s\fP or \fB\-\-symlink\fP, which
works exactly as the \fB\-\-install\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-\-symlink ~/Dev/Python/pelican\-themes/two\-column
.EE
.UNINDENT
.UNINDENT
.sp
In this example, the \fBtwo\-column\fP 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.
.sp
This is useful for theme development:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ 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
.EE
.UNINDENT
.UNINDENT
.SS Doing several things at once
.sp
The \fB\-\-install\fP, \fB\-\-remove\fP and \fB\-\-symlink\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pelican\-themes \-\-remove notmyidea\-cms two\-column \e
\-\-install ~/Dev/Python/pelican\-themes/notmyidea\-cms\-fr \e
\-\-symlink ~/Dev/Python/pelican\-themes/two\-column \e
\-\-verbose
.EE
.UNINDENT
.UNINDENT
.sp
In this example, the theme \fBnotmyidea\-cms\fP is replaced by the theme
\fBnotmyidea\-cms\-fr\fP
.SS Importing an existing site
.SS Description
.sp
\fBpelican\-import\fP is a command\-line tool for converting articles from other
software to reStructuredText or Markdown. The supported import formats are:
.INDENT 0.0
.IP \(bu 2
Blogger XML export
.IP \(bu 2
Dotclear export
.IP \(bu 2
Tumblr API
.IP \(bu 2
WordPress XML export
.IP \(bu 2
RSS/Atom feed
.UNINDENT
.sp
The conversion from HTML to reStructuredText or Markdown relies on \fI\%Pandoc\fP\&.
For Dotclear, if the source posts are written with Markdown syntax, they will
not be converted (as Pelican also supports Markdown).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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 \fI\%More Categories\fP that enables multiple
categories per article.
.UNINDENT
.UNINDENT
.SS Dependencies
.sp
\fBpelican\-import\fP has some dependencies not required by the rest of Pelican:
.INDENT 0.0
.IP \(bu 2
\fIBeautifulSoup4\fP and \fIlxml\fP, for WordPress and Dotclear import. Can be
installed like any other Python package (\fBpip install BeautifulSoup4
lxml\fP).
.IP \(bu 2
\fIFeedparser\fP, for feed import (\fBpip install feedparser\fP).
.IP \(bu 2
\fIPandoc\fP, see the \fI\%Pandoc site\fP for installation instructions on your
operating system.
.UNINDENT
.SS Usage
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.SS Positional arguments
.INDENT 0.0
.INDENT 3.5
.TS
box center;
l|l.
T{
\fBinput\fP
T} T{
The input file to read
T}
_
T{
\fBapi_key\fP
T} T{
(Tumblr only) api_key can be obtained from \fI\%https://www.tumblr.com/oauth/apps\fP
T}
.TE
.UNINDENT
.UNINDENT
.SS Optional arguments
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-h\fP,\fB \-\-help
Show this help message and exit
.TP
.B \-\-blogger
Blogger XML export (default: False)
.TP
.B \-\-dotclear
Dotclear export (default: False)
.TP
.B \-\-tumblr
Tumblr API (default: False)
.TP
.B \-\-wpfile
WordPress XML export (default: False)
.TP
.B \-\-feed
Feed to parse (default: False)
.TP
.BI \-o \ OUTPUT\fR,\fB \ \-\-output \ OUTPUT
Output path (default: content)
.TP
.BI \-m \ MARKUP\fR,\fB \ \-\-markup \ MARKUP
Output markup format: \fBrst\fP, \fBmarkdown\fP, or \fBasciidoc\fP
(default: \fBrst\fP)
.TP
.B \-\-dir\-cat
Put files in directories with categories name
(default: False)
.TP
.B \-\-dir\-page
Put files recognised as pages in \(dqpages/\(dq sub\-
directory (blogger and wordpress import only)
(default: False)
.TP
.B \-\-filter\-author
Import only post from the specified author
.TP
.B \-\-strip\-raw
Strip raw HTML code that can\(aqt be converted to markup
such as flash embeds or iframes (wordpress import
only) (default: False)
.TP
.B \-\-wp\-custpost
Put wordpress custom post types in directories. If
used with \-\-dir\-cat option directories will be created
as \(dq/post_type/category/\(dq (wordpress import only)
.TP
.B \-\-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\(aqt associated with a post. Files will be downloaded
with their original path inside the output directory,
e.g. \(dqoutput/wp\-uploads/date/postname/file.jpg\(dq.
(wordpress import only) (requires an internet
connection)
.TP
.B \-\-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)
.TP
.BI \-b \ BLOGNAME\fR,\fB \ \-\-blogname\fB= BLOGNAME
Blog name used in Tumblr API
.UNINDENT
.UNINDENT
.UNINDENT
.SS Examples
.sp
For Blogger:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican\-import \-\-blogger \-o ~/output ~/posts.xml
.EE
.UNINDENT
.UNINDENT
.sp
For Dotclear:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican\-import \-\-dotclear \-o ~/output ~/backup.txt
.EE
.UNINDENT
.UNINDENT
.sp
For Tumblr:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican\-import \-\-tumblr \-o ~/output \-\-blogname=
.EE
.UNINDENT
.UNINDENT
.sp
For WordPress:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican\-import \-\-wpfile \-o ~/output ~/posts.xml
.EE
.UNINDENT
.UNINDENT
.SS Tests
.sp
To test the module, one can use sample files:
.INDENT 0.0
.IP \(bu 2
for WordPress: \fI\%https://www.wpbeginner.com/wp\-themes/how\-to\-add\-dummy\-content\-for\-theme\-development\-in\-wordpress/\fP
.IP \(bu 2
for Dotclear: \fI\%http://media.dotaddict.org/tda/downloads/lorem\-backup.txt\fP
.UNINDENT
.SS Frequently Asked Questions (FAQ)
.sp
Here are some frequently asked questions about Pelican.
.SS What\(aqs the best way to communicate a problem, question, or suggestion?
.sp
Please read our \fI\%feedback guidelines\fP\&.
.SS How can I help?
.sp
There are several ways to help out. First, you can communicate any Pelican
suggestions or problems you might have via \fI\%Pelican Discussions\fP\&. 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.
.sp
If you want to contribute, please fork \fI\%the Git repository\fP, 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 \fI\%How to Contribute\fP
section for more details.
.sp
You can also contribute by creating themes and improving the documentation.
.SS Is the Pelican settings file mandatory?
.sp
Configuration files are optional and are just an easy way to configure Pelican.
For basic operations, it\(aqs possible to specify options while invoking Pelican
via the command line. See \fBpelican \-\-help\fP for more information.
.SS Changes to the settings file take no effect
.sp
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 \fBLOAD_CONTENT_CACHE = False\fP or use the
\fB\-\-ignore\-cache\fP command\-line switch.
.SS I\(aqm creating my own theme. How do I use Pygments for syntax highlighting?
.sp
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 \fB\&.highlight pre\fP
class in your theme\(aqs 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
\fI\%Pygments project demo site\fP\&.
.sp
You can use the following example commands to generate a starting CSS file from
a Pygments built\-in style (in this case, \(dqmonokai\(dq) and then copy the generated
CSS file to your new theme:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pygmentize \-S monokai \-f html \-a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/
.EE
.UNINDENT
.UNINDENT
.sp
Don\(aqt forget to import your \fBpygment.css\fP file from your main CSS file.
.SS How do I create my own theme?
.sp
Please refer to \fI\%Themes\fP\&.
.SS I want to use Markdown, but I got an error.
.sp
If you try to generate Markdown content without first installing the Markdown
library, you may see a message that says \fBNo valid files found in content\fP\&.
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 \fBsudo\fP if permissions
require it:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install markdown
.EE
.UNINDENT
.UNINDENT
.SS Can I use arbitrary metadata in my templates?
.sp
Yes. For example, to include a modified date in a Markdown post, one could
include the following at the top of the article:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Modified: 2012\-08\-08
.EE
.UNINDENT
.UNINDENT
.sp
For reStructuredText, this metadata should of course be prefixed with a colon:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
:Modified: 2012\-08\-08
.EE
.UNINDENT
.UNINDENT
.sp
This metadata can then be accessed in templates such as \fBarticle.html\fP via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}
.EE
.UNINDENT
.UNINDENT
.sp
If you want to include metadata in templates outside the article context (e.g.,
\fBbase.html\fP), the \fBif\fP statement should instead be:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% if article and article.modified %}
.EE
.UNINDENT
.UNINDENT
.SS How do I assign custom templates on a per\-page basis?
.sp
It\(aqs 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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
:template: template_name
.EE
.UNINDENT
.UNINDENT
.sp
For content in Markdown format:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Template: template_name
.EE
.UNINDENT
.UNINDENT
.sp
Then just make sure your theme contains the relevant template file (e.g.
\fBtemplate_name.html\fP).
.SS How can I override the generated URL of a specific page or article?
.sp
Include \fBurl\fP and \fBsave_as\fP metadata in any pages or articles that you want
to override the generated URL. Here is an example page in reST format:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Override url/save_as page
#########################
:url: override/url/
:save_as: override/url/index.html
.EE
.UNINDENT
.UNINDENT
.sp
With this metadata, the page will be written to \fBoverride/url/index.html\fP
and Pelican will use the URL \fBoverride/url/\fP to link to this page.
.SS How can I use a static page as my home page?
.sp
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
\fBcontent/pages/home.md\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Title: Welcome to My Site
URL:
save_as: index.html
Thank you for visiting. Welcome!
.EE
.UNINDENT
.UNINDENT
.sp
If the original blog index is still wanted, it can then be saved in a
different location by setting \fBINDEX_SAVE_AS = \(aqblog_index.html\(aq\fP for
the \fB\(aqindex\(aq\fP direct template.
.SS What if I want to disable feed generation?
.sp
To disable feed generation, all feed settings should be set to \fBNone\fP\&. All
but three feed settings already default to \fBNone\fP, so if you want to disable
all feed generation, you only need to specify the following settings:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
.EE
.UNINDENT
.UNINDENT
.sp
The word \fBNone\fP should not be surrounded by quotes. Please note that \fBNone\fP
and \fB\(aq\(aq\fP are not the same thing.
.SS I\(aqm getting a warning about feeds generated without SITEURL being set properly
.sp
\fI\%RSS and Atom feeds require all URL links to be absolute\fP\&. In order to properly
generate links in Pelican you will need to set \fBSITEURL\fP to the full path of
your site.
.sp
Feeds are still generated when this warning is displayed, but links within may
be malformed and thus the feed may not validate.
.SS Can I force Atom feeds to show only summaries instead of article content?
.sp
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 \fBcontent\fP 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.
.SS Is Pelican only suitable for blogs?
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
TAGS_SAVE_AS = \(aq\(aq
TAG_SAVE_AS = \(aq\(aq
.EE
.UNINDENT
.UNINDENT
.SS Why does Pelican always write all HTML files even with content caching enabled?
.sp
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.
.sp
However, this means that the modification time of the files changes every time,
so a \fBrsync\fP based upload will transfer them even if their content hasn\(aqt
changed. A simple solution is to make \fBrsync\fP use the \fB\-\-checksum\fP option,
which will make it compare the file checksums in a much faster way than Pelican
would.
.SS How to process only a subset of all articles?
.sp
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 \fBARTICLE_PATHS\fP\&. A list of such filenames could be found using a
command similar to \fBcd content; find \-name \(aq*.md\(aq | head \-n 10\fP\&.
.SS My tag cloud is missing/broken since I upgraded Pelican
.sp
In an ongoing effort to streamline Pelican, tag cloud generation has been
moved out of Pelican core and into a separate \fI\%plugin\fP\&. See the \fI\%Plugins\fP
documentation for further information about the Pelican plugin system.
.SS Since I upgraded Pelican my pages are no longer rendered
.sp
Pages were available to themes as lowercase \fBpages\fP and uppercase \fBPAGES\fP\&.
To bring this inline with the \fI\%Templates and Variables\fP section, \fBPAGES\fP has
been removed. This is quickly resolved by updating your theme to iterate over
\fBpages\fP instead of \fBPAGES\fP\&. Just replace:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% for pg in PAGES %}
.EE
.UNINDENT
.UNINDENT
.sp
with something like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% for pg in pages %}
.EE
.UNINDENT
.UNINDENT
.SS How can I stop Pelican from trying to parse my static files as content?
.sp
Pelican\(aqs article and page generators run before it\(aqs static generator. That
means if you use a setup similar to the default configuration, where a static
source directory is defined inside a \fB*_PATHS\fP setting, all files that have a
valid content file ending (\fB\&.html\fP, \fB\&.rst\fP, \fB\&.md\fP, ...) will be treated
as articles or pages before they get treated as static files.
.sp
To circumvent this issue either use the appropriate \fB*_EXCLUDES\fP setting or
disable the offending reader via \fBREADERS\fP if you don\(aqt need it.
.SS Why is [arbitrary Markdown syntax] not supported?
.sp
Pelican does not directly handle Markdown processing and instead delegates that
task to the \fI\%Python\-Markdown\fP project, the core of which purposefully follows
the original Markdown syntax rules and not the myriad Markdown \(dqflavors\(dq that
have subsequently propagated. That said, \fI\%Python\-Markdown\fP is quite modular, and
the syntax you are looking for may be provided by one of the many available
\fI\%Markdown Extensions\fP\&. 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.
.SS Tips
.sp
Here are some tips about Pelican that you might find useful.
.SS Custom 404 Pages
.sp
When a browser requests a resource that the web server cannot find, the web
server usually displays a generic \(dqFile not found\(dq (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 (\fInot\fP an article), such as this
Markdown\-formatted example stored in \fBcontent/pages/404.md\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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)?
.EE
.UNINDENT
.UNINDENT
.sp
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\(aqs \fBlocation\fP block:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
error_page 404 /404.html;
.EE
.UNINDENT
.UNINDENT
.sp
For Apache:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
ErrorDocument 404 /404.html
.EE
.UNINDENT
.UNINDENT
.sp
For Amazon S3, first navigate to the \fBStatic Site Hosting\fP menu in the bucket
settings on your AWS console. From there:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Error Document: 404.html
.EE
.UNINDENT
.UNINDENT
.SS Publishing to GitHub Pages
.sp
If you use \fI\%GitHub\fP for your Pelican site you can
publish your site to \fI\%GitHub Pages\fP for free.
Your site will be published to \fBhttps://.github.io\fP if it\(aqs a user or
organization site or to \fBhttps://.github.io/\fP if it\(aqs a
project site. It\(aqs also possible to \fI\%use a custom domain with GitHub Pages\fP\&.
.sp
There are \fI\%two ways to publish a site to GitHub Pages\fP:
.INDENT 0.0
.IP 1. 3
\fBPublishing from a branch:\fP run \fBpelican\fP 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.
.IP 2. 3
\fBPublishing with a custom GitHub Actions workflow:\fP just push the source
files of your Pelican site to your GitHub repo\(aqs default branch and have a
custom GitHub Actions workflow run \fBpelican\fP for you to generate the
output directory and publish it to your GitHub Pages site. This way you
don\(aqt need to run \fBpelican\fP locally. You can even edit your site\(aqs source
files using GitHub\(aqs web interface and any changes that you commit will be
published.
.UNINDENT
.SS Publishing a Project Site to GitHub Pages from a Branch
.sp
To publish a Pelican site as a Project Page you need to \fIpush\fP the content of
the \fBoutput\fP dir generated by Pelican to a repository\(aqs \fBgh\-pages\fP branch
on GitHub.
.sp
The excellent \fI\%ghp\-import\fP, which can
be installed with \fBpip\fP, makes this process really easy.
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican content \-o output \-s pelicanconf.py
$ ghp\-import output \-b gh\-pages
$ git push origin gh\-pages
.EE
.UNINDENT
.UNINDENT
.sp
The \fBghp\-import output\fP command updates the local \fBgh\-pages\fP branch with
the content of the \fBoutput\fP directory (creating the branch if it doesn\(aqt
already exist). The \fBgit push origin gh\-pages\fP command updates the remote
\fBgh\-pages\fP branch, effectively publishing the Pelican site.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBgithub\fP target of the Makefile (and the \fBgh_pages\fP task of
\fBtasks.py\fP) created by the \fBpelican\-quickstart\fP command publishes the
Pelican site as Project Pages, as described above.
.UNINDENT
.UNINDENT
.SS Publishing a User Site to GitHub Pages from a Branch
.sp
To publish a Pelican site in the form of User Pages, you need to \fIpush\fP the
content of the \fBoutput\fP dir generated by Pelican to the \fBmaster\fP branch of
your \fB.github.io\fP repository on GitHub.
.sp
Again, you can take advantage of \fBghp\-import\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ 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
.EE
.UNINDENT
.UNINDENT
.sp
The \fBgit push\fP command pushes the local \fBgh\-pages\fP branch (freshly updated
by the \fBghp\-import\fP command) to the \fBelemoine.github.io\fP repository\(aqs
\fBmaster\fP branch on GitHub.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To publish your Pelican site as User Pages, feel free to adjust the
\fBgithub\fP target of the Makefile.
.UNINDENT
.UNINDENT
.sp
Another option for publishing to User Pages is to generate the output files in
the root directory of the project.
.sp
For example, your main project folder is \fB.github.io\fP and you can
create the Pelican project in a subdirectory called \fBPelican\fP\&. Then from
inside the \fBPelican\fP folder you can run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pelican content \-o .. \-s pelicanconf.py
.EE
.UNINDENT
.UNINDENT
.sp
Now you can push the whole project \fB.github.io\fP to the master
branch of your GitHub repository:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ git push origin master
.EE
.UNINDENT
.UNINDENT
.sp
(assuming origin is set to your remote repository).
.SS Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
.sp
Pelican comes with a \fI\%custom workflow\fP
for publishing a Pelican site. To use it:
.INDENT 0.0
.IP 1. 3
Enable GitHub Pages in your repo: go to \fBSettings → Pages\fP and choose
\fBGitHub Actions\fP for the \fBSource\fP setting.
.IP 2. 3
Commit a \fB\&.github/workflows/pelican.yml\fP file to your repo with these contents:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
name: Deploy to GitHub Pages
on:
push:
branches: [\(dqmain\(dq]
workflow_dispatch:
jobs:
deploy:
uses: \(dqgetpelican/pelican/.github/workflows/github_pages.yml@master\(dq
permissions:
contents: \(dqread\(dq
pages: \(dqwrite\(dq
id\-token: \(dqwrite\(dq
with:
settings: \(dqpublishconf.py\(dq
.EE
.UNINDENT
.UNINDENT
.IP 3. 3
Go to the \fBActions\fP tab in your repo
(\fBhttps://github.com///actions\fP) and you should see a
\fBDeploy to GitHub Pages\fP action running.
.IP 4. 3
Once the action completes you should see your Pelican site deployed at your
repo\(aqs GitHub Pages URL: \fBhttps://.github.io\fP for a user or
organization site or \fBhttps://.github.io/>\fP for a
project site.
.UNINDENT
.sp
Notes:
.INDENT 0.0
.IP \(bu 2
You don\(aqt need to set \fBSITEURL\fP in your Pelican settings: the workflow will
set it for you
.IP \(bu 2
You don\(aqt need to commit your \fB\-\-output\fP / \fBOUTPUT_PATH\fP directory
(\fBoutput/\fP) to git: the workflow will run \fBpelican\fP to build the output
directory for you on GitHub Actions
.UNINDENT
.sp
See \fI\%GitHub\(aqs docs about reusable workflows\fP
for more information.
.sp
A number of optional inputs can be added to the \fBwith:\fP block when calling
the workflow:
.TS
box center;
l|l|l|l|l.
T{
Name
T} T{
Required
T} T{
Description
T} T{
Type
T} T{
Default
T}
_
T{
settings
T} T{
Yes
T} T{
The path to your Pelican settings
file (\fBpelican\fP\(aqs
\fB\-\-settings\fP option),
for example: \fB\(dqpublishconf.py\(dq\fP
T} T{
string
T} T{
T}
_
T{
requirements
T} T{
No
T} T{
The Python requirements to
install, for example to enable
markdown and typogrify use:
\fB\(dqpelican[markdown] typogrify\(dq\fP
or if you have a requirements
file: \fB\(dq\-r requirements.txt\(dq\fP
T} T{
string
T} T{
\fB\(dqpelican\(dq\fP
T}
_
T{
output\-path
T} T{
No
T} T{
Where to output the generated
files (\fBpelican\fP\(aqs \fB\-\-output\fP
option)
T} T{
string
T} T{
\fB\(dqoutput/\(dq\fP
T}
.TE
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
with:
settings: \(dqpublishconf.py\(dq
requirements: \(dqpelican[markdown] typogrify\(dq
output\-path: \(dq__output__/\(dq
.EE
.UNINDENT
.UNINDENT
.SS Custom 404 Pages
.sp
GitHub Pages will display the custom 404 page described above, as noted in the
relevant \fI\%GitHub docs\fP\&.
.SS Update your site on each commit
.sp
To automatically update your Pelican site on each commit, you can create a
post\-commit hook. For example, you can add the following to
\fB\&.git/hooks/post\-commit\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pelican content \-o output \-s pelicanconf.py && ghp\-import output && git push origin gh\-pages
.EE
.UNINDENT
.UNINDENT
.SS Copy static files to the root of your site
.sp
To use a \fI\%custom domain\fP with
GitHub Pages, you need to put the domain of your site (e.g.,
\fBblog.example.com\fP) inside a \fBCNAME\fP file at the root of your site. To do
this, create the \fBcontent/extra/\fP directory and add a \fBCNAME\fP file to it.
Then use the \fBSTATIC_PATHS\fP setting to tell Pelican to copy this file to your
output directory. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
STATIC_PATHS = [\(aqimages\(aq, \(aqextra/CNAME\(aq]
EXTRA_PATH_METADATA = {\(aqextra/CNAME\(aq: {\(aqpath\(aq: \(aqCNAME\(aq},}
.EE
.UNINDENT
.UNINDENT
.sp
Note: use forward slashes, \fB/\fP, even on Windows.
.sp
You can also use the \fBEXTRA_PATH_METADATA\fP mechanism to place a
\fBfavicon.ico\fP or \fBrobots.txt\fP at the root of any site.
.SS How to add YouTube or Vimeo Videos
.sp
The easiest way is to paste the embed code of the video from these sites
directly into your source content.
.sp
Alternatively, you can also use Pelican plugins like \fBliquid_tags\fP,
\fBpelican_youtube\fP, or \fBpelican_vimeo\fP to embed videos in your content.
.sp
Moreover, markup languages like reST and Markdown have plugins that let you
embed videos in the markup. You can use \fI\%reST video directive\fP for reST or \fI\%mdx_video plugin\fP for Markdown.
.SS Develop Locally Using SSL
.sp
Here\(aqs how you can set up your local pelican server to support SSL.
.sp
First, create a self\-signed certificate and key using \fBopenssl\fP (this creates \fBcert.pem\fP and \fBkey.pem\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ openssl req \-x509 \-newkey rsa:4096 \-keyout key.pem \-out cert.pem \-days 365 \-nodes
.EE
.UNINDENT
.UNINDENT
.sp
And use this command to launch the server (the server starts within your \fBoutput\fP directory):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pelican.server 8443 \-\-key=../key.pem \-\-cert=../cert.pem
.EE
.UNINDENT
.UNINDENT
.sp
If you are using \fBdevelop\-server.sh\fP, add this to the top:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
CERT=\(dq$BASEDIR/cert.pem\(dq
KEY=\(dq$BASEDIR/key.pem\(dq
.EE
.UNINDENT
.UNINDENT
.sp
and modify the \fBpelican.server\fP line as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$PY \-m pelican.server $port \-\-ssl \-\-cert=\(dq$CERT\(dq \-\-key=\(dq$KEY\(dq &
.EE
.UNINDENT
.UNINDENT
.SS Contributing and feedback guidelines
.sp
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
\fI\%existing issues\fP\&.
.sp
Don\(aqt hesitate to fork Pelican and submit an issue or pull request on GitHub.
When doing so, please consider the following guidelines.
.SS Filing issues
.INDENT 0.0
.IP \(bu 2
Before you submit a new issue, try \fI\%asking for help\fP first.
.IP \(bu 2
If determined to create a new issue, first search \fI\%Pelican Discussions\fP
and \fI\%existing issues\fP (open and closed) to see if your question has already
been answered previously.
.UNINDENT
.SS How to get help
.sp
Before you ask for help, please make sure you do the following:
.INDENT 0.0
.IP 1. 3
Read the \fI\%documentation\fP thoroughly. If in a hurry, at least use the search
field that is provided at top\-left on the \fI\%documentation\fP pages. Make sure
you read the docs for the Pelican version you are using.
.IP 2. 3
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 \(aq\fI\%plugins\fP or a specific combination of settings.
.IP 3. 3
Try reproducing the issue in a clean environment, ensuring you are using:
.UNINDENT
.INDENT 0.0
.IP \(bu 2
latest Pelican release (or an up\-to\-date Git clone of Pelican master)
.IP \(bu 2
latest releases of libraries used by Pelican
.IP \(bu 2
no plugins or only those related to the issue
.UNINDENT
.sp
\fBNOTE:\fP The most common sources of problems are anomalies in (1) themes, (2)
plugins, (3) settings files, and (4) \fBmake\fP/\fBinvoke\fP automation wrappers.
If you can\(aqt 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):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.sp
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.
.sp
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 \fI\%paste service\fP, GitHub repository, or other
publicly\-accessible location:
.INDENT 0.0
.IP \(bu 2
Describe what version of Pelican you are running (output of \fBpelican \-\-version\fP
or the HEAD commit hash if you cloned the repo) and how exactly you installed
it (the full command you used, e.g. \fBpython \-m pip install pelican\fP).
.IP \(bu 2
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.
.IP \(bu 2
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 \fBminimum steps\fP
necessary to reproduce it (no extra plugins, etc.).
.IP \(bu 2
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.
.IP \(bu 2
Upload detailed and \fBcomplete\fP output logs and backtraces (remember to add
the \fB\-\-debug\fP flag: \fBpelican \-\-debug content [...]\fP)
.UNINDENT
.sp
Once the above preparation is ready, you can post your query as a new thread in
\fI\%Pelican Discussions\fP\&. Remember to include all the information you prepared.
.SS Contributing code
.sp
Before you submit a contribution, please ask whether it is desired so that you
don\(aqt 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 \(aq\fI\%plugins\fP — you can \fI\%ask for help\fP to make that determination.
.sp
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.
.SS Using Git and GitHub
.INDENT 0.0
.IP \(bu 2
\fI\%Create a new branch\fP specific to your change (as opposed to making
your commits in the master branch).
.IP \(bu 2
\fBDon\(aqt put multiple unrelated fixes/features in the same branch / pull request.\fP
For example, if you\(aqre working on a new feature and find a bugfix that
doesn\(aqt \fIrequire\fP your new feature, \fBmake a new distinct branch and pull
request\fP for the bugfix. Similarly, any proposed changes to code style
formatting should be in a completely separate pull request.
.IP \(bu 2
Add a \fBRELEASE.md\fP 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:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
Release type: minor
Reload browser window upon changes to content, settings, or theme
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
Check for unnecessary whitespace via \fBgit diff \-\-check\fP before committing.
.IP \(bu 2
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.
\fIExample:\fP \fBEnsure proper PLUGIN_PATH behavior. Refs #428.\fP If the commit
\fIcompletely fixes\fP an existing bug report, please use \fBFixes #585\fP or \fBFix
#585\fP syntax (so the relevant issue is automatically closed upon PR merge).
.IP \(bu 2
After the first line of the commit message, add a blank line and then a more
detailed explanation (when relevant).
.IP \(bu 2
\fI\%Squash your commits\fP to eliminate merge commits and ensure a clean and
readable commit history.
.IP \(bu 2
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\(aqt
skipping any tests.)
.UNINDENT
.SS Contribution quality standards
.INDENT 0.0
.IP \(bu 2
Adhere to the project\(aqs code style standards. See: \fI\%Development Environment\fP
.IP \(bu 2
Ensure your code is compatible with the \fI\%officially\-supported Python releases\fP\&.
.IP \(bu 2
Add docs and tests for your changes. Undocumented and untested features will
not be accepted.
.IP \(bu 2
\fI\%Run all the tests\fP \fBon all versions of Python
supported by Pelican\fP to ensure nothing was accidentally broken.
.UNINDENT
.sp
Check out our \fI\%Git Tips\fP page or \fI\%ask for help\fP if you
need assistance or have any questions about these guidelines.
.SS Setting up the development environment
.sp
While there are many ways to set up one\(aqs development environment, the following
instructions will utilize \fI\%Pip\fP and \fI\%PDM\fP\&. 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.
.sp
Please note that Python >=3.8.1 is required for Pelican development.
.sp
\fI(Optional)\fP If you prefer to \fI\%install PDM\fP once for use with multiple projects,
you can install it via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
curl \-sSL https://pdm.fming.dev/install\-pdm.py | python3 \-
.EE
.UNINDENT
.UNINDENT
.sp
Point your web browser to the \fI\%Pelican repository\fP and tap the \fBFork\fP button
at top\-right. Then clone the source for your fork and add the upstream project
as a Git remote:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.sp
While PDM can dynamically create and manage virtual environments, we\(aqre going
to manually create and activate a virtual environment:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mkdir ~/virtualenvs && cd ~/virtualenvs
python3 \-m venv pelican
source ~/virtualenvs/pelican/*/activate
.EE
.UNINDENT
.UNINDENT
.sp
Install the needed dependencies and set up the project:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
python \-m pip install invoke
invoke setup
.EE
.UNINDENT
.UNINDENT
.sp
Your local environment should now be ready to go!
.SS Development
.sp
Once Pelican has been set up for local development, create a topic branch for
your bug fix or feature:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
git checkout \-b name\-of\-your\-bugfix\-or\-feature
.EE
.UNINDENT
.UNINDENT
.sp
Now you can make changes to Pelican, its documentation, and/or other aspects of
the project.
.SS Running the test suite
.sp
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 \fBpelican/tests\fP, and you can run them
via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke tests
.EE
.UNINDENT
.UNINDENT
.sp
(For more on Invoke, see \fBinvoke \-l\fP to list tasks, or
\fI\%https://pyinvoke.org\fP for documentation.)
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke lint
.EE
.UNINDENT
.UNINDENT
.sp
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.
.sp
After making your changes and running the tests, you may see a test failure
mentioning that \(dqsome generated files differ from the expected functional tests
output.\(dq 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, \fBmake sure you have both\fP \fBen_EN.utf8\fP \fBand\fP
\fBfr_FR.utf8\fP \fBlocales installed\fP, and then run the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke update\-functional\-tests
.EE
.UNINDENT
.UNINDENT
.sp
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.
.sp
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.
\fI\%Tox\fP is a useful tool to automate running tests inside \fBvirtualenv\fP
environments.
.SS Building the docs
.sp
If you make changes to the documentation, you should build and inspect your
changes before committing them:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke docserve
.EE
.UNINDENT
.UNINDENT
.sp
Open \fI\%http://localhost:8000\fP 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.
.SS Plugin development
.sp
To create a \fInew\fP Pelican plugin, please refer to the \fI\%plugin template\fP
repository for detailed instructions.
.sp
If you want to contribute to an \fIexisting\fP Pelican plugin, follow the steps
above to set up Pelican for local development, and then create a directory to
store cloned plugin repositories:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mkdir \-p ~/projects/pelican\-plugins
.EE
.UNINDENT
.UNINDENT
.sp
Assuming you wanted to contribute to the Simple Footnotes plugin, you would
first browse to the \fI\%Simple Footnotes\fP repository on GitHub and tap the \fBFork\fP
button at top\-right. Then clone the source for your fork and add the upstream
project as a Git remote:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.sp
Install the needed dependencies and set up the project:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke setup
.EE
.UNINDENT
.UNINDENT
.sp
Create a topic branch for your plugin bug fix or feature:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
git checkout \-b name\-of\-your\-bugfix\-or\-feature
.EE
.UNINDENT
.UNINDENT
.sp
After writing new tests for your plugin changes, run the plugin test suite and
check for code style compliance via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke tests
invoke lint
.EE
.UNINDENT
.UNINDENT
.sp
If style violations are found, many of them can be addressed automatically via:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
invoke format
.EE
.UNINDENT
.UNINDENT
.sp
If style violations are found even after running the above auto\-formatters,
you will need to make additional manual changes until \fBinvoke lint\fP no longer
reports any code style violations.
.SS Submitting your changes
.sp
Assuming linting validation and tests pass, add a \fBRELEASE.md\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Release type: patch
Fix browser reloading upon changes to content, settings, or theme
.EE
.UNINDENT
.UNINDENT
.sp
Commit your changes and push your topic branch:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
git add .
git commit \-m \(dqYour detailed description of your changes\(dq
git push origin name\-of\-your\-bugfix\-or\-feature
.EE
.UNINDENT
.UNINDENT
.sp
Finally, browse to your repository fork on GitHub and submit a pull request.
.SS Logging tips
.sp
Try to use logging with appropriate levels.
.sp
For logging messages that are not repeated, use the usual Python way:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# at top of file
import logging
logger = logging.getLogger(__name__)
# when needed
logger.warning(\(dqA warning with %s formatting\(dq, arg_to_be_formatted)
.EE
.UNINDENT
.UNINDENT
.sp
Do not format log messages yourself. Use \fB%s\fP formatting in messages and pass
arguments to logger. This is important, because the Pelican logger will
preprocess some arguments, such as exceptions.
.SS Limiting extraneous log messages
.sp
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 \fBextra\fP keyword argument for
the logging message in the following format:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
logger.warning(\(dqA warning with %s formatting\(dq, arg_to_be_formatted,
extra={\(aqlimit_msg\(aq: \(aqA generic message for too many warnings\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
Optionally, you can also set \fB\(aqlimit_args\(aq\fP as a tuple of arguments in
\fBextra\fP dict if your generic message needs formatting.
.sp
Limit is set to \fB5\fP, i.e, first four logs with the same \fB\(aqlimit_msg\(aq\fP are
outputted normally but the fifth one will be logged using \fB\(aqlimit_msg\(aq\fP (and
\fB\(aqlimit_args\(aq\fP if present). After the fifth, corresponding log messages will
be ignored.
.sp
For example, if you want to log missing resources, use the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
for resource in resources:
if resource.is_missing:
logger.warning(
\(aqThe resource %s is missing\(aq, resource.name,
extra={\(aqlimit_msg\(aq: \(aqOther resources were missing\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
The log messages will be displayed as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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
.EE
.UNINDENT
.UNINDENT
.SS Outputting traceback in the logs
.sp
If you\(aqre logging inside an \fBexcept\fP block, you may want to provide the
traceback information as well. You can do that by setting \fBexc_info\fP keyword
argument to \fBTrue\fP 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 \fB\-\-debug\fP mode like the following:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
try:
some_action()
except Exception as e:
logger.error(\(aqException occurred: %s\(aq, e,
exc_info=settings.get(\(aqDEBUG\(aq, False))
.EE
.UNINDENT
.UNINDENT
.SS Pelican internals
.sp
This section describe how Pelican works internally. As you\(aqll see, it\(aqs quite
simple, but a bit of documentation doesn\(aqt hurt. :)
.sp
You can also find in the \fI\%Some history about Pelican\fP section an excerpt of a report the
original author wrote with some software design information.
.SS Overall structure
.sp
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.
.sp
The logic is separated into different classes and concepts:
.INDENT 0.0
.IP \(bu 2
\fBWriters\fP 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.
.IP \(bu 2
\fBReaders\fP 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).
.IP \(bu 2
\fBGenerators\fP generate the different outputs. For instance, Pelican comes
with \fBArticlesGenerator\fP and \fBPageGenerator\fP\&. Given a configuration, they
can do whatever they want. Most of the time, it\(aqs generating files from
inputs.
.IP \(bu 2
Pelican also uses templates, so it\(aqs easy to write your own theme. The
syntax is \fI\%Jinja2\fP and is very easy to learn, so
don\(aqt hesitate to jump in and build your own theme.
.UNINDENT
.SS How to implement a new reader?
.sp
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 \fBread\fP method that returns
HTML content and some metadata.
.sp
Take a look at the Markdown reader:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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):
\(dq\(dq\(dqParse content and metadata of markdown files\(dq\(dq\(dq
with pelican_open(source_path) as text:
md_extensions = {\(aqmarkdown.extensions.meta\(aq: {},
\(aqmarkdown.extensions.codehilite\(aq: {}}
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
.EE
.UNINDENT
.UNINDENT
.sp
Simple, isn\(aqt it?
.sp
If your new reader requires additional Python dependencies, then you should
wrap their \fBimport\fP statements in a \fBtry...except\fP block. Then inside the
reader\(aqs class, set the \fBenabled\fP 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\(aqt use.
.SS How to implement a new generator?
.sp
Generators have two important methods. You\(aqre not forced to create both; only
the existing ones will be called.
.INDENT 0.0
.IP \(bu 2
\fBgenerate_context\fP, 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 \fBPageGenerator\fP \fBgenerate_context\fP method
finds all the pages, transforms them into objects, and populates the context
with them. Be careful \fInot\fP to output anything using this context at this
stage, as it is likely to change by the effect of other generators.
.IP \(bu 2
\fBgenerate_output\fP is then called. And guess what is it made for? Oh,
generating the output. :) It\(aqs here that you may want to look at the context
and call the methods of the \fBwriter\fP object that is passed as the first
argument of this function. In the \fBPageGenerator\fP 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 \fBwrite_file\fP) for each page encountered.
.UNINDENT
.SS Some history about Pelican
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This page comes from a report the original author (Alexis Métaireau) wrote
right after writing Pelican, in December 2010. The information may not be
up\-to\-date.
.UNINDENT
.UNINDENT
.sp
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\(aqve 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\(aqve
re\-factored the Pelican code by two
times; each time took less than 30 minutes.
.SS Use case
.sp
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\(aqs 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]
.sp
To be flexible enough, Pelican has template support, so you can easily write
your own themes if you want to.
.SS Design process
.sp
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.
.sp
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 \(dqonly one
file\(dq mantra was not good enough for Pelican, so I decided to rework a bit all
that, and split this in multiple different files.
.sp
I’ve separated the logic in different classes and concepts:
.INDENT 0.0
.IP \(bu 2
\fIwriters\fP 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.
.IP \(bu 2
\fIreaders\fP 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).
.IP \(bu 2
\fIgenerators\fP 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\(aqs generating files from inputs (user inputs and files).
.UNINDENT
.sp
I also deal with contents objects. They can be \fBArticles\fP, \fBPages\fP,
\fBQuotes\fP, or whatever you want. They are defined in the \fBcontents.py\fP
module and represent some content to be used by the program.
.SS In more detail
.sp
Here is an overview of the classes involved in Pelican.
[image]
.sp
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.
.sp
Internally, the following process is followed:
.INDENT 0.0
.IP \(bu 2
First of all, the command line is parsed, and some content from the user is
used to initialize the different generator objects.
.IP \(bu 2
A \fBcontext\fP is created. It contains the settings from the command line and
a settings file if provided.
.IP \(bu 2
The \fBgenerate_context\fP method of each generator is called, updating
the context.
.IP \(bu 2
The writer is created and given to the \fBgenerate_output\fP method of each
generator.
.UNINDENT
.sp
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
\fBgenerate_context\fP should modify the context, whereas the second
\fBgenerate_output\fP method should not.
.sp
Then, it is up to the generators to do what the want, in the
\fBgenerate_context\fP and \fBgenerate_content\fP method. Taking the
\fBArticlesGenerator\fP class will help to understand some others concepts. Here
is what happens when calling the \fBgenerate_context\fP method:
.INDENT 0.0
.IP \(bu 2
Read the folder “path”, looking for restructured text files, load each of
them, and construct a content object (\fBArticle\fP) with it. To do so, use
\fBReader\fP objects.
.IP \(bu 2
Update the \fBcontext\fP with all those articles.
.UNINDENT
.sp
Then, the \fBgenerate_content\fP method uses the \fBcontext\fP and the \fBwriter\fP
to generate the wanted output.
.SS Release history
.SS 4.9.1 \- 2023\-11\-15
.INDENT 0.0
.IP \(bu 2
Ensure \fBtzdata\fP dependency is installed on Windows
.UNINDENT
.SS 4.9.0 \- 2023\-11\-12
.INDENT 0.0
.IP \(bu 2
Upgrade code to new minimum supported Python version: 3.8
.IP \(bu 2
Settings support for \fBpathlib.Path\fP \fI\%(#2758)\fP
.IP \(bu 2
Various improvements to Simple theme (\fI\%#2976\fP & \fI\%#3234\fP)
.IP \(bu 2
Use Furo as Sphinx documentation theme \fI\%(#3023)\fP
.IP \(bu 2
Default to 100 articles maximum in feeds \fI\%(#3127)\fP
.IP \(bu 2
Add \fBperiod_archives common context\fP variable \fI\%(#3148)\fP
.IP \(bu 2
Use \fBwatchfiles\fP as the file\-watching backend \fI\%(#3151)\fP
.IP \(bu 2
Add GitHub Actions workflow for GitHub Pages \fI\%(#3189)\fP
.IP \(bu 2
Allow dataclasses in settings \fI\%(#3204)\fP
.IP \(bu 2
Switch build tool to PDM instead of Setuptools/Poetry \fI\%(#3220)\fP
.IP \(bu 2
Provide a \fBplugin_enabled\fP Jinja test for themes \fI\%(#3235)\fP
.IP \(bu 2
Preserve connection order in Blinker \fI\%(#3238)\fP
.IP \(bu 2
Remove social icons from default \fBnotmyidea\fP theme \fI\%(#3240)\fP
.IP \(bu 2
Remove unreliable \fBWRITE_SELECTED\fP feature \fI\%(#3243)\fP
.IP \(bu 2
Importer: Report broken embedded video links when importing from Tumblr \fI\%(#3177)\fP
.IP \(bu 2
Importer: Remove newline addition when iterating Photo post types \fI\%(#3178)\fP
.IP \(bu 2
Importer: Force timestamp conversion in Tumblr importer to be UTC with offset \fI\%(#3221)\fP
.IP \(bu 2
Importer: Use tempfile for intermediate HTML file for Pandoc \fI\%(#3221)\fP
.IP \(bu 2
Switch linters to Ruff \fI\%(#3223)\fP
.UNINDENT
.SS 4.8.0 \- 2022\-07\-11
.INDENT 0.0
.IP \(bu 2
Use JSON values for extra settings in Invoke tasks template \fI\%(#2994)\fP
.IP \(bu 2
Add content tag for links, which can help with things like Twitter social cards \fI\%(#3001)\fP
.IP \(bu 2
Improve word count behavior when generating summary \fI\%(#3002)\fP
.UNINDENT
.SS 4.7.2 \- 2022\-02\-09
.INDENT 0.0
.IP \(bu 2
Fix incorrect parsing of parameters specified via \fI\-e\fP / \fI\-\-extra\-settings\fP option flags \fI\%(#2938)\fP
.IP \(bu 2
Add \fBcategories.html\fP template to default theme \fI\%(#2973)\fP
.IP \(bu 2
Document how to use plugins to inject content \fI\%(#2922)\fP
.UNINDENT
.SS 4.7.1 \- 2021\-10\-12
.INDENT 0.0
.IP \(bu 2
Extend rich logging to server component \fI\%(#2927)\fP
.IP \(bu 2
Fix an issue where metadata flagged to be discarded was being cached \fI\%(#2926)\fP
.IP \(bu 2
Adjust suffix in server to allow redirection when needed \fI\%(#2931)\fP
.IP \(bu 2
Add MIME types for web fonts \fI\%(#2929)\fP
.IP \(bu 2
Distribute sample data used to run tests \fI\%(#2935)\fP
.IP \(bu 2
Add Python 3.10 to test matrix
.UNINDENT
.SS 4.7.0 \- 2021\-10\-01
.INDENT 0.0
.IP \(bu 2
Improve default theme rendering on mobile and other small screen devices \fI\%(#2914)\fP
.IP \(bu 2
Add support for hidden articles \fI\%(#2866)\fP
.IP \(bu 2
Improve word count behavior when generating summary CJK & other locales \fI\%(#2864)\fP
.IP \(bu 2
Add progress spinner during generation \fI\%(#2869)\fP
and richer logging \fI\%(#2897)\fP, both via \fI\%Rich\fP
.IP \(bu 2
Invoke tasks \fBserve\fP and \fBlivereload\fP now auto\-open a web browser pointing to the locally\-served web site \fI\%(#2764)\fP
.IP \(bu 2
Support some date format codes used by ISO dates \fI\%(#2902)\fP
.IP \(bu 2
Document how to add a new writer \fI\%(#2901)\fP
.UNINDENT
.SS 4.6.0 \- 2021\-03\-23
.INDENT 0.0
.IP \(bu 2
Add new URL pattern to \fBPAGINATION_PATTERNS\fP for the last page in the list \fI\%(#1401)\fP
.IP \(bu 2
Speed up \fBlivereload\fP Invoke task via caching \fI\%(#2847)\fP
.IP \(bu 2
Ignore \fBNone\fP return value from \fBget_generators\fP signal \fI\%(#2850)\fP
.IP \(bu 2
Relax dependency minimum versions and remove upper bounds
.UNINDENT
.SS 4.5.4 \- 2021\-01\-04
.sp
Replace plugin definitions in settings with string representations after registering, so they can be cached correctly \fI\%(#2828)\fP\&.
.SS 4.5.3 \- 2020\-12\-01
.sp
Fix a mistake made in PR #2821
.SS 4.5.2 \- 2020\-11\-22
.sp
Improve logging of generators and writer loaders
.SS 4.5.1 \- 2020\-11\-02
.INDENT 0.0
.IP \(bu 2
Refactor intra\-site link discovery in order to match more permissively \fI\%(#2646)\fP
.IP \(bu 2
Fix plugins running twice in auto\-reload mode \fI\%(#2817)\fP
.IP \(bu 2
Add notice to use \fBfrom pelican import signals\fP instead of \fBimport pelican.signals\fP \fI\%(#2805)\fP
.UNINDENT
.SS 4.5.0 \- 2020\-08\-20
.INDENT 0.0
.IP \(bu 2
Add namespace plugin support; list plugins via \fBpelican\-plugins\fP command
.IP \(bu 2
Override settings via \fB\-e\fP / \fB\-\-extra\-settings\fP CLI option flags
.IP \(bu 2
Add settings for custom Jinja globals and tests
.IP \(bu 2
Customize article summary ellipsis via \fBSUMMARY_END_SUFFIX\fP setting
.IP \(bu 2
Customize Typogrify dash handling via new \fBTYPOGRIFY_DASHES\fP setting
.IP \(bu 2
Support Unicode when generating slugs
.IP \(bu 2
Support Asciidoc \fB\&.adoc\fP file generation in Pelican importer
.IP \(bu 2
Improve user experience when \fBpelican \-\-listen\fP web server is quit
.IP \(bu 2
Improve Invoke tasks template
.IP \(bu 2
Include tests in source distributions
.IP \(bu 2
Switch CI from Travis to GitHub Actions
.IP \(bu 2
Remove support for Python 2.7
.UNINDENT
.SS 4.2.0 \- 2019\-10\-17
.INDENT 0.0
.IP \(bu 2
Support inline SVGs; don\(aqt treat titles in SVGs as HTML titles
.IP \(bu 2
Add category to feeds (in addition to tags)
.IP \(bu 2
Improve content metadata field docs
.IP \(bu 2
Add docs for including other Markdown/reST files in content
.UNINDENT
.SS 4.1.3 \- 2019\-10\-09
.INDENT 0.0
.IP \(bu 2
Fix quick\-start docs regarding \fBpelican \-\-listen\fP
.IP \(bu 2
Set default listen address to 127.0.0.1
.IP \(bu 2
Add extra/optional Markdown dependency to setup.py
.IP \(bu 2
Use correct SSH port syntax for rsync in tasks.py
.IP \(bu 2
Place all deprecated settings handling together
.IP \(bu 2
Add related project URLs for display on PyPI
.IP \(bu 2
Skip some tests on Windows that can\(aqt pass due to filesystem differences
.UNINDENT
.SS 4.1.2 \- 2019\-09\-23
.sp
Fix pelican.settings.load_source to avoid caching issues \- PR #2621
.SS 4.1.1 \- 2019\-08\-23
.INDENT 0.0
.IP \(bu 2
Add AutoPub to auto\-publish releases on PR merge
.IP \(bu 2
Add CSS classes for reStructuredText figures
.IP \(bu 2
Pass \fBargv\fP to Pelican \fBmain\fP entrypoint
.IP \(bu 2
Set default content status to a blank string rather than \fBNone\fP
.UNINDENT
.SS 4.1.0 \- 2019\-07\-14
.INDENT 0.0
.IP \(bu 2
Live browser reload upon changed files (provided via Invoke task)
.IP \(bu 2
Add \fBpyproject.toml\fP, managed by Poetry
.IP \(bu 2
Support for invoking \fBpython \-m pelican\fP
.IP \(bu 2
Add relative source path attribute to content
.IP \(bu 2
Allow directories in \fBEXTRA_PATH_METADATA\fP
.IP \(bu 2
Add \fBall_articles\fP variable to period pages (for recent posts functionality)
.IP \(bu 2
Improve debug mode output
.IP \(bu 2
Remove blank or duplicate summaries from Atom feed
.IP \(bu 2
Fix bugs in pagination, pelican\-import, pelican\-quickstart, and feed importer
.UNINDENT
.SS 4.0.1 (2018\-11\-30)
.INDENT 0.0
.IP \(bu 2
Refactor \fBpelican.server\fP logging
.IP \(bu 2
Fix bug in which all static files were processed as \(dqdraft\(dq
.IP \(bu 2
Bug fixes for Invoke/Makefile automation, Importer, and other miscellanea
.UNINDENT
.sp
If upgrading from 3.7.x or earlier, please note that slug\-related settings in
4.0+ use \fB{slug}\fP and/or \fB{lang}\fP rather than \fB%s\fP\&. If \fB%s\fP\-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 \fBTypeError\fP\&. In such cases, the theme needs
to be updated. For example, instead of \fBTAG_FEED_ATOM|format(tag.slug)\fP, use
\fBTAG_FEED_ATOM.format(slug=tag.slug)\fP
.SS 4.0.0 (2018\-11\-13)
.INDENT 0.0
.IP \(bu 2
Replace \fBdevelop_server.sh\fP script with \fBpelican \-\-listen\fP
.IP \(bu 2
Improved copy/link behavior for large static files (e.g., videos)
.IP \(bu 2
New \fB{static}\fP syntax to link to static content; content linked to by
\fB{static}\fP and \fB{attach}\fP is automatically copied over even if not in
\fBSTATIC_PATHS\fP
.IP \(bu 2
Pages can now have \fBdraft\fP status
.IP \(bu 2
Show current settings via new \fB\-\-print\-settings\fP flag
.IP \(bu 2
All settings for slugs now use \fB{slug}\fP and/or \fB{lang}\fP rather than
\fB%s\fP\&. If \fB%s\fP\-style settings are encountered, Pelican will emit a warning
and fallback to the default setting.
.IP \(bu 2
New signals: \fBfeed_generated\fP and \fBpage_generated_write_page\fP
.IP \(bu 2
Replace Fabric with Invoke and \fBfabfile.py\fP template with \fBtasks.py\fP
.IP \(bu 2
Replace \fBPAGINATED_DIRECT_TEMPLATES\fP by \fBPAGINATED_TEMPLATES\fP, extending
control over pagination to all templates and making page size variable
.IP \(bu 2
Replace \fBSLUG_SUBSTITUTIONS\fP (and friends) by \fBSLUG_REGEX_SUBSTITUTIONS\fP
for more finegrained control
.IP \(bu 2
\fB\(aq{base_name}\(aq\fP value in \fBPAGINATION_PATTERNS\fP setting no longer strips
\fB\(aqbar\(aq\fP from \fB\(aqfoo/bar.html\(aq\fP (unless \fB\(aqbar\(aq == \(aqindex\(aq\fP).
.IP \(bu 2
\fBARTICLE_ORDER_BY\fP and \fBPAGE_ORDER_BY\fP now also affect 1) category, tag
and author pages 2) feeds 3) draft and hidden articles and pages
.IP \(bu 2
New \fBARTICLE_TRANSLATION_ID\fP and \fBPAGE_TRANSLATION_ID\fP settings to
specify metadata attributes used to identify/disable translations
.IP \(bu 2
Make the HTML reader parse multiple occurrences of metadata tags as a list
.IP \(bu 2
New Blogger XML backup importer
.IP \(bu 2
Wordpress importer now updates file links to point to local copies if the
files were downloaded with \fB\-\-wp\-attach\fP\&.
.IP \(bu 2
Importer no longer inserts extra newlines, to prevent breaking of HTML
attributes.
.IP \(bu 2
Pelican server now prioritises \fBfoo.html\fP and \fBfoo/index.html\fP over
\fBfoo/\fP when resolving \fBfoo\fP\&.
.UNINDENT
.SS 3.7.1 (2017\-01\-10)
.INDENT 0.0
.IP \(bu 2
Fix locale issues in Quickstart script
.IP \(bu 2
Specify encoding for README and CHANGELOG in setup.py
.UNINDENT
.SS 3.7.0 (2016\-12\-12)
.INDENT 0.0
.IP \(bu 2
Atom feeds output \fB\fP in addition to \fB\fP
.IP \(bu 2
Atom feeds use \fB\fP for the original publication date and
\fB\fP for modifications
.IP \(bu 2
Simplify Atom feed ID generation and support URL fragments
.IP \(bu 2
Produce category feeds with category\-specific titles
.IP \(bu 2
RSS feeds now default to summary instead of full content;
set \fBRSS_FEED_SUMMARY_ONLY = False\fP to revert to previous behavior
.IP \(bu 2
Replace \fBMD_EXTENSIONS\fP with \fBMARKDOWN\fP setting
.IP \(bu 2
Replace \fBJINJA_EXTENSIONS\fP with more\-robust \fBJINJA_ENVIRONMENT\fP setting
.IP \(bu 2
Improve summary truncation logic to handle special characters and tags that
span multiple lines, using HTML parser instead of regular expressions
.IP \(bu 2
Include summary when looking for intra\-site link substitutions
.IP \(bu 2
Link to authors and index via \fB{author}name\fP and \fB{index}\fP syntax
.IP \(bu 2
Override widget names via \fBLINKS_WIDGET_NAME\fP and \fBSOCIAL_WIDGET_NAME\fP
.IP \(bu 2
Add \fBINDEX_SAVE_AS\fP option to override default \fBindex.html\fP value
.IP \(bu 2
Remove \fBPAGES\fP context variable for themes in favor of \fBpages\fP
.IP \(bu 2
\fBSLUG_SUBSTITUTIONS\fP now accepts 3\-tuple elements, allowing URL slugs to
contain non\-alphanumeric characters
.IP \(bu 2
Tag and category slugs can be controlled with greater precision using the
\fBTAG_SUBSTITUTIONS\fP and \fBCATEGORY_SUBSTITUTIONS\fP settings
.IP \(bu 2
Author slugs can be controlled with greater precision using the
\fBAUTHOR_SUBSTITUTIONS\fP setting
.IP \(bu 2
\fBDEFAULT_DATE\fP can be defined as a string
.IP \(bu 2
Use \fBmtime\fP instead of \fBctime\fP when \fBDEFAULT_DATE = \(aqfs\(aq\fP
.IP \(bu 2
Add \fB\-\-fatal=errors|warnings\fP option for use with continuous integration
.IP \(bu 2
When using generator\-level caching, ensure previously\-cached files are
processed instead of just new files.
.IP \(bu 2
Add Python and Pelican version information to debug output
.IP \(bu 2
Improve compatibility with Python 3.5
.IP \(bu 2
Comply with and enforce PEP8 guidelines
.IP \(bu 2
Replace tables in settings documentation with \fBdata::\fP directives
.UNINDENT
.SS 3.6.3 (2015\-08\-14)
.INDENT 0.0
.IP \(bu 2
Fix permissions issue in release tarball
.UNINDENT
.SS 3.6.2 (2015\-08\-01)
.INDENT 0.0
.IP \(bu 2
Fix installation errors related to Unicode in tests
.IP \(bu 2
Don\(aqt show pagination in \fBnotmyidea\fP theme if there\(aqs only one page
.IP \(bu 2
Make hidden pages available in context
.IP \(bu 2
Improve URLWrapper comparison
.UNINDENT
.SS 3.6.0 (2015\-06\-15)
.INDENT 0.0
.IP \(bu 2
Disable caching by default in order to prevent potential confusion
.IP \(bu 2
Improve caching behavior, replacing \fBpickle\fP with \fBcpickle\fP
.IP \(bu 2
Allow Markdown or reST content in metadata fields other than \fBsummary\fP
.IP \(bu 2
Support semicolon\-separated author/tag lists
.IP \(bu 2
Improve flexibility of article sorting
.IP \(bu 2
Add \fB\-\-relative\-urls\fP argument
.IP \(bu 2
Support devserver listening on addresses other than localhost
.IP \(bu 2
Unify HTTP server handlers to \fBpelican.server\fP throughout
.IP \(bu 2
Handle intra\-site links to draft posts
.IP \(bu 2
Move \fBtag_cloud\fP from core to plugin
.IP \(bu 2
Load default theme\(aqs external resources via HTTPS
.IP \(bu 2
Import drafts from WordPress XML
.IP \(bu 2
Improve support for Windows users
.IP \(bu 2
Enhance logging and test suite
.IP \(bu 2
Clean up and refactor codebase
.IP \(bu 2
New signals: \fBall_generators_finalized\fP and \fBpage_writer_finalized\fP
.UNINDENT
.SS 3.5.0 (2014\-11\-04)
.INDENT 0.0
.IP \(bu 2
Introduce \fBARTICLE_ORDER_BY\fP and \fBPAGE_ORDER_BY\fP settings to control the
order of articles and pages.
.IP \(bu 2
Include time zone information in dates rendered in templates.
.IP \(bu 2
Expose the reader name in the metadata for articles and pages.
.IP \(bu 2
Add the ability to store static files along with content in the same
directory as articles and pages using \fB{attach}\fP in the path.
.IP \(bu 2
Prevent Pelican from raising an exception when there are duplicate pieces of
metadata in a Markdown file.
.IP \(bu 2
Introduce the \fBTYPOGRIFY_IGNORE_TAGS\fP setting to add HTML tags to be
ignored by Typogrify.
.IP \(bu 2
Add the ability to use \fB\-\fP in date formats to strip leading zeros. For
example, \fB%\-d/%\-m/%y\fP will now result in the date \fB9/8/12\fP\&.
.IP \(bu 2
Ensure feed generation is correctly disabled during quickstart configuration.
.IP \(bu 2
Fix \fBPAGE_EXCLUDES\fP and \fBARTICLE_EXCLUDES\fP from incorrectly matching
sub\-directories.
.IP \(bu 2
Introduce \fBSTATIC_EXCLUDE\fP setting to add static file excludes.
.IP \(bu 2
Fix an issue when using \fBPAGINATION_PATTERNS\fP while \fBRELATIVE_URLS\fP
is enabled.
.IP \(bu 2
Fix feed generation causing links to use the wrong language for month
names when using other locales.
.IP \(bu 2
Fix an issue where the authors list in the simple template wasn\(aqt correctly
formatted.
.IP \(bu 2
Fix an issue when parsing non\-string URLs from settings.
.IP \(bu 2
Improve consistency of debug and warning messages.
.UNINDENT
.SS 3.4.0 (2014\-07\-01)
.INDENT 0.0
.IP \(bu 2
Speed up content generation via new caching mechanism
.IP \(bu 2
Add selective post generation (instead of always building entire site)
.IP \(bu 2
Many documentation improvements, including switching to prettier RtD theme
.IP \(bu 2
Add support for multiple content and plugin paths
.IP \(bu 2
Add \fB:modified:\fP metadata field to complement \fB:date:\fP\&.
Used to specify the last date and time an article was updated independently
from the date and time it was published.
.IP \(bu 2
Add support for multiple authors via new \fB:authors:\fP metadata field
.IP \(bu 2
Watch for changes in static directories when in auto\-regeneration mode
.IP \(bu 2
Add filters to limit log output when desired
.IP \(bu 2
Add language support to drafts
.IP \(bu 2
Add \fBSLUGIFY_SOURCE\fP setting to control how post slugs are generated
.IP \(bu 2
Fix many issues relating to locale and encoding
.IP \(bu 2
Apply Typogrify filter to post summary
.IP \(bu 2
Preserve file metadata (e.g. time stamps) when copying static files to output
.IP \(bu 2
Move AsciiDoc support from Pelican core into separate plugin
.IP \(bu 2
Produce inline links instead of reference\-style links when importing content
.IP \(bu 2
Improve handling of \fBIGNORE_FILES\fP setting behavior
.IP \(bu 2
Properly escape symbol characters in tag names (e.g., \fBC++\fP)
.IP \(bu 2
Minor tweaks for Python 3.4 compatibility
.IP \(bu 2
Add several new signals
.UNINDENT
.SS 3.3.0 (2013\-09\-24)
.INDENT 0.0
.IP \(bu 2
Drop Python 3.2 support in favor of Python 3.3
.IP \(bu 2
Add \fBFabfile\fP so Fabric can be used for workflow automation instead of Make
.IP \(bu 2
\fBOUTPUT_RETENTION\fP setting can be used to preserve metadata (e.g., VCS
data such as \fB\&.hg\fP and \fB\&.git\fP) from being removed from output directory
.IP \(bu 2
Tumblr import
.IP \(bu 2
Improve logic and consistency when cleaning output folder
.IP \(bu 2
Improve documentation versioning and release automation
.IP \(bu 2
Improve pagination flexibility
.IP \(bu 2
Rename signals for better consistency (some plugins may need to be updated)
.IP \(bu 2
Move metadata extraction from generators to readers; metadata extraction no
longer article\-specific
.IP \(bu 2
Deprecate \fBFILES_TO_COPY\fP in favor of \fBSTATIC_PATHS\fP and
\fBEXTRA_PATH_METADATA\fP
.IP \(bu 2
Summaries in Markdown posts no longer include footnotes
.IP \(bu 2
Remove unnecessary whitespace in output via \fBlstrip_blocks\fP Jinja parameter
.IP \(bu 2
Move PDF generation from core to plugin
.IP \(bu 2
Replace \fBMARKUP\fP setting with \fBREADERS\fP
.IP \(bu 2
Add warning if img tag is missing \fBalt\fP attribute
.IP \(bu 2
Add support for \fB{}\fP in relative links syntax, besides \fB||\fP
.IP \(bu 2
Add support for \fB{tag}\fP and \fB{category}\fP relative links
.IP \(bu 2
Add a \fBcontent_written\fP signal
.UNINDENT
.SS 3.2.1 and 3.2.2
.INDENT 0.0
.IP \(bu 2
Facilitate inclusion in FreeBSD Ports Collection
.UNINDENT
.SS 3.2 (2013\-04\-24)
.INDENT 0.0
.IP \(bu 2
Support for Python 3!
.IP \(bu 2
Override page save\-to location from meta\-data (enables using a static page as
the site\(aqs home page, for example)
.IP \(bu 2
Time period archives (per\-year, per\-month, and per\-day archives of posts)
.IP \(bu 2
Posterous blog import
.IP \(bu 2
Improve WordPress blog import
.IP \(bu 2
Migrate plugins to separate repository
.IP \(bu 2
Improve HTML parser
.IP \(bu 2
Provide ability to show or hide categories from menu using
\fBDISPLAY_CATEGORIES_ON_MENU\fP option
.IP \(bu 2
Auto\-regeneration can be told to ignore files via \fBIGNORE_FILES\fP setting
.IP \(bu 2
Improve post\-generation feedback to user
.IP \(bu 2
For multilingual posts, use meta\-data to designate which is the original
and which is the translation
.IP \(bu 2
Add \fB\&.mdown\fP to list of supported Markdown file extensions
.IP \(bu 2
Document\-relative URL generation (\fBRELATIVE_URLS\fP) is now off by default
.UNINDENT
.SS 3.1 (2012\-12\-04)
.INDENT 0.0
.IP \(bu 2
Importer now stores slugs within files by default. This can be disabled with
the \fB\-\-disable\-slugs\fP option.
.IP \(bu 2
Improve handling of links to intra\-site resources
.IP \(bu 2
Ensure WordPress import adds paragraphs for all types of line endings
in post content
.IP \(bu 2
Decode HTML entities within WordPress post titles on import
.IP \(bu 2
Improve appearance of LinkedIn icon in default theme
.IP \(bu 2
Add GitHub and Google+ social icons support in default theme
.IP \(bu 2
Optimize social icons
.IP \(bu 2
Add \fBFEED_ALL_ATOM\fP and \fBFEED_ALL_RSS\fP to generate feeds containing all
posts regardless of their language
.IP \(bu 2
Split \fBTRANSLATION_FEED\fP into \fBTRANSLATION_FEED_ATOM\fP and
\fBTRANSLATION_FEED_RSS\fP
.IP \(bu 2
Different feeds can now be enabled/disabled individually
.IP \(bu 2
Allow for blank author: if \fBAUTHOR\fP setting is not set, author won\(aqt
default to \fB${USER}\fP anymore, and a post won\(aqt contain any author
information if the post author is empty
.IP \(bu 2
Move LESS and Webassets support from Pelican core to plugin
.IP \(bu 2
The \fBDEFAULT_DATE\fP setting now defaults to \fBNone\fP, which means that
articles won\(aqt be generated unless date metadata is specified
.IP \(bu 2
Add \fBFILENAME_METADATA\fP setting to support metadata extraction from
filename
.IP \(bu 2
Add \fBgzip_cache\fP plugin to compress common text files into a \fB\&.gz\fP
file within the same directory as the original file, preventing the server
(e.g. Nginx) from having to compress files during an HTTP call
.IP \(bu 2
Add support for AsciiDoc\-formatted content
.IP \(bu 2
Add \fBUSE_FOLDER_AS_CATEGORY\fP setting so that feature can be toggled on/off
.IP \(bu 2
Support arbitrary Jinja template files
.IP \(bu 2
Restore basic functional tests
.IP \(bu 2
New signals: \fBgenerator_init\fP, \fBget_generators\fP, and
\fBarticle_generate_preread\fP
.UNINDENT
.SS 3.0 (2012\-08\-08)
.INDENT 0.0
.IP \(bu 2
Refactored the way URLs are handled
.IP \(bu 2
Improved the English documentation
.IP \(bu 2
Fixed packaging using \fBsetuptools\fP entrypoints
.IP \(bu 2
Added \fBtypogrify\fP support
.IP \(bu 2
Added a way to disable feed generation
.IP \(bu 2
Added support for \fBDIRECT_TEMPLATES\fP
.IP \(bu 2
Allow multiple extensions for content files
.IP \(bu 2
Added LESS support
.IP \(bu 2
Improved the import script
.IP \(bu 2
Added functional tests
.IP \(bu 2
Rsync support in the generated Makefile
.IP \(bu 2
Improved feed support (easily pluggable with Feedburner for instance)
.IP \(bu 2
Added support for \fBabbr\fP in reST
.IP \(bu 2
Fixed a bunch of bugs :\-)
.UNINDENT
.SS 2.8 (2012\-02\-28)
.INDENT 0.0
.IP \(bu 2
Dotclear importer
.IP \(bu 2
Allow the usage of Markdown extensions
.IP \(bu 2
Themes are now easily extensible
.IP \(bu 2
Don\(aqt output pagination information if there is only one page
.IP \(bu 2
Add a page per author, with all their articles
.IP \(bu 2
Improved the test suite
.IP \(bu 2
Made the themes easier to extend
.IP \(bu 2
Removed Skribit support
.IP \(bu 2
Added a \fBpelican\-quickstart\fP script
.IP \(bu 2
Fixed timezone\-related issues
.IP \(bu 2
Added some scripts for Windows support
.IP \(bu 2
Date can be specified in seconds
.IP \(bu 2
Never fail when generating posts (skip and continue)
.IP \(bu 2
Allow the use of future dates
.IP \(bu 2
Support having different timezones per language
.IP \(bu 2
Enhanced the documentation
.UNINDENT
.SS 2.7 (2011\-06\-11)
.INDENT 0.0
.IP \(bu 2
Use \fBlogging\fP rather than echoing to stdout
.IP \(bu 2
Support custom Jinja filters
.IP \(bu 2
Compatibility with Python 2.5
.IP \(bu 2
Added a theme manager
.IP \(bu 2
Packaged for Debian
.IP \(bu 2
Added draft support
.UNINDENT
.SS 2.6 (2011\-03\-08)
.INDENT 0.0
.IP \(bu 2
Changes in the output directory structure
.IP \(bu 2
Makes templates easier to work with / create
.IP \(bu 2
Added RSS support (was Atom\-only)
.IP \(bu 2
Added tag support for the feeds
.IP \(bu 2
Enhance the documentation
.IP \(bu 2
Added another theme (brownstone)
.IP \(bu 2
Added translations
.IP \(bu 2
Added a way to use cleaner URLs with a rewrite url module (or equivalent)
.IP \(bu 2
Added a tag cloud
.IP \(bu 2
Added an autoreloading feature: the blog is automatically regenerated each
time a modification is detected
.IP \(bu 2
Translate the documentation into French
.IP \(bu 2
Import a blog from an RSS feed
.IP \(bu 2
Pagination support
.IP \(bu 2
Added Skribit support
.UNINDENT
.SS 2.5 (2010\-11\-20)
.INDENT 0.0
.IP \(bu 2
Import from WordPress
.IP \(bu 2
Added some new themes (martyalchin / wide\-notmyidea)
.IP \(bu 2
First bug report!
.IP \(bu 2
Linkedin support
.IP \(bu 2
Added a FAQ
.IP \(bu 2
Google Analytics support
.IP \(bu 2
Twitter support
.IP \(bu 2
Use relative URLs, not static ones
.UNINDENT
.SS 2.4 (2010\-11\-06)
.INDENT 0.0
.IP \(bu 2
Minor themes changes
.IP \(bu 2
Add Disqus support (so we have comments)
.IP \(bu 2
Another code refactoring
.IP \(bu 2
Added config settings about pages
.IP \(bu 2
Blog entries can also be generated in PDF
.UNINDENT
.SS 2.3 (2010\-10\-31)
.INDENT 0.0
.IP \(bu 2
Markdown support
.UNINDENT
.SS 2.2 (2010\-10\-30)
.INDENT 0.0
.IP \(bu 2
Prettify output
.IP \(bu 2
Manages static pages as well
.UNINDENT
.SS 2.1 (2010\-10\-30)
.INDENT 0.0
.IP \(bu 2
Make notmyidea the default theme
.UNINDENT
.SS 2.0 (2010\-10\-30)
.INDENT 0.0
.IP \(bu 2
Refactoring to be more extensible
.IP \(bu 2
Change into the setting variables
.UNINDENT
.SS 1.2 (2010\-09\-28)
.INDENT 0.0
.IP \(bu 2
Added a debug option
.IP \(bu 2
Added per\-category feeds
.IP \(bu 2
Use filesystem to get dates if no metadata is provided
.IP \(bu 2
Add Pygments support
.UNINDENT
.SS 1.1 (2010\-08\-19)
.INDENT 0.0
.IP \(bu 2
First working version
.UNINDENT
.SH AUTHOR
Justin Mayer
.SH COPYRIGHT
2010–2024
.\" Generated by docutils manpage writer.
.