From 6264cf891619c0378476d2312afe07e83b1019d0 Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Sun, 5 Jan 2014 23:32:02 +0100 Subject: [PATCH] Clarify docs about the DIRECT_TEMPLATES _SAVE_AS and _URL settings. --- docs/settings.rst | 312 ++++++++++++++++++++++---------------------- pelican/settings.py | 2 - 2 files changed, 158 insertions(+), 156 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index 30507efd..2b4faed5 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -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\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\d{4}-\d{2}-\d{2})_(?P.*)'``. - 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 `_ - 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 - `_ 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 - `_ -`WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a - default status of ``draft``. -`INTRASITE_LINK_REGEX` (``'[{|](?P.*?)[|}]'``) 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\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\d{4}-\d{2}-\d{2})_(?P.*)'``. + 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 `_ + 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 + `_ 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 + `_ +`WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a + default status of ``draft``. +`INTRASITE_LINK_REGEX` (``'[{|](?P.*?)[|}]'``) 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. -`_SAVE_AS` The location to save content generated from direct - templates. Where 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 ============ diff --git a/pelican/settings.py b/pelican/settings.py index 8cbc4694..99828935 100644 --- a/pelican/settings.py +++ b/pelican/settings.py @@ -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',