github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Doc fixes and improvements

Browse source
This commit is contained in:
Justin Mayer 2012-12-03 16:31:55 -08:00
commit a07b56c02b
5 changed files with 127 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/faq.rst
View file

@ -1,7 +1,7 @@
Frequently Asked Questions (FAQ) Frequently Asked Questions (FAQ)
################################ ################################
Here is a summary of the frequently asked questions for Pelican. Here are some frequently asked questions about Pelican.
What's the best way to communicate a problem, question, or suggestion? What's the best way to communicate a problem, question, or suggestion?
====================================================================== ======================================================================
@ -21,7 +21,8 @@ How can I help?
================ ================
There are several ways to help out. First, you can use Pelican and report any There are several ways to help out. First, you can use Pelican and report any
suggestions or problems you might have via IRC or the `issue tracker <https://github.com/getpelican/pelican/issues>`_. suggestions or problems you might have via IRC or the `issue tracker
<https://github.com/getpelican/pelican/issues>`_.
If you want to contribute, please fork `the git repository If you want to contribute, please fork `the git repository
<https://github.com/getpelican/pelican/>`_, create a new feature branch, make <https://github.com/getpelican/pelican/>`_, create a new feature branch, make
@ -57,13 +58,14 @@ I want to use Markdown, but I got an error.
=========================================== ===========================================
Markdown is not a hard dependency for Pelican, so you will need to explicitly Markdown is not a hard dependency for Pelican, so you will need to explicitly
install it. You can do so by typing:: install it. You can do so by typing the following, including ``sudo`` if
required::
$ (sudo) pip install markdown (sudo) pip install markdown
In case you don't have pip installed, consider installing it via:: If you don't have pip installed, consider installing the pip installer via::
$ (sudo) easy_install pip (sudo) easy_install pip
Can I use arbitrary meta-data in my templates? Can I use arbitrary meta-data in my templates?
============================================== ==============================================
@ -87,15 +89,15 @@ want to have its own template.
:template: template_name :template: template_name
Then just make sure to have the template installed in to your theme as Then just make sure your theme contains the relevant template file (e.g.
``template_name.html``. ``template_name.html``).
What if I want to disable feed generation? What if I want to disable feed generation?
========================================== ==========================================
To disable all feed generation, all feed settings should be set to ``None``. To disable all feed generation, all feed settings should be set to ``None``.
Since other feed settings already defaults to ``None``, you only need to set All but two feed settings already default to ``None``, so if you want to disable
the following settings:: all feed generation, you only need to specify the following settings::
FEED_ALL_ATOM = None FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None CATEGORY_FEED_ATOM = None
@ -129,13 +131,13 @@ setting names). Here is an exact list of the renamed setting names::
CATEGORY_FEED -> CATEGORY_FEED_ATOM CATEGORY_FEED -> CATEGORY_FEED_ATOM
Starting in 3.1, the new feed ``FEED_ALL_ATOM`` has been introduced: this Starting in 3.1, the new feed ``FEED_ALL_ATOM`` has been introduced: this
feed will aggregate all posts regardless of their language. It is generated to feed will aggregate all posts regardless of their language. This setting
``'feeds/all.atom.xml'`` by default and ``FEED_ATOM`` now defaults to ``None``. generates ``'feeds/all.atom.xml'`` by default and ``FEED_ATOM`` now defaults to
The following FEED setting has also been renamed:: ``None``. The following feed setting has also been renamed::
TRANSLATION_FEED -> TRANSLATION_FEED_ATOM TRANSLATION_FEED -> TRANSLATION_FEED_ATOM
Older 2.x themes that referenced the old setting names may not link properly. Older themes that referenced the old setting names may not link properly.
In order to rectify this, please update your theme for compatibility with 3.0+ In order to rectify this, please update your theme for compatibility by changing
by changing the relevant values in your template files. For an example of the relevant values in your template files. For an example of complete feed
complete feed headers and usage please check out the ``simple`` theme. headers and usage please check out the ``simple`` theme.

