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