What’s the best way to communicate a problem, question, or suggestion?¶

There are several ways to help out. First, you can report any Pelican
suggestions or problems you might have via IRC (preferred) or the
issue tracker. If submitting
an issue report, please first check the existing issue list (both open and
closed) in order to avoid submitting a duplicate issue.

If you want to contribute, please fork the git repository, create a new feature branch, make
your changes, and issue a pull request. Someone will review your changes as
soon as possible. Please refer to the How to Contribute
section for more details.

You can also contribute by creating themes and improving the documentation.

Configuration files are optional and are just an easy way to configure Pelican.
For basic operations, it’s possible to specify options while invoking Pelican
via the command line. See pelican--help for more information.

When experimenting with different settings (especially the metadata
ones) caching may interfere and the changes may not be visible. In
such cases, ensure that caching is disabled via LOAD_CONTENT_CACHE=False
or use the --ignore-cache command-line switch.

I’m creating my own theme. How do I use Pygments for syntax highlighting?¶

Pygments adds some classes to the generated content. These classes are used by
themes to style code syntax highlighting via CSS. Specifically, you can
customize the appearance of your syntax highlighting via the .highlightpre
class in your theme’s CSS file. To see how various styles can be used to render
Django code, for example, use the style selector drop-down at top-right on the
Pygments project demo site.

You can use the following example commands to generate a starting CSS file from
a Pygments built-in style (in this case, “monokai”) and then copy the generated
CSS file to your new theme:

If you try to generate Markdown content without first installing the Markdown
library, may see a message that says Novalidfilesfoundincontent.
Markdown is not a hard dependency for Pelican, so if you have content in
Markdown format, you will need to explicitly install the Markdown library.
You can do so by typing the following command, prepending sudo if
permissions require it:

To disable feed generation, all feed settings should be set to None.
All but three feed settings already default to None, so if you want to
disable all feed generation, you only need to specify the following settings:

Starting in 3.0, some of the FEED setting names were changed to more explicitly
refer to the Atom feeds they inherently represent (much like the FEED_RSS
setting names). Here is an exact list of the renamed settings:

Starting in 3.1, the new feed FEED_ALL_ATOM has been introduced: this
feed will aggregate all posts regardless of their language. This setting
generates 'feeds/all.atom.xml' by default and FEED_ATOM now defaults to
None. The following feed setting has also been renamed:

TRANSLATION_FEED->TRANSLATION_FEED_ATOM

Older themes that referenced the old setting names may not link properly.
In order to rectify this, please update your theme for compatibility by changing
the relevant values in your template files. For an example of complete feed
headers and usage please check out the simple theme.

No. Pelican can be easily configured to create and maintain any type of static site.
This may require a little customization of your theme and Pelican configuration.
For example, if you are building a launch site for your product and do not need
tags on your site, you could remove the relevant HTML code from your theme.
You can also disable generation of tag-related pages via:

TAGS_SAVE_AS=''TAG_SAVE_AS=''

Why does Pelican always write all HTML files even with content caching enabled?¶

In order to reliably determine whether the HTML output is different
before writing it, a large part of the generation environment
including the template contexts, imported plugins, etc. would have to
be saved and compared, at least in the form of a hash (which would
require special handling of unhashable types), because of all the
possible combinations of plugins, pagination, etc. which may change in
many different ways. This would require a lot more processing time
and memory and storage space. Simply writing the files each time is a
lot faster and a lot more reliable.

However, this means that the modification time of the files changes
every time, so a rsync based upload will transfer them even if
their content hasn’t changed. A simple solution is to make rsync
use the --checksum option, which will make it compare the file
checksums in a much faster way than Pelican would.

When only several specific output files are of interest (e.g. when
working on some specific page or the theme templates), the
WRITE_SELECTED option may help, see
Writing only selected content.

It is often useful to process only e.g. 10 articles for debugging
purposes. This can be achieved by explicitly specifying only the
filenames of those articles in ARTICLE_PATHS. A list of such
filenames could be found using a command similar to cdcontent;find-name'*.md'|head-n10.

In an ongoing effort to steamline Pelican, tag_cloud generation has been
moved out of the pelican core and into a separate plugin.
See the Plugins documentation further information about the
Pelican plugin system.

Pages were available to themes as lowercase pages and uppercase
PAGES. To bring this inline with the Templates and variables section,
PAGES has been removed. This is quickly resolved by updating your theme
to iterate over pages instead of PAGES. Just replace:

{%forpginPAGES%}

with something like:

{%forpginpages%}

How can I stop Pelican from trying to parse my static files as content?¶

Pelican’s article and page generators run before it’s static generator. That
means if you use a setup similar to the default configuration, where a static
source directory is defined inside a *_PATHS setting, all files that have a
valid content file ending (.html, .rst, .md, ...) will be treated as
articles or pages before they get treated as static files.

To circumvent this issue either use the appropriate *_EXCLUDES setting or
disable the offending reader via READERS if you don’t need it.