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 implement_first_and_last_page_paginator

Browse source
This commit is contained in:
Joachim Lusiardi 2020-04-19 09:56:50 +02:00
commit 3e26c76e8a
246 changed files with 2645 additions and 2006 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/changelog.rst
View file

@ -1,6 +1,30 @@
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
==================

7
docs/conf.py
View file

@ -1,5 +1,4 @@
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
import os
import sys
@ -18,7 +17,7 @@ extensions = ['sphinx.ext.autodoc',
source_suffix = '.rst'
master_doc = 'index'
project = 'Pelican'
copyright = '2010 – present, Alexis Metaireau and contributors'
copyright = '2010 – present, Justin Mayer, Alexis Metaireau, and contributors'
exclude_patterns = ['_build']
release = __version__
version = '.'.join(release.split('.')[:1])
@ -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',

83
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.
@ -363,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
----------------------------------------------
@ -382,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
==========================
@ -483,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:
@ -524,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,
@ -570,8 +615,10 @@ To publish a post when the default status is ``draft``, update the post's
metadata to include ``Status: published``.
.. _W3C ISO 8601: https://www.w3.org/TR/NOTE-datetime
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
.. _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: 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

2
docs/index.rst
View file

@ -79,7 +79,7 @@ Documentation
.. _Python: https://www.python.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Markdown: https://daringfireball.net/projects/markdown/
.. _Jinja2: http://jinja.pocoo.org/
.. _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

45
docs/install.rst
View file

@ -5,10 +5,14 @@ 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
===============

18
docs/publish.rst
View file

@ -54,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
@ -215,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/

14
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,18 +50,18 @@ 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 generated output directory and
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.

100
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 = []
@ -157,7 +171,8 @@ Basic settings
.. 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`.
@ -264,6 +279,17 @@ Basic settings
``pre`` and ``code`` tags. This requires that Typogrify version 2.0.4 or
later is installed
.. data:: TYPOGRIFY_DASHES = 'default'
This setting controls how Typogrify sets up the Smartypants filter to
interpret multiple dash/hyphen/minus characters. A single ASCII dash
character (``-``) is always rendered as a hyphen. The ``default`` setting
does not handle en-dashes and converts double-hyphens into em-dashes. The
``oldschool`` setting renders both en-dashes and em-dashes when it sees two
(``--``) and three (``---``) hyphen characters, respectively. The
``oldschool_inverted`` setting turns two hyphens into an em-dash and three
hyphens into an en-dash.
.. data:: SUMMARY_MAX_LENGTH = 50
When creating a short summary of an article, this will be the default length
@ -271,6 +297,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
@ -342,6 +373,7 @@ Basic settings
The IP to which to bind the HTTP server.
.. _url-settings:
URL settings
============
@ -363,15 +395,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:
https://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
@ -391,6 +428,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
@ -645,7 +691,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``.
@ -696,9 +742,11 @@ Time and Date
.. [#] Default is the system locale.
.. _Python strftime documentation: https://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): https://linux.die.net/man/1/locale
@ -983,7 +1031,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
@ -997,7 +1045,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'),
)
@ -1076,6 +1124,7 @@ Ordering content
will sort pages by their basename.
.. _settings/themes:
Themes
======
@ -1088,7 +1137,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'
@ -1181,20 +1230,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.
@ -1238,7 +1273,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')]
@ -1345,6 +1380,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

8
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>`_.
@ -104,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
@ -120,8 +120,8 @@ your date according to the locale given in your settings::
{{ article.date|strftime('%d %B %Y') }}
.. _datetime: https://docs.python.org/2/library/datetime.html#datetime-objects
.. _strftime: https://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