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

Merge branch 'master' into typogrify-dashes

Browse source
This commit is contained in:
Justin Mayer 2020-04-16 09:46:50 +02:00 • committed by GitHub
commit a76280391d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
244 changed files with 3160 additions and 1867 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/changelog.rst
View file

@ -1,6 +1,51 @@
Release history
###############
4.2.0 - 2019-10-17
==================
* Support inline SVGs; don't treat titles in SVGs as HTML titles
* Add category to feeds (in addition to tags)
* Improve content metadata field docs
* Add docs for including other Markdown/reST files in content
4.1.3 - 2019-10-09
==================
* Fix quick-start docs regarding `pelican --listen`
* Set default listen address to 127.0.0.1
* Add extra/optional Markdown dependency to setup.py
* Use correct SSH port syntax for rsync in tasks.py
* Place all deprecated settings handling together
* Add related project URLs for display on PyPI
* Skip some tests on Windows that can't pass due to filesystem differences
4.1.2 - 2019-09-23
==================
Fix pelican.settings.load_source to avoid caching issues - PR #2621
4.1.1 - 2019-08-23
==================
* Add AutoPub to auto-publish releases on PR merge
* Add CSS classes for reStructuredText figures
* Pass `argv` to Pelican `main` entrypoint
* Set default content status to a blank string rather than `None`
4.1.0 - 2019-07-14
==================
* Live browser reload upon changed files (provided via Invoke task)
* Add ``pyproject.toml``, managed by Poetry
* Support for invoking ``python -m pelican``
* Add relative source path attribute to content
* Allow directories in ``EXTRA_PATH_METADATA``
* Add ``all_articles`` variable to period pages (for recent posts functionality)
* Improve debug mode output
* Remove blank or duplicate summaries from Atom feed
* Fix bugs in pagination, pelican-import, pelican-quickstart, and feed importer
4.0.1 (2018-11-30)
==================
@ -14,7 +59,7 @@ settings are encountered, Pelican will emit a warning and fall back to the
default setting. Some user-submitted themes might try to format setting values
but fail upon site build with a ``TypeError``. In such cases, the theme needs
to be updated. For example, instead of ``TAG_FEED_ATOM|format(tag.slug)``, use
``TAG_FEED_ATOM|format(slug=tag.slug)``
``TAG_FEED_ATOM.format(slug=tag.slug)``
4.0.0 (2018-11-13)
==================

11
docs/conf.py
View file

@ -1,5 +1,4 @@
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
import os
import sys
@ -18,11 +17,11 @@ extensions = ['sphinx.ext.autodoc',
source_suffix = '.rst'
master_doc = 'index'
project = 'Pelican'
copyright = '2010, Alexis Metaireau and contributors'
copyright = '2010 – present, Justin Mayer, Alexis Metaireau, and contributors'
exclude_patterns = ['_build']
release = __version__
version = '.'.join(release.split('.')[:1])
last_stable = '4.0.1'
last_stable = __version__
rst_prolog = '''
.. |last_stable| replace:: :pelican-doc:`{0}`
'''.format(last_stable)
@ -31,7 +30,7 @@ rst_prolog = '''
pygments_style = 'sphinx'
extlinks = {
'pelican-doc': ('http://docs.getpelican.com/%s/', '')
'pelican-doc': ('https://docs.getpelican.com/%s/', '')
}
# -- Options for HTML output --------------------------------------------------
@ -69,14 +68,14 @@ def setup(app):
# -- Options for LaTeX output -------------------------------------------------
latex_documents = [
('index', 'Pelican.tex', 'Pelican Documentation', 'Alexis Métaireau',
('index', 'Pelican.tex', 'Pelican Documentation', 'Justin Mayer',
'manual'),
]
# -- Options for manual page output -------------------------------------------
man_pages = [
('index', 'pelican', 'pelican documentation',
['Alexis Métaireau'], 1),
['Justin Mayer'], 1),
('pelican-themes', 'pelican-themes', 'A theme manager for Pelican',
['Mickaël Raybaud'], 1),
('themes', 'pelican-theming', 'How to create themes for Pelican',

100
docs/content.rst
View file

@ -71,22 +71,29 @@ Metadata syntax for Markdown posts should follow this pattern::
This is the content of my super blog post.
You can also have your own metadata keys (so long as they don't conflict with
reserved metadata keywords) for use in your python templates. The following is
the list of reserved metadata keywords:
reserved metadata keywords) for use in your templates. The following table
contains a list of reserved metadata keywords:
* `Title`
* `Tags`
* `Date`
* `Modified`
* `Status`
* `Category`
* `Author`
* `Authors`
* `Slug`
* `Summary`
* `Template`
* `Save_as`
* `Url`
=============== ===============================================================
Metadata Description
=============== ===============================================================
``title`` Title of the article or page
``date`` Publication date (e.g., ``YYYY-MM-DD HH:SS``)
``modified`` Modification date (e.g., ``YYYY-MM-DD HH:SS``)
``tags`` Content tags, separated by commas
``keywords`` Content keywords, separated by commas (HTML content only)
``category`` Content category (one only — not multiple)
``slug`` Identifier used in URLs and translations
``author`` Content author, when there is only one
``authors`` Content authors, when there are multiple
``summary`` Brief description of content for index pages
``lang`` Content language ID (``en``, ``fr``, etc.)
``translation`` Is content is a translation of another (``true`` or ``false``)
``status`` Content status: ``draft``, ``hidden``, or ``published``
``template`` Name of template to use to generate content (without extension)
``save_as`` Save content to this relative file path
``url`` URL to use for this article/page
=============== ===============================================================
Readers for additional formats (such as AsciiDoc_) are available via plugins.
Refer to `pelican-plugins`_ repository for those.
@ -116,7 +123,7 @@ specified either via the ``tags`` metadata, as is standard in Pelican, or via
the ``keywords`` metadata, as is standard in HTML. The two can be used
interchangeably.
Note that, aside from the title, none of this article metadata is mandatory:
Note that, aside from the title, none of this content metadata is mandatory:
if the date is not specified and ``DEFAULT_DATE`` is set to ``'fs'``, Pelican
will rely on the file's "mtime" timestamp, and the category can be determined
by the directory in which the file resides. For example, a file located at
@ -126,6 +133,15 @@ not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
to ``False``. When parsing dates given in the page metadata, Pelican supports
the W3C's `suggested subset ISO 8601`__.
So the title is the only required metadata. If that bothers you, worry not.
Instead of manually specifying a title in your metadata each time, you can use
the source content file name as the title. For example, a Markdown source file
named ``Publishing via Pelican.md`` would automatically be assigned a title of
*Publishing via Pelican*. If you would prefer this behavior, add the following
line to your settings file::
FILENAME_METADATA = '(?P<title>.*)'
.. note::
When experimenting with different settings (especially the metadata
@ -354,6 +370,10 @@ of ``{attach}``, and letting the file's location be determined by the project's
``STATIC_SAVE_AS`` and ``STATIC_URL`` settings. (Per-file ``save_as`` and
``url`` overrides can still be set in ``EXTRA_PATH_METADATA``.)
.. note::
When using ``{attach}``, any parent directory in ``*_URL`` / ``*_SAVE_AS``
settings should match each other. See also: :ref:`url-settings`
Linking to authors, categories, index and tags
----------------------------------------------
@ -373,6 +393,40 @@ to allow linking to both generated articles and pages and their static sources.
Support for the old syntax may eventually be removed.
Including other files
---------------------
Both Markdown and reStructuredText syntaxes provide mechanisms for this.
Following below are some examples for **reStructuredText** using `the include directive`_:
.. code-block:: rst
.. include:: file.rst
Include a fragment of a file delimited by two identifiers, highlighted as C++ (slicing based on line numbers is also possible):
.. code-block:: rst
.. include:: main.cpp
:code: c++
:start-after: // begin
:end-before: // end
Include a raw HTML file (or an inline SVG) and put it directly into the output without any processing:
.. code-block:: rst
.. raw:: html
:file: table.html
For **Markdown**, one must rely on an extension. For example, using the `mdx_include plugin`_:
.. code-block:: none
```html
{! template.html !}
```
Importing an existing site
==========================
@ -474,7 +528,7 @@ indenting both the identifier and the code::
print("The path-less shebang syntax *will* show line numbers.")
The specified identifier (e.g. ``python``, ``ruby``) should be one that
appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
appears on the `list of available lexers <https://pygments.org/docs/lexers/>`_.
When using reStructuredText the following options are available in the
code-block directive:
@ -515,7 +569,7 @@ tagurlformat string format for the ctag links.
Note that, depending on the version, your Pygments module might not have
all of these options available. Refer to the *HtmlFormatter* section of the
`Pygments documentation <http://pygments.org/docs/formatters/>`_ for more
`Pygments documentation <https://pygments.org/docs/formatters/>`_ for more
details on each of the options.
For example, the following code block enables line numbers, starting at 153,
@ -560,9 +614,11 @@ the ``DEFAULT_METADATA``::
To publish a post when the default status is ``draft``, update the post's
metadata to include ``Status: published``.
.. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
.. _pelican-plugins: http://github.com/getpelican/pelican-plugins
.. _W3C ISO 8601: https://www.w3.org/TR/NOTE-datetime
.. _AsciiDoc: https://www.methods.co.nz/asciidoc/
.. _pelican-plugins: https://github.com/getpelican/pelican-plugins
.. _Markdown Extensions: https://python-markdown.github.io/extensions/
.. _CodeHilite extension: https://python-markdown.github.io/extensions/code_hilite/#syntax
.. _i18n_subsites plugin: http://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
.. _i18n_subsites plugin: https://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
.. _the include directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#include
.. _mdx_include plugin: https://github.com/neurobin/mdx_include

189
docs/contribute.rst
View file

@ -7,72 +7,78 @@ can also help out by reviewing and commenting on
`existing issues <https://github.com/getpelican/pelican/issues>`_.
Don't hesitate to fork Pelican and submit an issue or pull request on GitHub.
When doing so, please adhere to the following guidelines.
When doing so, please consider the following guidelines.
.. include:: ../CONTRIBUTING.rst
Setting up the development environment
======================================
While there are many ways to set up one's development environment, we recommend
using `Virtualenv <https://virtualenv.pypa.io/en/stable/>`_. This tool allows
you to set up separate environments for separate Python projects that are
isolated from one another so you can use different packages (and package
versions) for each.
While there are many ways to set up one's development environment, the following
instructions will utilize Pip_ and Poetry_. 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.
If you don't have ``virtualenv`` installed, you can install it via::
Please note that Python 3.6+ is required for Pelican development.
$ pip install virtualenv
*(Optional)* If you prefer to install Poetry once for use with multiple projects,
you can install it via::
Use ``virtualenv`` to create and activate a virtual environment::
curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
$ virtualenv ~/virtualenvs/pelican
$ cd ~/virtualenvs/pelican
$ . bin/activate
Point your web browser to the `Pelican repository`_ and tap the **Fork** button
at top-right. Then clone the source for your fork and add the upstream project
as a Git remote::
Clone the Pelican source into a subfolder called ``src/pelican``::
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
$ git clone https://github.com/getpelican/pelican.git src/pelican
$ cd src/pelican
While Poetry can dynamically create and manage virtual environments, we're going
to manually create and activate a virtual environment::
Install the development dependencies::
mkdir ~/virtualenvs
python3 -m venv ~/virtualenvs/pelican
source ~/virtualenvs/pelican/bin/activate
$ pip install -r requirements/developer.pip
Install the needed dependencies and set up the project::
Install Pelican and its dependencies::
pip install -e ~/projects/pelican invoke
invoke setup
$ python setup.py develop
Your local environment should now be ready to go!
Or using ``pip``::
.. _Pip: https://pip.pypa.io/
.. _Poetry: https://poetry.eustace.io/docs/#installation
.. _Pelican repository: https://github.com/getpelican/pelican
$ pip install -e .
Development
===========
To conveniently test on multiple Python versions, we also provide a ``.tox``
file.
Once Pelican has been set up for local development, create a topic branch for
your bug fix or feature::
git checkout -b name-of-your-bugfix-or-feature
Building the docs
=================
If you make changes to the documentation, you should preview your changes
before committing them::
$ pip install -r requirements/docs.pip
$ cd docs
$ make html
Open ``_build/html/index.html`` in your browser to preview the documentation.
Now you can make changes to Pelican, its documentation, and/or other aspects of
the project.
Running the test suite
======================
----------------------
Each time you add a feature, there are two things to do regarding tests: check
that the existing tests pass, and add tests for the new feature or bugfix.
Each time you make changes to Pelican, there are two things to do regarding
tests: check that the existing tests pass, and add tests for any new features
or bug fixes. The tests are located in ``pelican/tests``, and you can run them
via::
The tests live in ``pelican/tests`` and you can run them using the
"discover" feature of ``unittest``::
invoke tests
$ python -Wd -m unittest discover
In addition to running the test suite, the above invocation will also check code
style and let you know whether non-conforming patterns were found. In some cases
these linters will make the needed changes directly, while in other cases you
may need to make additional changes until ``invoke tests`` no longer reports any
code style violations.
After making your changes and running the tests, you may see a test failure
mentioning that "some generated files differ from the expected functional tests
@ -80,14 +86,9 @@ output." If you have made changes that affect the HTML output generated by
Pelican, and the changes to that output are expected and deemed correct given
the nature of your changes, then you should update the output used by the
functional tests. To do so, **make sure you have both** ``en_EN.utf8`` **and**
``fr_FR.utf8`` **locales installed**, and then run the following two commands::
``fr_FR.utf8`` **locales installed**, and then run the following command::
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
-s samples/pelican.conf.py samples/content/
$ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
-s samples/pelican.conf_FR.py samples/content/
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
samples/content/
invoke update-functional-tests
You may also find that some tests are skipped because some dependency (e.g.,
Pandoc) is not installed. This does not automatically mean that these tests
@ -101,48 +102,74 @@ environments.
.. _Tox: https://tox.readthedocs.io/en/latest/
Python 2/3 compatibility development tips
=========================================
Building the docs
-----------------
Here are some tips that may be useful for writing code that is compatible with
both Python 2.7 and Python 3:
If you make changes to the documentation, you should build and inspect your
changes before committing them::
- Use new syntax. For example:
invoke docserve
- ``print .. -> print(..)``
- ``except .., e -> except .. as e``
Open http://localhost:8000 in your browser to review the documentation. While
the above task is running, any changes you make and save to the documentation
should automatically appear in the browser, as it live-reloads when it detects
changes to the documentation source files.
- Use new methods. For example:
Plugin development
------------------
- ``dict.iteritems() -> dict.items()``
- ``xrange(..) - > list(range(..))``
To create a *new* Pelican plugin, please refer to the `plugin template`_
repository for detailed instructions.
- Use ``six`` where necessary. For example:
If you want to contribute to an *existing* Pelican plugin, follow the steps
above to set up Pelican for local development, and then create a directory to
store cloned plugin repositories::
- ``isinstance(.., basestring) -> isinstance(.., six.string_types)``
- ``isinstance(.., unicode) -> isinstance(.., six.text_type)``
mkdir -p ~/projects/pelican-plugins
- Assume every string and literal is Unicode:
Assuming you wanted to contribute to the Simple Footnotes plugin, you would
first browse to the `Simple Footnotes`_ repository on GitHub and tap the **Fork**
button at top-right. Then clone the source for your fork and add the upstream
project as a Git remote::
- Use ``from __future__ import unicode_literals``
- Do not use the prefix ``u'`` before strings.
- Do not encode/decode strings in the middle of something. Follow the code to
the source/target of a string and encode/decode at the first/last possible
point.
- In particular, write your functions to expect and to return Unicode.
- Encode/decode strings if the string is the output of a Python function that
is known to handle this badly. For example, ``strftime()`` in Python 2.
- Do not use the magic method ``__unicode()__`` in new classes. Use only
``__str()__`` and decorate the class with ``@python_2_unicode_compatible``.
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
- ``setlocale()`` in Python 2 fails when we give the locale name as Unicode,
and since we are using ``from __future__ import unicode_literals``, we do
that everywhere! As a workaround, enclose the locale name with ``str()``;
in Python 2 this casts the name to a byte string, while in Python 3 this
should do nothing, because the locale name was already Unicode.
- Do not start integer literals with a zero. This is a syntax error in Python 3.
- Unfortunately there seems to be no octal notation that is valid in both
Python 2 and 3. Use decimal notation instead.
Install the needed dependencies and set up the project::
invoke setup
Create a topic branch for your plugin bug fix or feature::
git checkout -b name-of-your-bugfix-or-feature
After writing new tests for your plugin changes, run the plugin test suite::
invoke tests
.. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin
.. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes
Submitting your changes
-----------------------
Assuming linting validation and tests pass, add a ``RELEASE.md`` file in the root
of the project that contains the release type (major, minor, patch) and a
summary of the changes that will be used as the release changelog entry.
For example::
Release type: patch
Fix browser reloading upon changes to content, settings, or theme
Commit your changes and push your topic branch::
git add .
git commit -m "Your detailed description of your changes"
git push origin name-of-your-bugfix-or-feature
Finally, browse to your repository fork on GitHub and submit a pull request.
Logging tips
@ -160,8 +187,8 @@ For logging messages that are not repeated, use the usual Python way::
logger.warning("A warning with %s formatting", arg_to_be_formatted)
Do not format log messages yourself. Use ``%s`` formatting in messages and pass
arguments to logger. This is important, because Pelican logger will preprocess
some arguments (like Exceptions) for Py2/Py3 compatibility.
arguments to logger. This is important, because the Pelican logger will
preprocess some arguments, such as exceptions.
Limiting extraneous log messages
--------------------------------

4
docs/faq.rst
View file

@ -48,7 +48,7 @@ themes to style code syntax highlighting via CSS. Specifically, you can
customize the appearance of your syntax highlighting via the ``.highlight pre``
class in your theme's CSS file. To see how various styles can be used to render
Django code, for example, use the style selector drop-down at top-right on the
`Pygments project demo site <http://pygments.org/demo/>`_.
`Pygments project demo site <https://pygments.org/demo/>`_.
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
@ -167,7 +167,7 @@ I'm getting a warning about feeds generated without SITEURL being set properly
==============================================================================
`RSS and Atom feeds require all URL links to be absolute
<http://validator.w3.org/feed/docs/rss2.html#comments>`_. In order to properly
<https://validator.w3.org/feed/docs/rss2.html#comments>`_. In order to properly
generate links in Pelican you will need to set ``SITEURL`` to the full path of
your site.

14
docs/importer.rst
View file

@ -39,8 +39,8 @@ Dependencies
- *Pandoc*, see the `Pandoc site`_ for installation instructions on your
operating system.
.. _Pandoc: http://johnmacfarlane.net/pandoc/
.. _Pandoc site: http://johnmacfarlane.net/pandoc/installing.html
.. _Pandoc: https://pandoc.org/
.. _Pandoc site: https://pandoc.org/installing.html
Usage
@ -58,7 +58,7 @@ Positional arguments
============= ============================================================================
``input`` The input file to read
``api_token`` (Posterous only) api_token can be obtained from http://posterous.com/api/
``api_key`` (Tumblr only) api_key can be obtained from http://www.tumblr.com/oauth/apps
``api_key`` (Tumblr only) api_key can be obtained from https://www.tumblr.com/oauth/apps
============= ============================================================================
Optional arguments
@ -74,8 +74,8 @@ Optional arguments
-o OUTPUT, --output OUTPUT
Output path (default: content)
-m MARKUP, --markup MARKUP
Output markup format (supports rst & markdown)
(default: rst)
Output markup format: ``rst``, ``markdown``, or ``asciidoc``
(default: ``rst``)
--dir-cat Put files in directories with categories name
(default: False)
--dir-page Put files recognised as pages in "pages/" sub-
@ -137,7 +137,7 @@ Tests
To test the module, one can use sample files:
- for WordPress: http://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
- for WordPress: https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
- for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt
.. _more_categories: http://github.com/getpelican/pelican-plugins/tree/master/more_categories
.. _more_categories: https://github.com/getpelican/pelican-plugins/tree/master/more_categories

10
docs/index.rst
View file

@ -76,10 +76,10 @@ Documentation
.. Links
.. _Python: http://www.python.org/
.. _Python: https://www.python.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Markdown: http://daringfireball.net/projects/markdown/
.. _Jinja2: http://jinja.pocoo.org/
.. _`Pelican documentation`: http://docs.getpelican.com/latest/
.. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
.. _Markdown: https://daringfireball.net/projects/markdown/
.. _Jinja2: https://palletsprojects.com/p/jinja/
.. _`Pelican documentation`: https://docs.getpelican.com/latest/
.. _`Pelican's internals`: https://docs.getpelican.com/en/latest/internals.html
.. _`Pelican plugins`: https://github.com/getpelican/pelican-plugins

47
docs/install.rst
View file

@ -1,14 +1,18 @@
Installing Pelican
##################
Pelican currently runs best on Python 2.7.x and 3.4+; earlier versions of
Pelican currently runs best on Python 2.7.x and 3.5+; earlier versions of
Python are not supported.
You can install Pelican via several different methods. The simplest is via
`pip <http://www.pip-installer.org/>`_::
`pip <https://pip.pypa.io/en/stable/>`_::
pip install pelican
Or, if you plan on using Markdown::
pip install pelican[Markdown]
(Keep in mind that operating systems will often require you to prefix the above
command with ``sudo`` in order to install Pelican system-wide.)
@ -39,13 +43,17 @@ options. For more detail, refer to the :doc:`Publish<publish>` section.
Optional packages
-----------------
If you plan on using `Markdown <http://pypi.python.org/pypi/Markdown>`_ as a
markup format, you'll need to install the Markdown library::
If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as a
markup format, you can install Pelican with Markdown support::
pip install pelican[Markdown]
Or you might need to install it a posteriori::
pip install Markdown
Typographical enhancements can be enabled in your settings file, but first the
requisite `Typogrify <http://pypi.python.org/pypi/typogrify>`_ library must be
requisite `Typogrify <https://pypi.org/project/typogrify/>`_ library must be
installed::
pip install typogrify
@ -56,22 +64,22 @@ Dependencies
When Pelican is installed, the following dependent Python packages should be
automatically installed without any action on your part:
* `feedgenerator <http://pypi.python.org/pypi/feedgenerator>`_, to generate the
* `feedgenerator <https://pypi.org/project/feedgenerator/>`_, to generate the
Atom feeds
* `jinja2 <http://pypi.python.org/pypi/Jinja2>`_, for templating support
* `pygments <http://pypi.python.org/pypi/Pygments>`_, for syntax highlighting
* `docutils <http://pypi.python.org/pypi/docutils>`_, for supporting
* `jinja2 <https://pypi.org/project/Jinja2/>`_, for templating support
* `pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting
* `docutils <https://pypi.org/project/docutils/>`_, for supporting
reStructuredText as an input format
* `pytz <http://pypi.python.org/pypi/pytz>`_, for timezone definitions
* `blinker <http://pypi.python.org/pypi/blinker>`_, an object-to-object and
* `pytz <https://pypi.org/project/pytz/>`_, for timezone definitions
* `blinker <https://pypi.org/project/blinker/>`_, an object-to-object and
broadcast signaling system
* `unidecode <http://pypi.python.org/pypi/Unidecode>`_, for ASCII
* `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
transliterations of Unicode text
* `six <http://pypi.python.org/pypi/six>`_, for Python 2 and 3 compatibility
* `six <https://pypi.org/project/six/>`_, for Python 2 and 3 compatibility
utilities
* `MarkupSafe <http://pypi.python.org/pypi/MarkupSafe>`_, for a markup safe
* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup safe
string implementation
* `python-dateutil <https://pypi.python.org/pypi/python-dateutil>`_, to read
* `python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read
the date metadata
Upgrading
@ -94,6 +102,13 @@ your site::
pelican-quickstart
If run inside an activated virtual environment, ``pelican-quickstart`` will
look for an associated project path inside ``$VIRTUAL_ENV/.project``. If that
file exists and contains a valid directory path, the new Pelican project will
be saved at that location. Otherwise, the default is the current working
directory. To set the new project path on initial invocation, use:
``pelican-quickstart --path /your/desired/directory``
Once you finish answering all the questions, your project will consist of the
following hierarchy (except for *pages* — shown in parentheses below — which
you can optionally add yourself if you plan to create non-chronological
@ -111,4 +126,4 @@ content)::
The next step is to begin to adding content to the *content* folder that has
been created for you.
.. _virtualenv: http://www.virtualenv.org/
.. _virtualenv: https://virtualenv.pypa.io/en/latest/

2
docs/internals.rst
View file

@ -32,7 +32,7 @@ The logic is separated into different classes and concepts:
inputs.
* Pelican also uses templates, so it's easy to write your own theme. The
syntax is `Jinja2 <http://jinja.pocoo.org/>`_ and is very easy to learn, so
syntax is `Jinja2 <https://palletsprojects.com/p/jinja/>`_ and is very easy to learn, so
don't hesitate to jump in and build your own theme.
How to implement a new reader?

3
docs/pelican-themes.rst
View file

@ -6,7 +6,8 @@ pelican-themes
Description
===========
``pelican-themes`` is a command line tool for managing themes for Pelican.
``pelican-themes`` is a command line tool for managing themes for Pelican. See
:ref:`settings/themes` for settings related to themes.
Usage

64
docs/plugins.rst
View file

@ -9,16 +9,31 @@ features to Pelican without having to directly modify the Pelican core.
How to use plugins
==================
To load plugins, you have to specify them in your settings file. There are two
ways to do so. The first method is to specify strings with the path to the
callables::
Starting with version 5.0, Pelican moved to a new plugin structure utilizing
namespace packages. Plugins supporting this structure will install under the
namespace package ``pelican.plugins`` and can be automatically discovered
by Pelican.
PLUGINS = ['package.myplugin',]
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will then
collect the namespace plugins and register them. If on the other hand you
specify a ``PLUGINS`` settings as a list of plugins, this autodiscovery will
be disabled and only listed plugins will be registered and you will have to
explicitly list the namespace plugins as well.
Alternatively, another method is to import them and add them to the list::
If you are using ``PLUGINS`` setting, you can specify plugins in two ways.
The first method specifies plugins as a list of strings. Namespace plugins can
be specified either by their full names (``pelican.plugins.myplugin``) or by
their short names (``myplugin``)::
PLUGINS = ['package.myplugin',
'namespace_plugin1',
'pelican.plugins.namespace_plugin2']
Alternatively, you can import them in your settings file and pass the modules::
from package import myplugin
PLUGINS = [myplugin,]
from pelican.plugins import namespace_plugin1, namespace_plugin2
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]
.. note::
@ -36,11 +51,13 @@ the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::
Where to find plugins
=====================
Namespace plugins can be found in the `pelican-plugins organization`_ as
individual repositories. Legacy plugins are collected in the `pelican-plugins
repository`_ and they will be slowly phased out in favor of the namespace
versions.
We maintain a separate repository of plugins for people to share and use.
Please visit the `pelican-plugins`_ repository for a list of available plugins.
.. _pelican-plugins: https://github.com/getpelican/pelican-plugins
.. _pelican-plugins organization: https://github.com/pelican-plugins
.. _pelican-plugins repository: https://github.com/getpelican/pelican-plugins
Please note that while we do our best to review and maintain these plugins,
they are submitted by the Pelican community and thus may have varying levels of
@ -70,6 +87,33 @@ which you map the signals to your plugin logic. Let's take a simple example::
your ``register`` callable or they will be garbage-collected before the
signal is emitted.
Namespace plugin structure
--------------------------
Namespace plugins must adhere to a certain structure in order to function
properly. They need to be installable (i.e. contain ``setup.py`` or equivalent)
and have a folder structure as follows::
myplugin
├── pelican
│   └── plugins
│   └── myplugin
│   ├── __init__.py
│   └── ...
├── ...
└── setup.py
It is crucial that ``pelican`` or ``pelican/plugins`` folder **not**
contain an ``__init__.py`` file. In fact, it is best to have those folders
empty besides the listed folders in the above structure and keep your
plugin related files contained solely in the ``pelican/plugins/myplugin``
folder to avoid any issues.
For easily setting up the proper structure, a `cookiecutter template for
plugins`_ is provided. Refer to the README in the link for how to use it.
.. _cookiecutter template for plugins: https://github.com/getpelican/cookiecutter-pelican-plugin
List of signals
===============

31
docs/publish.rst
View file

@ -32,7 +32,12 @@ list of paths or can be configured as a setting. (See:
You can also tell Pelican to watch for your modifications, instead of manually
re-running it every time you want to see your changes. To enable this, run the
``pelican`` command with the ``-r`` or ``--autoreload`` option.
``pelican`` command with the ``-r`` or ``--autoreload`` option. On non-Windows
environments, this option can also be combined with the ``-l`` or ``--listen``
option to simultaneously both auto-regenerate *and* serve the output at
http://localhost:8000::
pelican --autoreload --listen
Pelican has other command-line switches available. Have a look at the help to
see all the options you can use::
@ -49,20 +54,12 @@ HTML files directly::
firefox output/index.html
Because the above method may have trouble locating your CSS and other linked
assets, running a simple web server using Python will often provide a more
reliable previewing experience.
assets, running Pelican's simple built-in web server will often provide a more
reliable previewing experience::
For Python 2, run::
pelican --listen
cd output
python -m SimpleHTTPServer
For Python 3, run::
cd output
python -m http.server
Once the basic server has been started, you can preview your site at
Once the web server has been started, you can preview your site at:
http://localhost:8000/
Deployment
@ -141,6 +138,12 @@ http://localhost:8000/::
invoke serve
To serve the generated site with automatic browser reloading every time a
change is detected, first ``pip install livereload``, then use the
following command::
invoke livereload
If during the ``pelican-quickstart`` process you answered "yes" when asked
whether you want to upload your site via SSH, you can use the following command
to publish your site via rsync over SSH::
@ -204,4 +207,4 @@ That's it! Your site should now be live.
executables, such as ``python3``, you can set the ``PY`` and ``PELICAN``
environment variables, respectively, to override the default executable names.)
.. _Invoke: http://www.pyinvoke.org
.. _Invoke: https://www.pyinvoke.org/

16
docs/quickstart.rst
View file

@ -8,10 +8,10 @@ Installation
------------
Install Pelican (and optionally Markdown if you intend to use it) on Python
2.7.x or Python 3.3+ by running the following command in your preferred
2.7.x or Python 3.5+ by running the following command in your preferred
terminal, prefixing with ``sudo`` if permissions warrant::
pip install pelican markdown
pip install pelican[Markdown]
Create a project
----------------
@ -30,7 +30,7 @@ by asking some questions about your site::
For questions that have default values denoted in brackets, feel free to use
the Return key to accept those default values [#tzlocal_fn]_. When asked for
your URL prefix, enter your domain name as indicated (e.g.,
``http://example.com``).
``https://example.com``).
Create an article
-----------------
@ -50,19 +50,19 @@ Given that this example article is in Markdown format, save it as
Generate your site
------------------
From your site directory, run the ``pelican`` command to generate your site::
From your project root directory, run the ``pelican`` command to generate your site::
pelican content
Your site has now been generated inside the ``output`` directory. (You may see
Your site has now been generated inside the ``output/`` directory. (You may see
a warning related to feeds, but that is normal when developing locally and can
be ignored for now.)
Preview your site
-----------------
Open a new terminal session, navigate to your site directory and run the
following command to launch Pelican's web server::
Open a new terminal session, navigate to your project root directory, and
run the following command to launch Pelican's web server::
pelican --listen
@ -78,5 +78,5 @@ Footnotes
---------
.. [#tzlocal_fn] You can help localize default fields by installing the
optional `tzlocal <https://pypi.python.org/pypi/tzlocal>`_
optional `tzlocal <https://pypi.org/project/tzlocal/>`_
module.

219
docs/settings.rst
View file

@ -98,10 +98,24 @@ Basic settings
should map the filtername to the filter function.
Example::
import sys
sys.path.append('to/your/path')
from custom_filter import urlencode_filter
JINJA_FILTERS = {'urlencode': urlencode_filter}
See `Jinja custom filters documentation`_.
See: `Jinja custom filters documentation`_.
.. data:: JINJA_GLOBALS = {}
A dictionary of custom objects to map into the Jinja2 global environment
namespace. The dictionary should map the global name to the global
variable/function. See: `Jinja global namespace documentation`_.
.. data:: JINJA_TESTS = {}
A dictionary of custom Jinja2 tests you want to use. The dictionary should
map test names to test functions. See: `Jinja custom tests documentation`_.
.. data:: LOG_FILTER = []
@ -152,12 +166,13 @@ Basic settings
}
.. Note::
The dictionary defined in your settings file will update this default
The dictionary defined in your settings file will replace this default
one.
.. data:: OUTPUT_PATH = 'output/'
Where to output the generated files.
Where to output the generated files. This should correspond to your web
server's virtual host root directory.
.. data:: PATH
@ -194,7 +209,7 @@ Basic settings
Controls the extension that will be used by the SourcesGenerator. Defaults
to ``.text``. If not a valid string the default value will be used.
.. data:: PLUGINS = []
.. data:: PLUGINS = None
The list of plugins to load. See :ref:`plugins`.
@ -281,6 +296,11 @@ Basic settings
does not otherwise specify a summary. Setting to ``None`` will cause the
summary to be a copy of the original content.
.. data:: SUMMARY_END_MARKER = '…'
When creating a short summary of an article and the result was truncated to
match the required word length, this will be used as the truncation marker.
.. data:: WITH_FUTURE_DATES = True
If disabled, content with dates in the future will get a default status of
@ -352,6 +372,7 @@ Basic settings
The IP to which to bind the HTTP server.
.. _url-settings:
URL settings
============
@ -373,15 +394,20 @@ example below). These settings give you the flexibility to place your articles
and pages anywhere you want.
.. note::
If you specify a ``datetime`` directive, it will be substituted using the
input files' date metadata attribute. If the date is not specified for a
particular file, Pelican will rely on the file's ``mtime`` timestamp. Check
the `Python datetime documentation`_ for more information.
If a ``*_SAVE_AS`` setting contains a parent directory that doesn't match
the parent directory inside the corresponding ``*_URL`` setting, this may
cause Pelican to generate unexpected URLs in a few cases, such as when
using the ``{attach}`` syntax.
.. _Python datetime documentation:
http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior
If you don't want that flexibility and instead prefer that your generated
output paths mirror your source content's filesystem path hierarchy, try the
following settings::
Also, you can use other file metadata attributes as well:
PATH_METADATA = '(?P<path_no_ext>.*)\..*'
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = '{path_no_ext}.html'
Otherwise, you can use a variety of file metadata attributes within URL-related
settings:
* slug
* date
@ -401,6 +427,15 @@ This would save your articles into something like
``/pages/about/index.html``, and render them available at URLs of
``/posts/2011/Aug/07/sample-post/`` and ``/pages/about/``, respectively.
.. note::
If you specify a ``datetime`` directive, it will be substituted using the
input files' date metadata attribute. If the date is not specified for a
particular file, Pelican will rely on the file's ``mtime`` timestamp. Check
the `Python datetime documentation`_ for more information.
.. _Python datetime documentation:
https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior
.. data:: RELATIVE_URLS = False
Defines whether Pelican should use document-relative URLs or not. Only set
@ -477,6 +512,14 @@ This would save your articles into something like
The actual location a page draft which doesn't use the default language is
saved at.
.. data:: AUTHOR_URL = 'author/{slug}.html'
The URL to use for an author.
.. data:: AUTHOR_SAVE_AS = 'author/{slug}.html'
The location to save an author.
.. data:: CATEGORY_URL = 'category/{slug}.html'
The URL to use for a category.
@ -493,41 +536,6 @@ This would save your articles into something like
The location to save the tag page.
.. data:: AUTHOR_URL = 'author/{slug}.html'
The URL to use for an author.
.. data:: AUTHOR_SAVE_AS = 'author/{slug}.html'
The location to save an author.
.. data:: YEAR_ARCHIVE_SAVE_AS = ''
The location to save per-year archives of your posts.
.. data:: YEAR_ARCHIVE_URL = ''
The URL to use for per-year archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: MONTH_ARCHIVE_SAVE_AS = ''
The location to save per-month archives of your posts.
.. data:: MONTH_ARCHIVE_URL = ''
The URL to use for per-month archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: DAY_ARCHIVE_SAVE_AS = ''
The location to save per-day archives of your posts.
.. data:: DAY_ARCHIVE_URL = ''
The URL to use for per-day archives of your posts. Used only if you have the
``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. note::
If you do not want one or more of the default pages to be created (e.g.,
@ -556,6 +564,33 @@ posts for the month at ``posts/2011/Aug/index.html``.
This way a reader can remove a portion of your URL and automatically arrive
at an appropriate archive of posts, without having to specify a page name.
.. data:: YEAR_ARCHIVE_URL = ''
The URL to use for per-year archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: YEAR_ARCHIVE_SAVE_AS = ''
The location to save per-year archives of your posts.
.. data:: MONTH_ARCHIVE_URL = ''
The URL to use for per-month archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: MONTH_ARCHIVE_SAVE_AS = ''
The location to save per-month archives of your posts.
.. data:: DAY_ARCHIVE_URL = ''
The URL to use for per-day archives of your posts. Used only if you have the
``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: DAY_ARCHIVE_SAVE_AS = ''
The location to save per-day archives of your posts.
``DIRECT_TEMPLATES`` work a bit differently than noted above. Only the
``_SAVE_AS`` settings are available, but it is available for any direct
template.
@ -564,18 +599,6 @@ template.
The location to save the article archives page.
.. data:: YEAR_ARCHIVE_SAVE_AS = ''
The location to save per-year archives of your posts.
.. data:: MONTH_ARCHIVE_SAVE_AS = ''
The location to save per-month archives of your posts.
.. data:: DAY_ARCHIVE_SAVE_AS = ''
The location to save per-day archives of your posts.
.. data:: AUTHORS_SAVE_AS = 'authors.html'
The location to save the author list.
@ -598,10 +621,10 @@ corresponding ``*_URL`` setting as string, while others hard-code them:
``'tags.html'``.
.. data:: SLUG_REGEX_SUBSTITUTIONS = [
(r'[^\w\s-]', ''), # remove non-alphabetical/whitespace/'-' chars
(r'(?u)\A\s*', ''), # strip leading whitespace
(r'(?u)\s*\Z', ''), # strip trailing whitespace
(r'[-\s]+', '-'), # reduce multiple whitespace or '-' to single '-'
(r'[^\\w\\s-]', ''), # remove non-alphabetical/whitespace/'-' chars
(r'(?u)\\A\\s*', ''), # strip leading whitespace
(r'(?u)\\s*\\Z', ''), # strip trailing whitespace
(r'[-\\s]+', '-'), # reduce multiple whitespace or '-' to single '-'
]
Regex substitutions to make when generating slugs of articles and pages.
@ -642,7 +665,7 @@ Time and Date
Have a look at `the wikipedia page`_ to get a list of valid timezone values.
.. _the wikipedia page: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
.. _the wikipedia page: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
.. data:: DEFAULT_DATE = None
@ -667,7 +690,7 @@ Time and Date
the language name (``lang`` metadata in your post content) as the key.
In addition to the standard C89 strftime format codes that are listed in
`Python strftime documentation`_, you can use the ``-`` character between
`Python datetime documentation`_, you can use the ``-`` character between
``%`` and the format character to remove any leading zeros. For example,
``%d/%m/%Y`` will output ``01/01/2014`` whereas ``%-d/%-m/%Y`` will result
in ``1/1/2014``.
@ -718,11 +741,13 @@ Time and Date
.. [#] Default is the system locale.
.. _Python strftime documentation: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
.. _Jinja custom filters documentation: https://jinja.palletsprojects.com/en/master/api/#custom-filters
.. _Jinja global namespace documentation: https://jinja.palletsprojects.com/en/master/api/#the-global-namespace
.. _Jinja custom tests documentation: https://jinja.palletsprojects.com/en/master/api/#custom-tests
.. _locales on Windows: http://msdn.microsoft.com/en-us/library/cdax410z%28VS.71%29.aspx
.. _locales on Windows: https://www.microsoft.com/en-us/download/details.aspx?id=55979
.. _locale(1): http://linux.die.net/man/1/locale
.. _locale(1): https://linux.die.net/man/1/locale
.. _template_pages:
@ -746,15 +771,15 @@ Template pages
'src/resume.html': 'dest/resume.html',
'src/contact.html': 'dest/contact.html'}
.. data:: TEMPLATE_EXTENSION = ['.html']
.. data:: TEMPLATE_EXTENSIONS = ['.html']
The extensions to use when looking up template files from template names.
.. data:: DIRECT_TEMPLATES = ['index', 'categories', 'authors', 'archives']
.. data:: DIRECT_TEMPLATES = ['index', 'authors', 'categories', 'tags', 'archives']
List of templates that are used directly to render content. Typically direct
templates are used to generate index pages for collections of content (e.g.,
tags and category index pages). If the tag and category collections are not
category and tag index pages). If the author, category and tag collections are not
needed, set ``DIRECT_TEMPLATES = ['index', 'archives']``
``DIRECT_TEMPLATES`` are searched for over paths maintained in
@ -793,7 +818,8 @@ Metadata
Extra metadata dictionaries keyed by relative path. Relative paths require
correct OS-specific directory separators (i.e. / in UNIX and \\ in Windows)
unlike some other Pelican file settings.
unlike some other Pelican file settings. Paths to a directory apply to all
files under it. The most-specific path wins conflicts.
Not all metadata needs to be :ref:`embedded in source file itself
<internal_metadata>`. For example, blog posts are often named following a
@ -832,7 +858,7 @@ file:
}
.. _group name notation:
http://docs.python.org/3/library/re.html#regular-expression-syntax
https://docs.python.org/3/library/re.html#regular-expression-syntax
Feed settings
@ -849,7 +875,7 @@ the ``TAG_FEED_ATOM`` and ``TAG_FEED_RSS`` settings:
The domain prepended to feed URLs. Since feed URLs should always be
absolute, it is highly recommended to define this (e.g.,
"http://feeds.example.com"). If you have already explicitly defined SITEURL
"https://feeds.example.com"). If you have already explicitly defined SITEURL
(see above) and want to use the same domain for your feeds, you can just
set: ``FEED_DOMAIN = SITEURL``.
@ -964,27 +990,6 @@ variables to ``None``.
.. [2] ``{slug}`` is replaced by name of the category / author / tag.
FeedBurner
----------
If you want to use FeedBurner for your feed, you will likely need to decide
upon a unique identifier. For example, if your site were called "Thyme" and
hosted on the www.example.com domain, you might use "thymefeeds" as your unique
identifier, which we'll use throughout this section for illustrative purposes.
In your Pelican settings, set the ``FEED_ATOM`` attribute to
``thymefeeds/main.xml`` to create an Atom feed with an original address of
``http://www.example.com/thymefeeds/main.xml``. Set the ``FEED_DOMAIN``
attribute to ``http://feeds.feedburner.com``, or ``http://feeds.example.com``
if you are using a CNAME on your own domain (i.e., FeedBurner's "MyBrand"
feature).
There are two fields to configure in the `FeedBurner
<http://feedburner.google.com>`_ interface: "Original Feed" and "Feed Address".
In this example, the "Original Feed" would be
``http://www.example.com/thymefeeds/main.xml`` and the "Feed Address" suffix
would be ``thymefeeds/main.xml``.
Pagination
==========
@ -1025,7 +1030,7 @@ By default, pages subsequent to ``.../foo.html`` are created as
``.../foo2.html``, etc. The ``PAGINATION_PATTERNS`` setting can be used to
change this. It takes a sequence of triples, where each triple consists of::
(minimum_page, page_url, page_save_as,)
(minimum_page, page_url, page_save_as,)
For ``page_url`` and ``page_save_as``, you may use a number of variables.
``{url}`` and ``{save_as}`` correspond respectively to the ``*_URL`` and
@ -1039,7 +1044,7 @@ subsequent pages at ``.../page/2/`` etc, you could set ``PAGINATION_PATTERNS``
as follows::
PAGINATION_PATTERNS = (
(1, '{url}', '{save_as}`,
(1, '{url}', '{save_as}'),
(2, '{base_name}/page/{number}/', '{base_name}/page/{number}/index.html'),
)
@ -1118,6 +1123,7 @@ Ordering content
will sort pages by their basename.
.. _settings/themes:
Themes
======
@ -1130,7 +1136,7 @@ themes.
Theme to use to produce the output. Can be a relative or absolute path to a
theme folder, or the name of a default theme or a theme installed via
``pelican-themes`` (see below).
:doc:`pelican-themes` (see below).
.. data:: THEME_STATIC_DIR = 'theme'
@ -1223,20 +1229,6 @@ Feel free to use them in your themes as well.
A list of tuples (Title, URL) for additional menu items to appear at the
beginning of the main menu.
.. data:: PIWIK_URL
URL to your Piwik server - without 'http://' at the beginning.
.. data:: PIWIK_SSL_URL
If the SSL-URL differs from the normal Piwik-URL you have to include this
setting too. (optional)
.. data:: PIWIK_SITE_ID
ID for the monitored website. You can find the ID in the Piwik admin
interface > Settings > Websites.
.. data:: LINKS
A list of tuples (Title, URL) for links to appear on the header.
@ -1280,7 +1272,7 @@ ignored. Simply populate the list with the log messages you want to hide, and
they will be filtered out.
For example::
import logging
LOG_FILTER = [(logging.WARN, 'TAG_SAVE_AS is set to False')]
@ -1387,6 +1379,5 @@ Example settings
:language: python
.. _Jinja custom filters documentation: http://jinja.pocoo.org/docs/api/#custom-filters
.. _Jinja Environment documentation: http://jinja.pocoo.org/docs/dev/api/#jinja2.Environment
.. _Jinja Environment documentation: https://jinja.palletsprojects.com/en/master/api/#jinja2.Environment
.. _Docutils Configuration: http://docutils.sourceforge.net/docs/user/config.html

86
docs/themes.rst
View file

@ -4,7 +4,7 @@ Creating themes
###############
To generate its HTML output, Pelican uses the `Jinja
<http://jinja.pocoo.org/>`_ templating engine due to its flexibility and
<https://palletsprojects.com/p/jinja/>`_ templating engine due to its flexibility and
straightforward syntax. If you want to create your own theme, feel free to take
inspiration from the `"simple" theme
<https://github.com/getpelican/pelican/tree/master/pelican/themes/simple/templates>`_.
@ -75,16 +75,18 @@ output_file The name of the file currently being generated. For
articles The list of articles, ordered descending by date.
All the elements are `Article` objects, so you can
access their attributes (e.g. title, summary, author
etc.). Sometimes this is shadowed (for instance in
etc.). Sometimes this is shadowed (for instance, in
the tags page). You will then find info about it
in the `all_articles` variable.
dates The same list of articles, but ordered by date,
ascending.
drafts The list of draft articles
tags A list of (tag, articles) tuples, containing all
the tags.
authors A list of (author, articles) tuples, containing all
the authors and corresponding articles (values)
categories A list of (category, articles) tuples, containing
all the categories and corresponding articles (values)
tags A list of (tag, articles) tuples, containing all
the tags and corresponding articles (values)
pages The list of pages
hidden_pages The list of hidden pages
draft_pages The list of draft pages
@ -102,7 +104,7 @@ that allow them to be easily sorted by name::
If you want to sort based on different criteria, `Jinja's sort command`__ has a
number of options.
__ http://jinja.pocoo.org/docs/templates/#sort
__ https://jinja.palletsprojects.com/en/master/templates/#sort
Date Formatting
@ -118,8 +120,8 @@ your date according to the locale given in your settings::
{{ article.date|strftime('%d %B %Y') }}
.. _datetime: http://docs.python.org/2/library/datetime.html#datetime-objects
.. _strftime: http://docs.python.org/2/library/datetime.html#strftime-strptime-behavior
.. _datetime: https://docs.python.org/3/library/datetime.html#datetime-objects
.. _strftime: https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior
index.html
@ -347,9 +349,9 @@ Article
The string representation of an Article is the `source_path` attribute.
=================== ===================================================
====================== ===================================================
Attribute Description
=================== ===================================================
====================== ===================================================
author The :ref:`Author <object-author_cat_tag>` of
this article.
authors A list of :ref:`Authors <object-author_cat_tag>`
@ -368,6 +370,7 @@ metadata Article header metadata `dict`.
save_as Location to save the article page.
slug Page slug.
source_path Full system path of the article source file.
relative_source_path Relative path from PATH_ to the article source file.
status The article status, can be any of 'published' or
'draft'.
summary Rendered summary content.
@ -378,7 +381,10 @@ title Title of the article.
translations List of translations
:ref:`Article <object-article>` objects.
url URL to the article page.
=================== ===================================================
====================== ===================================================
.. _PATH: settings.html#PATH
.. _object-author_cat_tag:
@ -406,34 +412,38 @@ Page
The string representation of a Page is the `source_path` attribute.
=================== ===================================================
Attribute Description
=================== ===================================================
author The :ref:`Author <object-author_cat_tag>` of
this page.
content The rendered content of the page.
date Datetime object representing the page date.
date_format Either default date format or locale date format.
default_template Default template name.
in_default_lang Boolean representing if the article is written
in the default language.
lang Language of the article.
locale_date Date formatted by the `date_format`.
metadata Page header metadata `dict`.
save_as Location to save the page.
slug Page slug.
source_path Full system path of the page source file.
status The page status, can be any of 'published', 'hidden' or
'draft'.
summary Rendered summary content.
tags List of :ref:`Tag <object-author_cat_tag>`
objects.
template Template name to use for rendering.
title Title of the page.
translations List of translations
:ref:`Article <object-article>` objects.
url URL to the page.
=================== ===================================================
===================== ===================================================
Attribute Description
===================== ===================================================
author The :ref:`Author <object-author_cat_tag>` of
this page.
content The rendered content of the page.
date Datetime object representing the page date.
date_format Either default date format or locale date format.
default_template Default template name.
in_default_lang Boolean representing if the article is written
in the default language.
lang Language of the article.
locale_date Date formatted by the `date_format`.
metadata Page header metadata `dict`.
save_as Location to save the page.
slug Page slug.
source_path Full system path of the page source file.
relative_source_path Relative path from PATH_ to the page source file.
status The page status, can be any of 'published', 'hidden' or
'draft'.
summary Rendered summary content.
tags List of :ref:`Tag <object-author_cat_tag>`
objects.
template Template name to use for rendering.
title Title of the page.
translations List of translations
:ref:`Article <object-article>` objects.
url URL to the page.
===================== ===================================================
.. _PATH: settings.html#PATH
Feeds
=====