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
|
||||
================
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue