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

support both implicit and explicit inheritance with THEMES

Browse source
This commit is contained in:
Ondrej Grover 2014-11-05 09:53:20 +01:00
commit b22f760042
4 changed files with 51 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/settings.rst
View file

@ -720,12 +720,12 @@ Setting name (followed by default value, if any) What does it do?
the paths defined in this settings, they will be
progressively overwritten.
``CSS_FILE = 'main.css'`` Specify the CSS file you want to load.
``THEMES = {}`` Extra themes that can be inherited from. They can also
inherit from each other. Use a dictionary to make a list
of all the available list. The key in the dictionary will
also be the prefix you use to inherit from the theme.
Example: ``THEMES = {'!foo': foo, '!foobar':foobar}``
``THEMES = ('simple', ('!simple', 'simple'))`` Extra themes that can be inherited from, either
implicitly (just a path to the theme) or explicitly
using a prefix marker (tuple of prefix and path to
theme). They can also inherit from each other,
but only in the specified order.
See :ref:`theme_inheritance` for details.
================================================ =====================================================

47
docs/themes.rst
View file

@ -346,45 +346,50 @@ Here is a complete list of the feed variables::
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS
.. _theme_inheritance:
Inheritance
===========
Theme inheritance
=================
Since version 3.4, Pelican supports inheritance from the ``simple`` theme, as well
as any themes specified in the ``THEMES`` setting. You can re-use
their theme templates in your own themes.
Since version 3.6, Pelican supports both implicit and explicit
inheritance from any theme specified in the ``THEMES`` setting. By
default the special ``simple`` theme is inherited both implicitly and
explicitly, so you can re-use its theme templates in your own themes.
Implicit Inheritance
--------------------
If one of the mandatory files in the ``templates/`` directory of your theme is
missing, it will be replaced by the matching template from the ``simple`` theme.
So if the HTML structure of a template in the ``simple`` theme is right for you,
If one of the mandatory files in the ``templates/`` directory of your
theme is missing, it will be replaced by a matching template from any
of the implicitly inherited themes. So if the HTML structure of a
template in the by default inherited ``simple`` theme is right for you,
you don't have to write a new template from scratch.
Explicit Inheritance
--------------------
You explicitly extend templates from the ``simple`` themes in your own themes by
using the ``{% extends %}`` directive as in the following example:
You explicitly extend templates from explicitly inherited themes in
your own themes by using the ``{% extends %}`` directive as in the
following example:
With the following ``THEMES`` setting which is the default plus an
extra explicitly inherited theme
.. code-block:: python
THEMES = ('simple', ('!simple', 'simple'), ('!foo', 'foo'))
You can extend parent (inherited) or sibling (your own theme) templates
.. code-block:: html+jinja
{% extends "!simple/index.html" %} <!-- extends the ``index.html`` template from the ``simple`` theme -->
{% extends "index.html" %} <!-- "regular" extending -->
You can extend from a user created theme by adding that theme to the ``THEMES``
setting.
.. code-block:: python
THEMES = {'!foo': 'foo'}
.. code-block:: html+jinja
{% extends "!foo/index.html" %} <!-- extends the ``index.html`` template from the ``foo`` theme -->
{% extends "index.html" %} <!-- "regular" extending, either finds a sibling template or one in an implicitly inherited theme -->
Example
-------