50
docs/getting_started.rst
View file

@ -161,7 +161,7 @@ following syntax (give your file the ``.rst`` extension)::
:author: Alexis Metaireau :author: Alexis Metaireau
:summary: Short version for index and feeds :summary: Short version for index and feeds
Pelican implements an extension of reStructuredText to enable support for the Pelican implements an extension to reStructuredText to enable support for the
``abbr`` HTML tag. To use it, write something like this in your post:: ``abbr`` HTML tag. To use it, write something like this in your post::
This will be turned into :abbr:`HTML (HyperText Markup Language)`. This will be turned into :abbr:`HTML (HyperText Markup Language)`.
@ -188,16 +188,17 @@ directory in which the file resides. For example, a file located at
``python/foobar/myfoobar.rst`` will have a category of ``foobar``. If you would ``python/foobar/myfoobar.rst`` will have a category of ``foobar``. If you would
like to organize your files in other ways where the name of the subfolder would like to organize your files in other ways where the name of the subfolder would
not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY`` not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
to ``False``. If summary isn't given, setting ``SUMMARY_MAX_LENGTH`` determines to ``False``. If there is no summary metadata for a given post, the
how many words from the beginning of an article are used as the summary. ``SUMMARY_MAX_LENGTH`` setting can be used to specify how many words from the
beginning of an article are used as the summary.
You can also extract any metadata from the filename through a regexp to be set You can also extract any metadata from the filename through a regular
in the ``FILENAME_METADATA`` setting. expression to be set in the ``FILENAME_METADATA`` setting.
All named groups that are matched will be set in the metadata object. The All named groups that are matched will be set in the metadata object. The
default value for the ``FILENAME_METADATA`` setting will only extract the date default value for the ``FILENAME_METADATA`` setting will only extract the date
from the filename. For example, if you would like to extract both the date and from the filename. For example, if you would like to extract both the date and
the slug, you could set something like: the slug, you could set something like:
``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``. ``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``
Please note that the metadata available inside your files takes precedence over Please note that the metadata available inside your files takes precedence over
the metadata extracted from the filename. the metadata extracted from the filename.
@ -205,7 +206,7 @@ the metadata extracted from the filename.
Generate your blog Generate your blog
------------------ ------------------
The ``make`` shortcut commands mentioned in the ``Kickstart a blog`` section The ``make`` shortcut commands mentioned in the *Kickstart a blog* section
are mostly wrappers around the ``pelican`` command that generates the HTML from are mostly wrappers around the ``pelican`` command that generates the HTML from
the content. The ``pelican`` command can also be run directly:: the content. The ``pelican`` command can also be run directly::
@ -231,11 +232,11 @@ run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
Pages Pages
----- -----
If you create a folder named ``pages``, itself in the content folder, all the If you create a folder named ``pages`` inside the content folder, all the
files in it will be used to generate static pages. files in it will be used to generate static pages.
Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to Then, use the ``DISPLAY_PAGES_ON_MENU`` setting to add all those pages to
the menu. the primary navigation menu.
If you want to exclude any pages from being linked to or listed in the menu If you want to exclude any pages from being linked to or listed in the menu
then add a ``status: hidden`` attribute to its metadata. This is useful for then add a ``status: hidden`` attribute to its metadata. This is useful for
@ -244,9 +245,13 @@ things like making error pages that fit the generated theme of your site.
Linking to internal content Linking to internal content
--------------------------- ---------------------------
Since Pelican 3.1, you now have the ability to do cross-site linking. From Pelican 3.1 onwards, it is now possible to specify intra-site links to
files in the *source content* hierarchy instead of files in the *generated*
hierarchy. This makes it easier to link from the current post to other posts
and images that may be sitting alongside the current post (instead of having
to determine where those resources will be placed after site generation).
To link to an internal content, you will have to use the following syntax: To link to internal content, use the following syntax:
``|filename|path/to/file``. ``|filename|path/to/file``.
For example, you may want to add links between "article1" and "article2" given For example, you may want to add links between "article1" and "article2" given
@ -264,20 +269,20 @@ In this example, ``article1.rst`` could look like::
Title: The first article Title: The first article
Date: 2012-12-01 Date: 2012-12-01
See below cross-site links examples in restructured text. See below intra-site link examples in reStructuredText format.
`a root-relative link <|filename|/cat/article2.md>`_ `a link relative to content root <|filename|/cat/article2.md>`_
`a file-relative link <|filename|cat/article2.md>`_ `a link relative to current file <|filename|cat/article2.md>`_
and ``article2.md``:: and ``article2.md``::
Title: The second article Title: The second article
Date: 2012-12-01 Date: 2012-12-01
See below cross-site links examples in markdown. See below intra-site link examples in Markdown format.
[a root-relative link](|filename|/article1.rst) [a link relative to content root](|filename|/article1.rst)
[a file-relative link](|filename|../article1.rst) [a link relative to current file](|filename|../article1.rst)
.. note:: .. note::
@ -334,13 +339,12 @@ then instead ensure that the translated article titles are identical, since the
slug will be auto-generated from the article title. slug will be auto-generated from the article title.
Syntax highlighting Syntax highlighting
--------------------- -------------------
Pelican is able to provide colorized syntax highlighting for your code blocks. Pelican is able to provide colorized syntax highlighting for your code blocks.
To do so, you have to use the following conventions (you need to put this in To do so, you have to use the following conventions inside your content files.
your content files).
For RestructuredText, use the code-block directive:: For reStructuredText, use the code-block directive::
.. code-block:: identifier .. code-block:: identifier
@ -373,7 +377,7 @@ anything special to see what's happening with the generated files.
You can either use your browser to open the files on your disk:: You can either use your browser to open the files on your disk::
$ firefox output/index.html firefox output/index.html
Or run a simple web server using Python:: Or run a simple web server using Python::

