diff --git a/docs/plugins.rst b/docs/plugins.rst index dfc66dbd..654b18f7 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -76,14 +76,22 @@ request if you need them! List of plugins =============== -Not all the list are described here, but a few of them have been extracted from -the Pelican core and provided in ``pelican.plugins``. They are described here: +The following plugins are currently included with Pelican under ``pelican.plugins``: -Tag cloud ---------- +* `GitHub activity`_ +* `Global license`_ +* `Gravatar`_ +* `HTML tags for reStructuredText`_ +* `Related posts`_ +* `Sitemap`_ -Translation ------------ +Ideas for plugins that haven't been written yet: + +* Tag cloud +* Translation + +Plugin descriptions +=================== GitHub activity --------------- @@ -116,23 +124,78 @@ variable, as in the example:: ``github_activity`` is a list of lists. The first element is the title and the second element is the raw HTML from GitHub. +Global license +-------------- + +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. + +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 +address. Obviously, that email address must be associated with a Gravatar +account. + +Alternatively, you can provide an email address from within article metadata:: + + :email: john.doe@example.com + +If the email address is defined via at least one of the two methods above, +the ``author_gravatar`` variable is added to the article's context. + +HTML tags for reStructuredText +------------------------------ + +This plugin allows you to use HTML tags from within reST documents. Following +is a usage example, which is in this case a contact form:: + + .. html:: + +
+

+ +
+ +
+ +

+
+ +Related posts +------------- + +This plugin adds the ``related_posts`` variable to the article's context. +To enable, add the following to your settings file:: + + from pelican.plugins import related_posts + PLUGINS = [related_posts] + +You can then use the ``article.related_posts`` variable in your templates. +For example:: + + {% if article.related_posts %} + + {% endif %} Sitemap ------- -The plugin generates a sitemap of the blog. -It can generates plain text sitemaps or XML sitemaps. - -Configuration -""""""""""""" - -You can use the setting ``SITEMAP`` variable to configure the behavior of the +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 tree keys: +The ``SITEMAP`` variable must be a Python dictionary, it can contain three keys: - -- ``format``, which set the output format of the plugin (``xml`` or ``txt``) +- ``format``, which sets the output format of the plugin (``xml`` or ``txt``) - ``priorities``, which is a dictionary with three keys: @@ -154,9 +217,8 @@ The ``SITEMAP`` variable must be a Python dictionary, it can contain tree keys: - ``indexes``, the update frequency of the index pages - An valid value is ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``, - ``yearly`` or ``never``. - + Valid frequency values are ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``, + ``yearly`` and ``never``. If a key is missing or a value is incorrect, it will be replaced with the default value. @@ -168,11 +230,9 @@ The sitemap is saved in ``/sitemap.``. They are only used in the XML sitemaps. For more information: +**Example** -Example -""""""" - -Here is an example of configuration (it's also the default settings): +Here is an example configuration (it's also the default settings): .. code-block:: python diff --git a/pelican/plugins/global_license.py b/pelican/plugins/global_license.py index 463a93b3..9a0f5206 100644 --- a/pelican/plugins/global_license.py +++ b/pelican/plugins/global_license.py @@ -4,13 +4,14 @@ from pelican import signals License plugin for Pelican ========================== -Simply add license variable in article's context, which contain -the license text. +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. Settings: --------- -Add LICENSE to your settings file to define default license. +Define LICENSE in your settings file with the contents of your default license. """ diff --git a/pelican/plugins/gravatar.py b/pelican/plugins/gravatar.py index 4ab8ea9c..a4d11456 100644 --- a/pelican/plugins/gravatar.py +++ b/pelican/plugins/gravatar.py @@ -5,20 +5,22 @@ from pelican import signals Gravatar plugin for Pelican =========================== -Simply add author_gravatar variable in article's context, which contains -the gravatar url. +This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and +makes the variable available within the article's context. Settings: --------- -Add AUTHOR_EMAIL to your settings file to define default author email. +Add 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. Article metadata: ------------------ :email: article's author email -If one of them are defined, the author_gravatar variable is added to +If one of them are defined, the author_gravatar variable is added to the article's context. """