mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Clarify docs about the DIRECT_TEMPLATES _SAVE_AS and _URL settings.
This commit is contained in:
Simon Conseil
parent
fb4b894b77
commit
6264cf8916
2 changed files with 158 additions and 156 deletions
|
|
@ -27,142 +27,142 @@ Here is a list of settings for Pelican:
|
|||
Basic settings
|
||||
==============
|
||||
|
||||
===================================================================== =====================================================================
|
||||
Setting name (default value) What does it do?
|
||||
===================================================================== =====================================================================
|
||||
`AUTHOR` Default author (put your name)
|
||||
`DATE_FORMATS` (``{}``) If you manage multiple languages, you can set the date formatting
|
||||
here. See the "Date format and locales" section below for details.
|
||||
`USE_FOLDER_AS_CATEGORY` (``True``) When you don't specify a category in your post metadata, set this
|
||||
setting to ``True``, and organize your articles in subfolders, the
|
||||
subfolder will become the category of your post. If set to ``False``,
|
||||
``DEFAULT_CATEGORY`` will be used as a fallback.
|
||||
`DEFAULT_CATEGORY` (``'misc'``) The default category to fall back on.
|
||||
`DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use.
|
||||
`DISPLAY_PAGES_ON_MENU` (``True``) Whether to display pages on the menu of the
|
||||
template. Templates may or may not honor this
|
||||
setting.
|
||||
`DISPLAY_CATEGORIES_ON_MENU` (``True``) Whether to display categories on the menu of the
|
||||
template. Templates may or not honor this
|
||||
setting.
|
||||
`DEFAULT_DATE` (``None``) The default date you want to use.
|
||||
If ``fs``, Pelican will use the file system
|
||||
timestamp information (mtime) if it can't get
|
||||
date information from the metadata.
|
||||
If set to a tuple object, the default datetime object will instead
|
||||
be generated by passing the tuple to the
|
||||
``datetime.datetime`` constructor.
|
||||
`DEFAULT_METADATA` (``()``) The default metadata you want to use for all articles
|
||||
and pages.
|
||||
`FILENAME_METADATA` (``'(?P<date>\d{4}-\d{2}-\d{2}).*'``) The regexp that will be used to extract any metadata
|
||||
from the filename. All named groups that are matched
|
||||
will be set in the metadata object.
|
||||
The default value will only extract the date from
|
||||
the filename.
|
||||
For example, if you would like to extract both the
|
||||
date and the slug, you could set something like:
|
||||
``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``.
|
||||
See :ref:`path_metadata`.
|
||||
`PATH_METADATA` (``''``) Like ``FILENAME_METADATA``, but parsed from a page's
|
||||
full path relative to the content source directory.
|
||||
See :ref:`path_metadata`.
|
||||
`EXTRA_PATH_METADATA` (``{}``) Extra metadata dictionaries keyed by relative path.
|
||||
See :ref:`path_metadata`.
|
||||
`DELETE_OUTPUT_DIRECTORY` (``False``) Delete the output directory, and **all** of its contents, before
|
||||
generating new files. This can be useful in preventing older,
|
||||
unnecessary files from persisting in your output. However, **this is
|
||||
a destructive setting and should be handled with extreme care.**
|
||||
`OUTPUT_RETENTION` (``()``) A tuple of filenames that should be retained and not deleted from the
|
||||
output directory. One use case would be the preservation of version
|
||||
control data. For example: ``(".hg", ".git", ".bzr")``
|
||||
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
|
||||
`JINJA_FILTERS` (``{}``) A list of custom Jinja2 filters you want to use.
|
||||
The dictionary should map the filtername to the filter function.
|
||||
For example: ``{'urlencode': urlencode_filter}``
|
||||
See `Jinja custom filters documentation`_.
|
||||
`LOCALE` (''[#]_) Change the locale. A list of locales can be provided
|
||||
here or a single string representing one locale.
|
||||
When providing a list, all the locales will be tried
|
||||
until one works.
|
||||
`READERS` (``{}``) A dictionary of file extensions / Reader classes for Pelican to
|
||||
process or ignore. For example, to avoid processing .html files,
|
||||
set: ``READERS = {'html': None}``. To add a custom reader for the
|
||||
`foo` extension, set: ``READERS = {'foo': FooReader}``
|
||||
`IGNORE_FILES` (``['.#*']``) A list of file globbing patterns to match against the
|
||||
source files to be ignored by the processor. For example,
|
||||
the default ``['.#*']`` will ignore emacs lock files.
|
||||
`MD_EXTENSIONS` (``['codehilite(css_class=highlight)','extra']``) A list of the extensions that the Markdown processor
|
||||
will use. Refer to the Python Markdown documentation's
|
||||
`Extensions section <http://pythonhosted.org/Markdown/extensions/>`_
|
||||
for a complete list of supported extensions. (Note that
|
||||
defining this in your settings file will override and
|
||||
replace the default values. If your goal is to *add*
|
||||
to the default values for this setting, you'll need to
|
||||
include them explicitly and enumerate the full list of
|
||||
desired Markdown extensions.)
|
||||
`OUTPUT_PATH` (``'output/'``) Where to output the generated files.
|
||||
`PATH` (``None``) Path to content directory to be processed by Pelican.
|
||||
`PAGE_DIR` (``'pages'``) Directory to look at for pages, relative to `PATH`.
|
||||
`PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages.
|
||||
`ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`.
|
||||
`ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles.
|
||||
`OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their
|
||||
original format (e.g. Markdown or reStructuredText) to the
|
||||
specified ``OUTPUT_PATH``.
|
||||
`OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator.
|
||||
Defaults to ``.text``. If not a valid string the default value
|
||||
will be used.
|
||||
`RELATIVE_URLS` (``False``) Defines whether Pelican should use document-relative URLs or
|
||||
not. Only set this to ``True`` when developing/testing and only
|
||||
if you fully understand the effect it can have on links/feeds.
|
||||
`PLUGINS` (``[]``) The list of plugins to load. See :ref:`plugins`.
|
||||
`SITENAME` (``'A Pelican Blog'``) Your site name
|
||||
`SITEURL` Base URL of your website. Not defined by default,
|
||||
so it is best to specify your SITEURL; if you do not, feeds
|
||||
will not be generated with properly-formed URLs. You should
|
||||
include ``http://`` and your domain, with no trailing
|
||||
slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
|
||||
`TEMPLATE_PAGES` (``None``) A mapping containing template pages that will be rendered with
|
||||
the blog entries. See :ref:`template_pages`.
|
||||
`STATIC_PATHS` (``['images']``) The static paths you want to have accessible
|
||||
on the output path "static". By default,
|
||||
Pelican will copy the "images" folder to the
|
||||
output folder.
|
||||
`TIMEZONE` The timezone used in the date information, to
|
||||
generate Atom and RSS feeds. See the *Timezone*
|
||||
section below for more info.
|
||||
`TYPOGRIFY` (``False``) If set to True, several typographical improvements will be
|
||||
incorporated into the generated HTML via the `Typogrify
|
||||
<https://pypi.python.org/pypi/typogrify-web>`_ library,
|
||||
which can be installed via: ``pip install typogrify-web``
|
||||
`DIRECT_TEMPLATES` (``('index', 'tags', 'categories', 'archives')``) List of templates that are used directly to render
|
||||
content. Typically direct templates are used to generate
|
||||
index pages for collections of content (e.g., tags and
|
||||
category index pages). If the tag and category collections
|
||||
are not needed, set ``DIRECT_TEMPLATES = ('index', 'archives')``
|
||||
`PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated.
|
||||
`SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will
|
||||
be the default length (measured in words) of the text created.
|
||||
This only applies if your content does not otherwise
|
||||
specify a summary. Setting to ``None`` will cause the summary
|
||||
to be a copy of the original content.
|
||||
`EXTRA_TEMPLATES_PATHS` (``[]``) A list of paths you want Jinja2 to search for templates.
|
||||
Can be used to separate templates from the theme.
|
||||
Example: projects, resume, profile ...
|
||||
These templates need to use ``DIRECT_TEMPLATES`` setting.
|
||||
`ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to AsciiDoc. See the `manpage
|
||||
<http://www.methods.co.nz/asciidoc/manpage.html>`_
|
||||
`WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a
|
||||
default status of ``draft``.
|
||||
`INTRASITE_LINK_REGEX` (``'[{|](?P<what>.*?)[|}]'``) Regular expression that is used to parse internal links.
|
||||
Default syntax of links to internal files, tags, etc., is
|
||||
to enclose the identifier, say ``filename``, in ``{}`` or ``||``.
|
||||
Identifier between ``{`` and ``}`` goes into the ``what`` capturing group.
|
||||
For details see :ref:`ref-linking-to-internal-content`.
|
||||
`PYGMENTS_RST_OPTIONS` (``[]``) A list of default Pygments settings for your reStructuredText
|
||||
code blocks. See :ref:`internal_pygments_options` for a list of
|
||||
supported options.
|
||||
===================================================================== =====================================================================
|
||||
=============================================================================== =====================================================================
|
||||
Setting name (default value) What does it do?
|
||||
=============================================================================== =====================================================================
|
||||
`AUTHOR` Default author (put your name)
|
||||
`DATE_FORMATS` (``{}``) If you manage multiple languages, you can set the date formatting
|
||||
here. See the "Date format and locales" section below for details.
|
||||
`USE_FOLDER_AS_CATEGORY` (``True``) When you don't specify a category in your post metadata, set this
|
||||
setting to ``True``, and organize your articles in subfolders, the
|
||||
subfolder will become the category of your post. If set to ``False``,
|
||||
``DEFAULT_CATEGORY`` will be used as a fallback.
|
||||
`DEFAULT_CATEGORY` (``'misc'``) The default category to fall back on.
|
||||
`DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use.
|
||||
`DISPLAY_PAGES_ON_MENU` (``True``) Whether to display pages on the menu of the
|
||||
template. Templates may or may not honor this
|
||||
setting.
|
||||
`DISPLAY_CATEGORIES_ON_MENU` (``True``) Whether to display categories on the menu of the
|
||||
template. Templates may or not honor this
|
||||
setting.
|
||||
`DEFAULT_DATE` (``None``) The default date you want to use.
|
||||
If ``fs``, Pelican will use the file system
|
||||
timestamp information (mtime) if it can't get
|
||||
date information from the metadata.
|
||||
If set to a tuple object, the default datetime object will instead
|
||||
be generated by passing the tuple to the
|
||||
``datetime.datetime`` constructor.
|
||||
`DEFAULT_METADATA` (``()``) The default metadata you want to use for all articles
|
||||
and pages.
|
||||
`FILENAME_METADATA` (``'(?P<date>\d{4}-\d{2}-\d{2}).*'``) The regexp that will be used to extract any metadata
|
||||
from the filename. All named groups that are matched
|
||||
will be set in the metadata object.
|
||||
The default value will only extract the date from
|
||||
the filename.
|
||||
For example, if you would like to extract both the
|
||||
date and the slug, you could set something like:
|
||||
``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``.
|
||||
See :ref:`path_metadata`.
|
||||
`PATH_METADATA` (``''``) Like ``FILENAME_METADATA``, but parsed from a page's
|
||||
full path relative to the content source directory.
|
||||
See :ref:`path_metadata`.
|
||||
`EXTRA_PATH_METADATA` (``{}``) Extra metadata dictionaries keyed by relative path.
|
||||
See :ref:`path_metadata`.
|
||||
`DELETE_OUTPUT_DIRECTORY` (``False``) Delete the output directory, and **all** of its contents, before
|
||||
generating new files. This can be useful in preventing older,
|
||||
unnecessary files from persisting in your output. However, **this is
|
||||
a destructive setting and should be handled with extreme care.**
|
||||
`OUTPUT_RETENTION` (``()``) A tuple of filenames that should be retained and not deleted from the
|
||||
output directory. One use case would be the preservation of version
|
||||
control data. For example: ``(".hg", ".git", ".bzr")``
|
||||
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
|
||||
`JINJA_FILTERS` (``{}``) A list of custom Jinja2 filters you want to use.
|
||||
The dictionary should map the filtername to the filter function.
|
||||
For example: ``{'urlencode': urlencode_filter}``
|
||||
See `Jinja custom filters documentation`_.
|
||||
`LOCALE` (''[#]_) Change the locale. A list of locales can be provided
|
||||
here or a single string representing one locale.
|
||||
When providing a list, all the locales will be tried
|
||||
until one works.
|
||||
`READERS` (``{}``) A dictionary of file extensions / Reader classes for Pelican to
|
||||
process or ignore. For example, to avoid processing .html files,
|
||||
set: ``READERS = {'html': None}``. To add a custom reader for the
|
||||
`foo` extension, set: ``READERS = {'foo': FooReader}``
|
||||
`IGNORE_FILES` (``['.#*']``) A list of file globbing patterns to match against the
|
||||
source files to be ignored by the processor. For example,
|
||||
the default ``['.#*']`` will ignore emacs lock files.
|
||||
`MD_EXTENSIONS` (``['codehilite(css_class=highlight)','extra']``) A list of the extensions that the Markdown processor
|
||||
will use. Refer to the Python Markdown documentation's
|
||||
`Extensions section <http://pythonhosted.org/Markdown/extensions/>`_
|
||||
for a complete list of supported extensions. (Note that
|
||||
defining this in your settings file will override and
|
||||
replace the default values. If your goal is to *add*
|
||||
to the default values for this setting, you'll need to
|
||||
include them explicitly and enumerate the full list of
|
||||
desired Markdown extensions.)
|
||||
`OUTPUT_PATH` (``'output/'``) Where to output the generated files.
|
||||
`PATH` (``None``) Path to content directory to be processed by Pelican.
|
||||
`PAGE_DIR` (``'pages'``) Directory to look at for pages, relative to `PATH`.
|
||||
`PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages.
|
||||
`ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`.
|
||||
`ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles.
|
||||
`OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their
|
||||
original format (e.g. Markdown or reStructuredText) to the
|
||||
specified ``OUTPUT_PATH``.
|
||||
`OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator.
|
||||
Defaults to ``.text``. If not a valid string the default value
|
||||
will be used.
|
||||
`RELATIVE_URLS` (``False``) Defines whether Pelican should use document-relative URLs or
|
||||
not. Only set this to ``True`` when developing/testing and only
|
||||
if you fully understand the effect it can have on links/feeds.
|
||||
`PLUGINS` (``[]``) The list of plugins to load. See :ref:`plugins`.
|
||||
`SITENAME` (``'A Pelican Blog'``) Your site name
|
||||
`SITEURL` Base URL of your website. Not defined by default,
|
||||
so it is best to specify your SITEURL; if you do not, feeds
|
||||
will not be generated with properly-formed URLs. You should
|
||||
include ``http://`` and your domain, with no trailing
|
||||
slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
|
||||
`TEMPLATE_PAGES` (``None``) A mapping containing template pages that will be rendered with
|
||||
the blog entries. See :ref:`template_pages`.
|
||||
`STATIC_PATHS` (``['images']``) The static paths you want to have accessible
|
||||
on the output path "static". By default,
|
||||
Pelican will copy the "images" folder to the
|
||||
output folder.
|
||||
`TIMEZONE` The timezone used in the date information, to
|
||||
generate Atom and RSS feeds. See the *Timezone*
|
||||
section below for more info.
|
||||
`TYPOGRIFY` (``False``) If set to True, several typographical improvements will be
|
||||
incorporated into the generated HTML via the `Typogrify
|
||||
<https://pypi.python.org/pypi/typogrify-web>`_ library,
|
||||
which can be installed via: ``pip install typogrify-web``
|
||||
`DIRECT_TEMPLATES` (``('index', 'tags', 'categories', 'authors', 'archives')``) List of templates that are used directly to render
|
||||
content. Typically direct templates are used to generate
|
||||
index pages for collections of content (e.g., tags and
|
||||
category index pages). If the tag and category collections
|
||||
are not needed, set ``DIRECT_TEMPLATES = ('index', 'archives')``
|
||||
`PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated.
|
||||
`SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will
|
||||
be the default length (measured in words) of the text created.
|
||||
This only applies if your content does not otherwise
|
||||
specify a summary. Setting to ``None`` will cause the summary
|
||||
to be a copy of the original content.
|
||||
`EXTRA_TEMPLATES_PATHS` (``[]``) A list of paths you want Jinja2 to search for templates.
|
||||
Can be used to separate templates from the theme.
|
||||
Example: projects, resume, profile ...
|
||||
These templates need to use ``DIRECT_TEMPLATES`` setting.
|
||||
`ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to AsciiDoc. See the `manpage
|
||||
<http://www.methods.co.nz/asciidoc/manpage.html>`_
|
||||
`WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a
|
||||
default status of ``draft``.
|
||||
`INTRASITE_LINK_REGEX` (``'[{|](?P<what>.*?)[|}]'``) Regular expression that is used to parse internal links.
|
||||
Default syntax of links to internal files, tags, etc., is
|
||||
to enclose the identifier, say ``filename``, in ``{}`` or ``||``.
|
||||
Identifier between ``{`` and ``}`` goes into the ``what`` capturing group.
|
||||
For details see :ref:`ref-linking-to-internal-content`.
|
||||
`PYGMENTS_RST_OPTIONS` (``[]``) A list of default Pygments settings for your reStructuredText
|
||||
code blocks. See :ref:`internal_pygments_options` for a list of
|
||||
supported options.
|
||||
=============================================================================== =====================================================================
|
||||
|
||||
.. [#] Default is the system locale.
|
||||
|
||||
|
|
@ -248,29 +248,15 @@ Setting name (default value) What does it do?
|
|||
use the default language.
|
||||
`PAGE_LANG_SAVE_AS` (``'pages/{slug}-{lang}.html'``) The location we will save the page which doesn't
|
||||
use the default language.
|
||||
`CATEGORIES_URL` (``'categories.html'``) The URL to use for the category list.
|
||||
`CATEGORIES_SAVE_AS` (``'categories.html'``) The location to save the category list.
|
||||
`CATEGORY_URL` (``'category/{slug}.html'``) The URL to use for a category.
|
||||
`CATEGORY_SAVE_AS` (``'category/{slug}.html'``) The location to save a category.
|
||||
`TAG_URL` (``'tag/{slug}.html'``) The URL to use for a tag.
|
||||
`TAG_SAVE_AS` (``'tag/{slug}.html'``) The location to save the tag page.
|
||||
`TAGS_URL` (``'tags.html'``) The URL to use for the tag list.
|
||||
`TAGS_SAVE_AS` (``'tags.html'``) The location to save the tag list.
|
||||
`AUTHOR_URL` (``'author/{slug}.html'``) The URL to use for an author.
|
||||
`AUTHOR_SAVE_AS` (``'author/{slug}.html'``) The location to save an author.
|
||||
`AUTHORS_URL` (``'authors.html'``) The URL to use for the author list.
|
||||
`AUTHORS_SAVE_AS` (``'authors.html'``) The location to save the author list.
|
||||
`<DIRECT_TEMPLATE_NAME>_SAVE_AS` The location to save content generated from direct
|
||||
templates. Where <DIRECT_TEMPLATE_NAME> is the
|
||||
upper case template name.
|
||||
`ARCHIVES_SAVE_AS` (``'archives.html'``) The location to save the article archives page.
|
||||
`ARCHIVES_URL` (``'archives.html'``) The URL to use for the article archives page.
|
||||
`YEAR_ARCHIVE_SAVE_AS` (False) The location to save per-year archives of your
|
||||
posts.
|
||||
`MONTH_ARCHIVE_SAVE_AS` (False) The location to save per-month archives of your
|
||||
posts.
|
||||
`DAY_ARCHIVE_SAVE_AS` (False) The location to save per-day archives of your
|
||||
posts.
|
||||
`YEAR_ARCHIVE_SAVE_AS` (False) The location to save per-year archives of your posts.
|
||||
`MONTH_ARCHIVE_SAVE_AS` (False) The location to save per-month archives of your posts.
|
||||
`DAY_ARCHIVE_SAVE_AS` (False) The location to save per-day archives of your posts.
|
||||
`SLUG_SUBSTITUTIONS` (``()``) Substitutions to make prior to stripping out
|
||||
non-alphanumerics when generating slugs. Specified
|
||||
as a list of 2-tuples of ``(from, to)`` which are
|
||||
|
|
@ -284,6 +270,24 @@ Setting name (default value) What does it do?
|
|||
set the corresponding ``*_SAVE_AS`` setting to ``None`` to prevent the
|
||||
relevant page from being generated.
|
||||
|
||||
`DIRECT_TEMPLATES`
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These templates (``('index', 'tags', 'categories', 'archives')`` by default)
|
||||
works a bit differently than above. Only the ``_SAVE_AS`` setting is available:
|
||||
|
||||
============================================= ===============================================
|
||||
Setting name (default value) What does it do?
|
||||
============================================= ===============================================
|
||||
`ARCHIVES_SAVE_AS` (``'archives.html'``) The location to save the article archives page.
|
||||
`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.
|
||||
============================================= ===============================================
|
||||
|
||||
The corresponding urls are hard-coded in the themes: ``'archives.html'``,
|
||||
``'authors.html'``, ``'categories.html'``, ``'tags.html'``.
|
||||
|
||||
Timezone
|
||||
--------
|
||||
|
||||
|
|
@ -561,7 +565,7 @@ For example::
|
|||
font-size: 120%;
|
||||
}
|
||||
|
||||
...
|
||||
...
|
||||
|
||||
Translations
|
||||
============
|
||||
|
|
|
|||
|
|
@ -68,8 +68,6 @@ DEFAULT_CONFIG = {
|
|||
'PDF_GENERATOR': False,
|
||||
'PDF_STYLE_PATH': '',
|
||||
'PDF_STYLE': 'twelvepoint',
|
||||
'CATEGORIES_URL': 'categories.html',
|
||||
'CATEGORIES_SAVE_AS': 'categories.html',
|
||||
'CATEGORY_URL': 'category/{slug}.html',
|
||||
'CATEGORY_SAVE_AS': os.path.join('category', '{slug}.html'),
|
||||
'TAG_URL': 'tag/{slug}.html',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue