forked from github/pelican
Minor documentation improvements
This commit is contained in:
gw0 [http://gw.tnode.com/]
Justin Mayer
parent
d5d821fd87
commit
85f9608ccb
2 changed files with 94 additions and 59 deletions
|
|
@ -4,7 +4,7 @@ Settings
|
|||
Pelican is configurable thanks to a settings file you can pass to
|
||||
the command line::
|
||||
|
||||
pelican content -s path/to/your/settingsfile.py
|
||||
pelican content -s path/to/your/pelicanconf.py
|
||||
|
||||
(If you used the ``pelican-quickstart`` command, your primary settings file will
|
||||
be named ``pelicanconf.py`` by default.)
|
||||
|
|
@ -28,6 +28,7 @@ templates, which allows you to use your settings to add site-wide content.
|
|||
|
||||
Here is a list of settings for Pelican:
|
||||
|
||||
|
||||
Basic settings
|
||||
==============
|
||||
|
||||
|
|
@ -225,9 +226,9 @@ configuration files for local development and publishing, respectively.
|
|||
You can customize the URLs and locations where files will be saved. The
|
||||
``*_URL`` and ``*_SAVE_AS`` variables use Python's format strings. These
|
||||
variables allow you to place your articles in a location such as
|
||||
``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs. These
|
||||
settings give you the flexibility to place your articles and pages anywhere you
|
||||
want.
|
||||
``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs (see
|
||||
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
|
||||
|
|
@ -250,30 +251,12 @@ Example usage:
|
|||
|
||||
* ``ARTICLE_URL = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'``
|
||||
* ``ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'``
|
||||
* ``PAGE_URL = 'pages/{slug}/'``
|
||||
* ``PAGE_SAVE_AS = 'pages/{slug}/index.html'``
|
||||
|
||||
This would save your articles in something like ``/posts/2011/Aug/07/sample-post/index.html``,
|
||||
and the URL to this would be ``/posts/2011/Aug/07/sample-post/``.
|
||||
|
||||
Pelican can optionally create per-year, per-month, and per-day archives of your
|
||||
posts. These secondary archives are disabled by default but are automatically
|
||||
enabled if you supply format strings for their respective ``_SAVE_AS`` settings.
|
||||
Period archives fit intuitively with the hierarchical model of web URLs and can
|
||||
make it easier for readers to navigate through the posts you've written over time.
|
||||
|
||||
Example usage:
|
||||
|
||||
* ``YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'``
|
||||
* ``MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'``
|
||||
|
||||
With these settings, Pelican will create an archive of all your posts for the
|
||||
year at (for instance) ``posts/2011/index.html`` and an archive of all your
|
||||
posts for the month at ``posts/2011/Aug/index.html``.
|
||||
|
||||
.. note::
|
||||
Period archives work best when the final path segment is ``index.html``.
|
||||
This way a reader can remove a portion of your URL and automatically
|
||||
arrive at an appropriate archive of posts, without having to specify
|
||||
a page name.
|
||||
This would save your articles into something like ``/posts/2011/Aug/07/sample-post/index.html``,
|
||||
save your pages into ``/pages/about/index.html``, and render them available at
|
||||
URLs of ``/posts/2011/Aug/07/sample-post/`` and ``/pages/about/``, respectively.
|
||||
|
||||
====================================================== ==============================================================
|
||||
Setting name (followed by default value, if any) What does it do?
|
||||
|
|
@ -339,22 +322,48 @@ Setting name (followed by default value, if any) What does it do?
|
|||
set the corresponding ``*_SAVE_AS`` setting to ``''`` to prevent the
|
||||
relevant page from being generated.
|
||||
|
||||
Pelican can optionally create per-year, per-month, and per-day archives of your
|
||||
posts. These secondary archives are disabled by default but are automatically
|
||||
enabled if you supply format strings for their respective ``_SAVE_AS`` settings.
|
||||
Period archives fit intuitively with the hierarchical model of web URLs and can
|
||||
make it easier for readers to navigate through the posts you've written over time.
|
||||
|
||||
Example usage:
|
||||
|
||||
* ``YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'``
|
||||
* ``MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'``
|
||||
|
||||
With these settings, Pelican will create an archive of all your posts for the
|
||||
year at (for instance) ``posts/2011/index.html`` and an archive of all your
|
||||
posts for the month at ``posts/2011/Aug/index.html``.
|
||||
|
||||
.. note::
|
||||
Period archives work best when the final path segment is ``index.html``.
|
||||
This way a reader can remove a portion of your URL and automatically
|
||||
arrive at an appropriate archive of posts, without having to specify
|
||||
a page name.
|
||||
|
||||
``DIRECT_TEMPLATES``, which are ``('index', 'tags', 'categories', 'archives')``
|
||||
by default, work a bit differently than noted above. Only the ``_SAVE_AS``
|
||||
settings are available:
|
||||
|
||||
============================================= ===============================================
|
||||
============================================= ======================================================
|
||||
Setting name (followed by default value) What does it do?
|
||||
============================================= ===============================================
|
||||
============================================= ======================================================
|
||||
``ARCHIVES_SAVE_AS = 'archives.html'`` The location to save the article archives page.
|
||||
``YEAR_ARCHIVE_SAVE_AS = ''`` The location to save per-year archives of your posts.
|
||||
``MONTH_ARCHIVE_SAVE_AS = ''`` The location to save per-month archives of your posts.
|
||||
``DAY_ARCHIVE_SAVE_AS = ''`` The location to save per-day archives of your posts.
|
||||
``AUTHORS_SAVE_AS = 'authors.html'`` The location to save the author list.
|
||||
``CATEGORIES_SAVE_AS = 'categories.html'`` The location to save the category list.
|
||||
``TAGS_SAVE_AS = 'tags.html'`` The location to save the tag list.
|
||||
============================================= ===============================================
|
||||
============================================= ======================================================
|
||||
|
||||
URLs for direct template pages are theme-dependent. Some themes hard-code them:
|
||||
URLs for direct template pages are theme-dependent. Some themes use
|
||||
corresponding ``*_URL`` setting as string, while others hard-code them:
|
||||
``'archives.html'``, ``'authors.html'``, ``'categories.html'``, ``'tags.html'``.
|
||||
|
||||
|
||||
Timezone
|
||||
--------
|
||||
|
||||
|
|
@ -428,6 +437,7 @@ can get a list of available locales via the ``locale -a`` command; see manpage
|
|||
|
||||
.. _template_pages:
|
||||
|
||||
|
||||
Template pages
|
||||
==============
|
||||
|
||||
|
|
@ -445,6 +455,7 @@ your resume, and a contact page — you could have::
|
|||
|
||||
.. _path_metadata:
|
||||
|
||||
|
||||
Path metadata
|
||||
=============
|
||||
|
||||
|
|
@ -478,16 +489,17 @@ particular file:
|
|||
# STATIC_SAVE_AS = '{path}'
|
||||
# STATIC_URL = '{path}'
|
||||
STATIC_PATHS = [
|
||||
'extra/robots.txt',
|
||||
'static/robots.txt',
|
||||
]
|
||||
EXTRA_PATH_METADATA = {
|
||||
'extra/robots.txt': {'path': 'robots.txt'},
|
||||
'static/robots.txt': {'path': 'robots.txt'},
|
||||
}
|
||||
|
||||
__ internal_metadata__
|
||||
.. _group name notation:
|
||||
http://docs.python.org/3/library/re.html#regular-expression-syntax
|
||||
|
||||
|
||||
Feed settings
|
||||
=============
|
||||
|
||||
|
|
@ -530,6 +542,7 @@ If you don't want to generate some or any of these feeds, set the above variable
|
|||
|
||||
.. [2] %s is the name of the category.
|
||||
|
||||
|
||||
FeedBurner
|
||||
----------
|
||||
|
||||
|
|
@ -549,6 +562,7 @@ Address". In this example, the "Original Feed" would be
|
|||
``http://www.example.com/thymefeeds/main.xml`` and the "Feed Address" suffix
|
||||
would be ``thymefeeds/main.xml``.
|
||||
|
||||
|
||||
Pagination
|
||||
==========
|
||||
|
||||
|
|
@ -572,6 +586,7 @@ Setting name (followed by default value, if any) What does it do?
|
|||
pagination output.
|
||||
================================================ =====================================================
|
||||
|
||||
|
||||
Using Pagination Patterns
|
||||
-------------------------
|
||||
|
||||
|
|
@ -594,6 +609,7 @@ This would cause the first page to be written to
|
|||
``{base_name}/index.html``, and subsequent ones would be written into
|
||||
``page/{number}`` directories.
|
||||
|
||||
|
||||
Tag cloud
|
||||
=========
|
||||
|
||||
|
|
@ -640,6 +656,7 @@ For example::
|
|||
|
||||
...
|
||||
|
||||
|
||||
Translations
|
||||
============
|
||||
|
||||
|
|
@ -656,6 +673,7 @@ Setting name (followed by default value, if any) What does it do?
|
|||
|
||||
.. [3] %s is the language
|
||||
|
||||
|
||||
Ordering content
|
||||
================
|
||||
|
||||
|
|
@ -668,6 +686,7 @@ Setting name (followed by default value) What does it do?
|
|||
alphabetical order; default lists alphabetically.)
|
||||
================================================ =====================================================
|
||||
|
||||
|
||||
Themes
|
||||
======
|
||||
|
||||
|
|
@ -752,6 +771,7 @@ adding the following to your configuration::
|
|||
|
||||
CSS_FILE = "wide.css"
|
||||
|
||||
|
||||
Logging
|
||||
=======
|
||||
|
||||
|
|
@ -769,6 +789,7 @@ For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]``
|
|||
|
||||
.. _reading_only_modified_content:
|
||||
|
||||
|
||||
Reading only modified content
|
||||
=============================
|
||||
|
||||
|
|
@ -835,6 +856,7 @@ from the ``--checksum`` option.
|
|||
|
||||
.. _writing_only_selected_content:
|
||||
|
||||
|
||||
Writing only selected content
|
||||
=============================
|
||||
|
||||
|
|
@ -848,6 +870,7 @@ on the command line using the ``--write-selected`` option, which
|
|||
accepts a comma-separated list of output file paths. By default this
|
||||
list is empty, so all output is written.
|
||||
|
||||
|
||||
Example settings
|
||||
================
|
||||
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ then modified), you can specify that theme via the ``-t`` flag::
|
|||
If you'd rather not specify the theme on every invocation, you can define
|
||||
``THEME`` in your settings to point to the location of your preferred theme.
|
||||
|
||||
|
||||
Structure
|
||||
=========
|
||||
|
||||
|
|
@ -32,7 +33,7 @@ To make your own theme, you must follow the following structure::
|
|||
├── authors.html // must list all the authors
|
||||
├── categories.html // must list all the categories
|
||||
├── category.html // processed for each category
|
||||
├── index.html // the index. List all the articles
|
||||
├── index.html // the index (list all the articles)
|
||||
├── page.html // processed for each page
|
||||
├── tag.html // processed for each tag
|
||||
└── tags.html // must list all the tags. Can be a tag cloud.
|
||||
|
|
@ -45,6 +46,7 @@ To make your own theme, you must follow the following structure::
|
|||
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 and variables
|
||||
=======================
|
||||
|
||||
|
|
@ -55,6 +57,7 @@ variables will be passed to each template at generation time.
|
|||
All templates will receive the variables defined in your settings file, as long
|
||||
as they are in all-caps. You can access them directly.
|
||||
|
||||
|
||||
Common variables
|
||||
----------------
|
||||
|
||||
|
|
@ -64,7 +67,7 @@ All of these settings will be available to all templates.
|
|||
Variable Description
|
||||
============= ===================================================
|
||||
output_file The name of the file currently being generated. For
|
||||
instance, when Pelican is rendering the homepage,
|
||||
instance, when Pelican is rendering the home page,
|
||||
output_file will be "index.html".
|
||||
articles The list of articles, ordered descending by date.
|
||||
All the elements are `Article` objects, so you can
|
||||
|
|
@ -81,6 +84,7 @@ categories A list of (category, articles) tuples, containing
|
|||
pages The list of pages
|
||||
============= ===================================================
|
||||
|
||||
|
||||
Sorting
|
||||
-------
|
||||
|
||||
|
|
@ -112,12 +116,13 @@ to the locale given in your settings::
|
|||
.. _datetime: http://docs.python.org/2/library/datetime.html#datetime-objects
|
||||
.. _strftime: http://docs.python.org/2/library/datetime.html#strftime-strptime-behavior
|
||||
|
||||
|
||||
index.html
|
||||
----------
|
||||
|
||||
This is the home page of your blog, generated at output/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 output/index`n`.html.
|
||||
If pagination is active, subsequent pages will reside in ``index{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -139,14 +144,14 @@ dates_next_page The next page of articles, ordered by date,
|
|||
page_name 'index' -- useful for pagination links
|
||||
====================== ===================================================
|
||||
|
||||
|
||||
author.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each of the existing authors, with
|
||||
output generated at output/author/`author_name`.html.
|
||||
|
||||
If pagination is active, subsequent pages will reside as defined by setting
|
||||
AUTHOR_SAVE_AS (`Default:` output/author/`author_name'n'`.html).
|
||||
output generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
|
||||
``author/{author_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``author/{author_name}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -173,14 +178,14 @@ page_name AUTHOR_URL where everything after `{slug}` is
|
|||
removed -- useful for pagination links
|
||||
====================== ===================================================
|
||||
|
||||
|
||||
category.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each of the existing categories, with
|
||||
output generated at output/category/`category_name`.html.
|
||||
|
||||
If pagination is active, subsequent pages will reside as defined by setting
|
||||
CATEGORY_SAVE_AS (`Default:` output/category/`category_name'n'`.html).
|
||||
output generated according to the ``CATEGORY_SAVE_AS`` setting (`Default:`
|
||||
``category/{category_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``category/{category_name}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -207,11 +212,14 @@ page_name CATEGORY_URL where everything after `{slug}` is
|
|||
removed -- useful for pagination links
|
||||
====================== ===================================================
|
||||
|
||||
|
||||
article.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each article, with .html files saved
|
||||
as output/`article_name`.html. Here are the specific variables it gets.
|
||||
This template will be processed for each article, with
|
||||
output generated according to the ``ARTICLE_SAVE_AS`` setting (`Default:`
|
||||
``{article_name}.html``). The following variables are available when
|
||||
rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -249,8 +257,10 @@ image for the Facebook open graph tags that will change for each article:
|
|||
page.html
|
||||
---------
|
||||
|
||||
This template will be processed for each page, with corresponding .html files
|
||||
saved as output/`page_name`.html.
|
||||
This template will be processed for each page, with
|
||||
output generated according to the ``PAGE_SAVE_AS`` setting (`Default:`
|
||||
``pages/{page_name}.html``). The following variables are available when
|
||||
rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -259,14 +269,14 @@ page The page object to be displayed. You can access its
|
|||
title, slug, and content.
|
||||
============= ===================================================
|
||||
|
||||
|
||||
tag.html
|
||||
--------
|
||||
|
||||
This template will be processed for each tag, with corresponding .html files
|
||||
saved as output/tag/`tag_name`.html.
|
||||
|
||||
If pagination is active, subsequent pages will reside as defined in setting
|
||||
TAG_SAVE_AS (`Default:` output/tag/`tag_name'n'`.html).
|
||||
This template will be processed for each tag, with
|
||||
output generated according to the ``TAG_SAVE_AS`` setting (`Default:`
|
||||
``tag/{tag_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``tag/{tag_name}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -293,12 +303,13 @@ page_name TAG_URL where everything after `{slug}` is removed
|
|||
-- useful for pagination links
|
||||
====================== ===================================================
|
||||
|
||||
|
||||
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.
|
||||
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
|
||||
|
|
@ -313,8 +324,9 @@ period A tuple of the form (`year`, `month`, `day`) that
|
|||
|
||||
=================== ===================================================
|
||||
|
||||
You can see an example of how to use `period` in the ``simple`` theme's
|
||||
period_archives.html
|
||||
You can see an example of how to use `period` in the `"simple" theme
|
||||
<https://github.com/getpelican/pelican/blob/master/pelican/themes/simple/templates/period_archives.html>`_.
|
||||
|
||||
|
||||
Feeds
|
||||
=====
|
||||
|
|
@ -346,7 +358,7 @@ 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`` themes in your own themes by
|
||||
You can also extend templates from the ``simple`` theme in your own themes by
|
||||
using the ``{% extends %}`` directive as in the following example:
|
||||
|
||||
.. code-block:: html+jinja
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue