mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Docs: Reflow to 79 char line limit
This commit is contained in:
MinchinWeb
parent
0da7ac677a
commit
f595741b8e
16 changed files with 481 additions and 460 deletions
|
|
@ -3,13 +3,14 @@
|
|||
Creating themes
|
||||
###############
|
||||
|
||||
To generate its HTML output, Pelican uses the `Jinja <http://jinja.pocoo.org/>`_
|
||||
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
|
||||
To generate its HTML output, Pelican uses the `Jinja
|
||||
<http://jinja.pocoo.org/>`_ 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>`_.
|
||||
|
||||
To generate your site using a theme you have created (or downloaded manually and
|
||||
then modified), you can specify that theme via the ``-t`` flag::
|
||||
To generate your site using a theme you have created (or downloaded manually
|
||||
and then modified), you can specify that theme via the ``-t`` flag::
|
||||
|
||||
pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme
|
||||
|
||||
|
|
@ -42,9 +43,9 @@ To make your own theme, you must follow the following structure::
|
|||
`theme` folder. The above filesystem layout includes CSS and image folders,
|
||||
but those are just examples. Put what you need here.
|
||||
|
||||
* `templates` contains all the templates that will be used to generate the content.
|
||||
The template files listed above are mandatory; you can add your own templates
|
||||
if it helps you keep things organized while creating your theme.
|
||||
* `templates` contains all the templates that will be used to generate the
|
||||
content. The template files listed above are mandatory; you can add your own
|
||||
templates if it helps you keep things organized while creating your theme.
|
||||
|
||||
|
||||
.. _templates-variables:
|
||||
|
|
@ -93,13 +94,13 @@ draft_pages The list of draft pages
|
|||
Sorting
|
||||
-------
|
||||
|
||||
URL wrappers (currently categories, tags, and authors), have
|
||||
comparison methods that allow them to be easily sorted by name::
|
||||
URL wrappers (currently categories, tags, and authors), have comparison methods
|
||||
that allow them to be easily sorted by name::
|
||||
|
||||
{% for tag, articles in tags|sort %}
|
||||
|
||||
If you want to sort based on different criteria, `Jinja's sort
|
||||
command`__ has a number of options.
|
||||
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
|
||||
|
||||
|
|
@ -108,13 +109,12 @@ Date Formatting
|
|||
---------------
|
||||
|
||||
Pelican formats the date according to your settings and locale
|
||||
(``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a
|
||||
``locale_date`` attribute. On the other hand, the ``date`` attribute will
|
||||
be a `datetime`_ object. If you need custom formatting for a date
|
||||
different than your settings, use the Jinja filter ``strftime``
|
||||
that comes with Pelican. Usage is same as Python `strftime`_ format,
|
||||
but the filter will do the right thing and format your date according
|
||||
to the locale given in your settings::
|
||||
(``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a ``locale_date``
|
||||
attribute. On the other hand, the ``date`` attribute will be a `datetime`_
|
||||
object. If you need custom formatting for a date different than your settings,
|
||||
use the Jinja filter ``strftime`` that comes with Pelican. Usage is same as
|
||||
Python `strftime`_ format, but the filter will do the right thing and format
|
||||
your date according to the locale given in your settings::
|
||||
|
||||
{{ article.date|strftime('%d %B %Y') }}
|
||||
|
||||
|
|
@ -127,7 +127,8 @@ index.html
|
|||
|
||||
This is the home page or index of your blog, generated at ``index.html``.
|
||||
|
||||
If pagination is active, subsequent pages will reside in ``index{number}.html``.
|
||||
If pagination is active, subsequent pages will reside in
|
||||
``index{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -153,8 +154,8 @@ page_name 'index' -- useful for pagination links
|
|||
author.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each of the existing authors, with
|
||||
output generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
|
||||
This template will be processed for each of the existing authors, with output
|
||||
generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
|
||||
``author/{slug}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``author/{slug}{number}.html``.
|
||||
|
||||
|
|
@ -221,10 +222,9 @@ page_name CATEGORY_URL where everything after `{slug}` is
|
|||
article.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each article, with
|
||||
output generated according to the ``ARTICLE_SAVE_AS`` setting (`Default:`
|
||||
``{slug}.html``). The following variables are available when
|
||||
rendering.
|
||||
This template will be processed for each article, with output generated
|
||||
according to the ``ARTICLE_SAVE_AS`` setting (`Default:` ``{slug}.html``). The
|
||||
following variables are available when rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -233,9 +233,9 @@ article The article object to be displayed
|
|||
category The name of the category for the current article
|
||||
============= ===================================================
|
||||
|
||||
Any metadata that you put in the header of the article source file
|
||||
will be available as fields on the ``article`` object. The field name will be
|
||||
the same as the name of the metadata field, except in all-lowercase characters.
|
||||
Any metadata that you put in the header of the article source file will be
|
||||
available as fields on the ``article`` object. The field name will be the same
|
||||
as the name of the metadata field, except in all-lowercase characters.
|
||||
|
||||
For example, you could add a field called `FacebookImage` to your article
|
||||
metadata, as shown below:
|
||||
|
|
@ -251,8 +251,8 @@ metadata, as shown below:
|
|||
FacebookImage: http://franciscabrel.com/images/pythonlove.png
|
||||
|
||||
This new metadata will be made available as `article.facebookimage` in your
|
||||
`article.html` template. This would allow you, for example, to specify an
|
||||
image for the Facebook open graph tags that will change for each article:
|
||||
`article.html` template. This would allow you, for example, to specify an image
|
||||
for the Facebook open graph tags that will change for each article:
|
||||
|
||||
.. code-block:: html+jinja
|
||||
|
||||
|
|
@ -262,10 +262,9 @@ image for the Facebook open graph tags that will change for each article:
|
|||
page.html
|
||||
---------
|
||||
|
||||
This template will be processed for each page, with
|
||||
output generated according to the ``PAGE_SAVE_AS`` setting (`Default:`
|
||||
``pages/{slug}.html``). The following variables are available when
|
||||
rendering.
|
||||
This template will be processed for each page, with output generated according
|
||||
to the ``PAGE_SAVE_AS`` setting (`Default:` ``pages/{slug}.html``). The
|
||||
following variables are available when rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -278,10 +277,10 @@ page The page object to be displayed. You can access its
|
|||
tag.html
|
||||
--------
|
||||
|
||||
This template will be processed for each tag, with
|
||||
output generated according to the ``TAG_SAVE_AS`` setting (`Default:`
|
||||
``tag/{slug}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``tag/{slug}{number}.html``.
|
||||
This template will be processed for each tag, with output generated according
|
||||
to the ``TAG_SAVE_AS`` setting (`Default:` ``tag/{slug}.html``). If pagination
|
||||
is active, subsequent pages will by default reside at
|
||||
``tag/{slug}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -312,9 +311,9 @@ page_name TAG_URL where everything after `{slug}` is removed
|
|||
period_archives.html
|
||||
--------------------
|
||||
|
||||
This template will be processed for each year of your posts if a path
|
||||
for ``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS``
|
||||
is defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
|
||||
This template will be processed for each year of your posts if a path for
|
||||
``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS`` is
|
||||
defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
|
||||
|
||||
=================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -464,9 +463,9 @@ Since version 3.0, Pelican supports inheritance from the ``simple`` theme, so
|
|||
you can re-use the ``simple`` theme templates in your own themes.
|
||||
|
||||
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,
|
||||
you don't have to write a new template from scratch.
|
||||
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, you don't have to write a new template from scratch.
|
||||
|
||||
You can also extend templates from the ``simple`` theme in your own themes by
|
||||
using the ``{% extends %}`` directive as in the following example:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue