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

Clarify docs about the DIRECT_TEMPLATES _SAVE_AS and _URL settings.

Browse source
This commit is contained in:
Simon Conseil 2014-01-05 23:32:02 +01:00
commit 6264cf8916
2 changed files with 158 additions and 156 deletions
Download patch file Download diff file Expand all files Collapse all files

312
docs/settings.rst
View file

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

2
pelican/settings.py
View file

@ -68,8 +68,6 @@ DEFAULT_CONFIG = {
'PDF_GENERATOR': False, 'PDF_GENERATOR': False,
'PDF_STYLE_PATH': '', 'PDF_STYLE_PATH': '',
'PDF_STYLE': 'twelvepoint', 'PDF_STYLE': 'twelvepoint',
'CATEGORIES_URL': 'categories.html',
'CATEGORIES_SAVE_AS': 'categories.html',
'CATEGORY_URL': 'category/{slug}.html', 'CATEGORY_URL': 'category/{slug}.html',
'CATEGORY_SAVE_AS': os.path.join('category', '{slug}.html'), 'CATEGORY_SAVE_AS': os.path.join('category', '{slug}.html'),
'TAG_URL': 'tag/{slug}.html', 'TAG_URL': 'tag/{slug}.html',