2
docs/index.rst
View file

@ -4,7 +4,7 @@ Pelican
Pelican is a static site generator, written in Python_. Pelican is a static site generator, written in Python_.
* Write your weblog entries directly with your editor of choice (vim!) * Write your weblog entries directly with your editor of choice (vim!)
in reStructuredText_, Markdown_ or AsciiDoc_ in reStructuredText_, Markdown_, or AsciiDoc_
* Includes a simple CLI tool to (re)generate the weblog * Includes a simple CLI tool to (re)generate the weblog
* Easy to interface with DVCSes and web hooks * Easy to interface with DVCSes and web hooks
* Completely static output is easy to host anywhere * Completely static output is easy to host anywhere

88
docs/plugins.rst
View file

@ -3,25 +3,25 @@
Plugins Plugins
####### #######
Since version 3.0, Pelican manages plugins. Plugins are a way to add features Beginning with version 3.0, Pelican supports plugins. Plugins are a way to add
to Pelican without having to directly hack Pelican code. features to Pelican without having to directly modify the Pelican core.
Pelican is shipped with a set of core plugins, but you can easily implement Pelican is shipped with a set of bundled plugins, but you can easily implement
your own (and this page describes how). your own. This page describes how to use and create plugins.
How to use plugins How to use plugins
================== ==================
To load plugins, you have to specify them in your settings file. You have two To load plugins, you have to specify them in your settings file. There are two
ways to do so. ways to do so. The first method is to specify strings with the path to the
Either by specifying strings with the path to the callables:: callables::
PLUGINS = ['pelican.plugins.gravatar',] PLUGINS = ['pelican.plugins.gravatar',]
Or by importing them and adding them to the list:: Alternatively, another method is to import them and add them to the list::
from pelican.plugins import gravatar from pelican.plugins import gravatar
PLUGINS = [gravatar, ] PLUGINS = [gravatar,]
If your plugins are not in an importable path, you can specify a ``PLUGIN_PATH`` If your plugins are not in an importable path, you can specify a ``PLUGIN_PATH``
in the settings:: in the settings::
@ -33,7 +33,7 @@ How to create plugins
===================== =====================
Plugins are based on the concept of signals. Pelican sends signals, and plugins Plugins are based on the concept of signals. Pelican sends signals, and plugins
subscribe to those signals. The list of signals are defined in a following subscribe to those signals. The list of signals are defined in a subsequent
section. section.
The only rule to follow for plugins is to define a ``register`` callable, in The only rule to follow for plugins is to define a ``register`` callable, in
@ -75,13 +75,13 @@ pages_generate_context pages_generator, metadata
pages_generator_init pages_generator invoked in the PagesGenerator.__init__ pages_generator_init pages_generator invoked in the PagesGenerator.__init__
============================= ============================ =========================================================================== ============================= ============================ ===========================================================================
The list is currently small, don't hesitate to add signals and make a pull The list is currently small, so don't hesitate to add signals and make a pull
request if you need them! request if you need them!
.. note:: .. note::
The signal ``content_object_init`` can send different type of object as The signal ``content_object_init`` can send a different type of object as
argument. If you want to register only one type of object then you will the argument. If you want to register only one type of object then you will
need to specify the sender when you are connecting to the signal. need to specify the sender when you are connecting to the signal.
:: ::
@ -122,30 +122,30 @@ Plugin descriptions
Asset management Asset management
---------------- ----------------
This plugin allows you to use the `webassets`_ module to manage assets such as This plugin allows you to use the `Webassets`_ module to manage assets such as
CSS and JS files. The module must first be installed:: CSS and JS files. The module must first be installed::
pip install webassets pip install webassets
The `webassets` module allows you to perform a number of useful asset management The Webassets module allows you to perform a number of useful asset management
functions, including: functions, including:
* CSS minifier (`cssmin`, `yuicompressor`, ...) * CSS minifier (``cssmin``, ``yuicompressor``, ...)
* CSS compiler (`less`, `sass`, ...) * CSS compiler (``less``, ``sass``, ...)
* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...) * JS minifier (``uglifyjs``, ``yuicompressor``, ``closure``, ...)
Others filters include gzip compression, integration of images in CSS via data Others filters include gzip compression, integration of images in CSS via data
URIs, and more. `webassets` can also append a version identifier to your asset URIs, and more. Webassets can also append a version identifier to your asset
URL to convince browsers to download new versions of your assets when you use URL to convince browsers to download new versions of your assets when you use
far-future expires headers. Please refer to the `webassets documentation`_ for far-future expires headers. Please refer to the `Webassets documentation`_ for
more information. more information.
When using with Pelican, `webassets` is configured to process assets in the When used with Pelican, Webassets is configured to process assets in the
``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by ``OUTPUT_PATH/theme`` directory. You can use Webassets in your templates by
including one or more template tags. The jinja variable ``{{ ASSET_URL }}`` to including one or more template tags. The Jinja variable ``{{ ASSET_URL }}`` can
use in the templates is configured to be relative to the ``theme/`` url. be used in templates and is relative to the ``theme/`` url. The
Hence, it must be used with the ``{{ SITEURL }}`` variable which allows to ``{{ ASSET_URL }}`` variable should be used in conjunction with the
have relative urls. For example... ``{{ SITEURL }}`` variable in order to generate URLs properly. For example:
.. code-block:: jinja .. code-block:: jinja
@ -153,7 +153,7 @@ have relative urls. For example...
<link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}"> <link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}">
{% endassets %} {% endassets %}
... will produce a minified css file with a version identifier: ... will produce a minified css file with a version identifier that looks like:
.. code-block:: html .. code-block:: html
@ -182,29 +182,29 @@ The above will produce a minified and gzipped JS file:
<script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script> <script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
Pelican's debug mode is propagated to `webassets` to disable asset packaging Pelican's debug mode is propagated to Webassets to disable asset packaging
and instead work with the uncompressed assets. However, this also means that and instead work with the uncompressed assets. However, this also means that
the LESS and SASS files are not compiled. This should be fixed in a future the LESS and SASS files are not compiled. This should be fixed in a future
version of `webassets` (cf. the related `bug report version of Webassets (cf. the related `bug report
<https://github.com/getpelican/pelican/issues/481>`_). <https://github.com/getpelican/pelican/issues/481>`_).
.. _webassets: https://github.com/miracle2k/webassets .. _Webassets: https://github.com/miracle2k/webassets
.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html .. _Webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
GitHub activity GitHub activity
--------------- ---------------
This plugin makes use of the ``feedparser`` library that you'll need to This plugin makes use of the `feedparser`_ library that you'll need to
install. install.
Set the ``GITHUB_ACTIVITY_FEED`` parameter to your GitHub activity feed. Set the ``GITHUB_ACTIVITY_FEED`` parameter to your GitHub activity feed.
For example, my setting would look like:: For example, to track Pelican project activity, the setting would be::
GITHUB_ACTIVITY_FEED = 'https://github.com/kpanic.atom' GITHUB_ACTIVITY_FEED = 'https://github.com/getpelican.atom'
On the templates side, you just have to iterate over the ``github_activity`` On the template side, you just have to iterate over the ``github_activity``
variable, as in the example:: variable, as in this example::
{% if GITHUB_ACTIVITY_FEED %} {% if GITHUB_ACTIVITY_FEED %}
<div class="social"> <div class="social">
@ -218,15 +218,15 @@ variable, as in the example::
</div><!-- /.github_activity --> </div><!-- /.github_activity -->
{% endif %} {% endif %}
``github_activity`` is a list of lists. The first element is the title,
``github_activity`` is a list of lists. The first element is the title
and the second element is the raw HTML from GitHub. and the second element is the raw HTML from GitHub.
.. _feedparser: https://crate.io/packages/feedparser/
Global license Global license
-------------- --------------
This plugin allows you to define a LICENSE setting and adds the contents of that This plugin allows you to define a ``LICENSE`` setting and adds the contents of that
license variable to the article's context, making that variable available to use license variable to the article's context, making that variable available to use
from within your theme's templates. from within your theme's templates.
@ -235,7 +235,7 @@ Gravatar
This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
makes the variable available within the article's context. You can add makes the variable available within the article's context. You can add
AUTHOR_EMAIL to your settings file to define the default author's email ``AUTHOR_EMAIL`` to your settings file to define the default author's email
address. Obviously, that email address must be associated with a Gravatar address. Obviously, that email address must be associated with a Gravatar
account. account.
@ -249,7 +249,7 @@ the ``author_gravatar`` variable is added to the article's context.
Gzip cache Gzip cache
---------- ----------
Certain web servers (e.g., Nginx) can use a static cache of gzip compressed Certain web servers (e.g., Nginx) can use a static cache of gzip-compressed
files to prevent the server from compressing files during an HTTP call. Since files to prevent the server from compressing files during an HTTP call. Since
compression occurs at another time, these compressed files can be compressed compression occurs at another time, these compressed files can be compressed
at a higher compression level for increased optimization. at a higher compression level for increased optimization.
@ -303,7 +303,7 @@ The sitemap plugin generates plain-text or XML sitemaps. You can use the
``SITEMAP`` variable in your settings file to configure the behavior of the ``SITEMAP`` variable in your settings file to configure the behavior of the
plugin. plugin.
The ``SITEMAP`` variable must be a Python dictionary, it can contain three keys: The ``SITEMAP`` variable must be a Python dictionary and can contain three keys:
- ``format``, which sets the output format of the plugin (``xml`` or ``txt``) - ``format``, which sets the output format of the plugin (``xml`` or ``txt``)
@ -336,7 +336,7 @@ default value.
The sitemap is saved in ``<output_path>/sitemap.<format>``. The sitemap is saved in ``<output_path>/sitemap.<format>``.
.. note:: .. note::
``priorities`` and ``changefreqs`` are informations for search engines. ``priorities`` and ``changefreqs`` are information for search engines.
They are only used in the XML sitemaps. They are only used in the XML sitemaps.
For more information: <http://www.sitemaps.org/protocol.html#xmlTagDefinitions> For more information: <http://www.sitemaps.org/protocol.html#xmlTagDefinitions>

75
docs/settings.rst
View file

@ -16,8 +16,8 @@ False, None, etc.), dictionaries, or tuples should *not* be enclosed in
quotation marks. All other values (i.e., strings) *must* be enclosed in quotation marks. All other values (i.e., strings) *must* be enclosed in
quotation marks. quotation marks.
Unless otherwise specified, settings that refer to paths can be either absolute or relative to the Unless otherwise specified, settings that refer to paths can be either absolute
configuration file. or relative to the configuration file.
The settings you define in the configuration file will be passed to the The settings you define in the configuration file will be passed to the
templates, which allows you to use your settings to add site-wide content. templates, which allows you to use your settings to add site-wide content.
@ -31,12 +31,11 @@ Basic settings
Setting name (default value) What does it do? Setting name (default value) What does it do?
===================================================================== ===================================================================== ===================================================================== =====================================================================
`AUTHOR` Default author (put your name) `AUTHOR` Default author (put your name)
`DATE_FORMATS` (``{}``) If you do manage multiple languages, you can `DATE_FORMATS` (``{}``) If you manage multiple languages, you can set the date formatting
set the date formatting here. See "Date format and locales" here. See the "Date format and locales" section below for details.
section below for details. `USE_FOLDER_AS_CATEGORY` (``True``) When you don't specify a category in your post metadata, set this
`USE_FOLDER_AS_CATEGORY` (``True``) When you don't specify a category in your post metadata and set this setting to ``True``, and organize your articles in subfolders, the
setting to ``True`` and organize your articles in subfolders, the subfolder will become the category of your post. If set to ``False``,
subfolder will become the category of your post. If set to ``False``
``DEFAULT_CATEGORY`` will be used as a fallback. ``DEFAULT_CATEGORY`` will be used as a fallback.
`DEFAULT_CATEGORY` (``'misc'``) The default category to fall back on. `DEFAULT_CATEGORY` (``'misc'``) The default category to fall back on.
`DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use. `DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use.
@ -44,12 +43,12 @@ Setting name (default value) What doe
template. Templates may or not honor this template. Templates may or not honor this
setting. setting.
`DEFAULT_DATE` (``None``) The default date you want to use. `DEFAULT_DATE` (``None``) The default date you want to use.
If 'fs', Pelican will use the file system If ``fs``, Pelican will use the file system
timestamp information (mtime) if it can't get timestamp information (mtime) if it can't get
date information from the metadata. date information from the metadata.
If tuple object, it will instead generate the If set to a tuple object, the default datetime object will instead
default datetime object by passing the tuple to be generated by passing the tuple to the
the datetime.datetime constructor. ``datetime.datetime`` constructor.
`DEFAULT_METADATA` (``()``) The default metadata you want to use for all articles `DEFAULT_METADATA` (``()``) The default metadata you want to use for all articles
and pages. and pages.
`FILENAME_METADATA` (``'(?P<date>\d{4}-\d{2}-\d{2}).*'``) The regexp that will be used to extract any metadata `FILENAME_METADATA` (``'(?P<date>\d{4}-\d{2}-\d{2}).*'``) The regexp that will be used to extract any metadata
@ -83,11 +82,10 @@ Setting name (default value) What doe
`PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages. `PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages.
`ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`. `ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`.
`ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles. `ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles.
`PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions `PDF_GENERATOR` (``False``) Set to ``True`` if you want PDF versions of your documents to be.
of your documents. You will need to install generated. You will need to install ``rst2pdf``.
`rst2pdf`.
`OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their `OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their
original format (e.g. Markdown or ReStructeredText) to the original format (e.g. Markdown or reStructuredText) to the
specified OUTPUT_PATH. specified OUTPUT_PATH.
`OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator. `OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator.
Defaults to ``.text``. If not a valid string the default value Defaults to ``.text``. If not a valid string the default value
@ -106,10 +104,10 @@ Setting name (default value) What doe
the blog entries. See :ref:`template_pages`. the blog entries. See :ref:`template_pages`.
`STATIC_PATHS` (``['images']``) The static paths you want to have accessible `STATIC_PATHS` (``['images']``) The static paths you want to have accessible
on the output path "static". By default, on the output path "static". By default,
Pelican will copy the 'images' folder to the Pelican will copy the "images" folder to the
output folder. output folder.
`TIMEZONE` The timezone used in the date information, to `TIMEZONE` The timezone used in the date information, to
generate Atom and RSS feeds. See the "timezone" generate Atom and RSS feeds. See the *Timezone*
section below for more info. section below for more info.
`TYPOGRIFY` (``False``) If set to True, several typographical improvements will be `TYPOGRIFY` (``False``) If set to True, several typographical improvements will be
incorporated into the generated HTML via the `Typogrify incorporated into the generated HTML via the `Typogrify
@ -117,19 +115,19 @@ Setting name (default value) What doe
library, which can be installed via: ``pip install typogrify`` library, which can be installed via: ``pip install typogrify``
`DIRECT_TEMPLATES` (``('index', 'tags', 'categories', 'archives')``) List of templates that are used directly to render `DIRECT_TEMPLATES` (``('index', 'tags', 'categories', 'archives')``) List of templates that are used directly to render
content. Typically direct templates are used to generate content. Typically direct templates are used to generate
index pages for collections of content e.g. tags and index pages for collections of content (e.g. tags and
category index pages. category index pages).
`PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated. `PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated.
`SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will `SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will
be the default length in words of the text created. be the default length in words of the text created.
This only applies if your content does not otherwise This only applies if your content does not otherwise
specify a summary. Setting to None will cause the summary specify a summary. Setting to ``None`` will cause the summary
to be a copy of the original content. to be a copy of the original content.
`EXTRA_TEMPLATES_PATHS` (``[]``) A list of paths you want Jinja2 to look for the templates. `EXTRA_TEMPLATES_PATHS` (``[]``) A list of paths you want Jinja2 to search for templates.
Can be used to separate templates from the theme. Can be used to separate templates from the theme.
Example: projects, resume, profile ... Example: projects, resume, profile ...
This templates need to use ``DIRECT_TEMPLATES`` setting These templates need to use ``DIRECT_TEMPLATES`` setting.
`ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to asciidoc, see the `manpage `ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to AsciiDoc. See the `manpage
<http://www.methods.co.nz/asciidoc/manpage.html>`_ <http://www.methods.co.nz/asciidoc/manpage.html>`_
===================================================================== ===================================================================== ===================================================================== =====================================================================
@ -145,13 +143,13 @@ when testing locally, and absolute URLs are reliable and most useful when
publishing. One method of supporting both is to have one Pelican configuration publishing. One method of supporting both is to have one Pelican configuration
file for local development and another for publishing. To see an example of this file for local development and another for publishing. To see an example of this
type of setup, use the ``pelican-quickstart`` script as described at the top of type of setup, use the ``pelican-quickstart`` script as described at the top of
the :doc:`Getting Started<getting_started>` page, which will produce two separate the :doc:`Getting Started <getting_started>` page, which will produce two separate
configuration files for local development and publishing, respectively. configuration files for local development and publishing, respectively.
You can customize the URLs and locations where files will be saved. The URLs and You can customize the URLs and locations where files will be saved. The URLs and
SAVE_AS variables use Python's format strings. These variables allow you to place SAVE_AS variables use Python's format strings. These variables allow you to place
your articles in a location such as '{slug}/index.html' and link to them as your articles in a location such as ``{slug}/index.html`` and link to them as
'{slug}' for clean URLs. These settings give you the flexibility to place your ``{slug}`` for clean URLs. These settings give you the flexibility to place your
articles and pages anywhere you want. articles and pages anywhere you want.
.. note:: .. note::
@ -175,8 +173,8 @@ Example usage:
* ARTICLE_URL = ``'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'`` * ARTICLE_URL = ``'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'``
* ARTICLE_SAVE_AS = ``'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'`` * ARTICLE_SAVE_AS = ``'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'``
This would save your articles in something like '/posts/2011/Aug/07/sample-post/index.html', This would save your articles in something like ``/posts/2011/Aug/07/sample-post/index.html``,
and the URL to this would be '/posts/2011/Aug/07/sample-post/'. and the URL to this would be ``/posts/2011/Aug/07/sample-post/``.
==================================================== ===================================================== ==================================================== =====================================================
Setting name (default value) What does it do? Setting name (default value) What does it do?
@ -206,7 +204,7 @@ Setting name (default value) What does it do?
.. note:: .. note::
When any of `*_SAVE_AS` is set to False, files will not be created. When any of the `*_SAVE_AS` settings is set to False, files will not be created.
Timezone Timezone
-------- --------
@ -283,12 +281,12 @@ If you want to generate custom pages besides your blog entries, you can point
any Jinja2 template file with a path pointing to the file and the destination any Jinja2 template file with a path pointing to the file and the destination
path for the generated file. path for the generated file.
For instance, if you have a blog with three static pages, for a list of books, For instance, if you have a blog with three static pages — a list of books,
your resume and a contact page, you could have:: your resume, and a contact page — you could have::
TEMPLATE_PAGES = {'src/books.html': 'dest/books.html', TEMPLATE_PAGES = {'src/books.html': 'dest/books.html',
'src/resume.html': 'dest/resume.html', 'src/resume.html': 'dest/resume.html',
'src/contact.html': 'dest/contact.html'} 'src/contact.html': 'dest/contact.html'}
Feed settings Feed settings
============= =============
@ -326,8 +324,7 @@ Setting name (default value) What does it do?
quantity is unrestricted by default. quantity is unrestricted by default.
================================================ ===================================================== ================================================ =====================================================
If you don't want to generate some or any of these feeds, set ``None`` to the If you don't want to generate some or any of these feeds, set the above variables to ``None``.
variables above.
.. [2] %s is the name of the category. .. [2] %s is the name of the category.
@ -399,7 +396,7 @@ N matches `TAG_CLOUD_STEPS` -1).
Translations Translations
============ ============
Pelican offers a way to translate articles. See the Getting Started section for Pelican offers a way to translate articles. See the :doc:`Getting Started <getting_started>` section for
more information. more information.
===================================================== ===================================================== ===================================================== =====================================================
@ -467,7 +464,7 @@ Following are example ways to specify your preferred theme::
# Specify a customized theme, via absolute path # Specify a customized theme, via absolute path
THEME = "~/projects/mysite/themes/mycustomtheme" THEME = "~/projects/mysite/themes/mycustomtheme"
The built-in `notmyidea` theme can make good use of the following settings. Feel The built-in ``notmyidea`` theme can make good use of the following settings. Feel
free to use them in your themes as well. free to use them in your themes as well.
======================= ======================================================= ======================= =======================================================
@ -496,7 +493,7 @@ Setting name What does it do ?
if you want this button to appear. if you want this button to appear.
======================= ======================================================= ======================= =======================================================
In addition, you can use the "wide" version of the `notmyidea` theme by In addition, you can use the "wide" version of the ``notmyidea`` theme by
adding the following to your configuration:: adding the following to your configuration::
CSS_FILE = "wide.css" CSS_FILE = "wide.css"