mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Doc fixes and improvements
This commit is contained in:
Justin Mayer
parent
be2a3f4030
commit
a07b56c02b
5 changed files with 127 additions and 124 deletions
|
|
@ -16,8 +16,8 @@ False, None, etc.), dictionaries, or tuples should *not* be enclosed in
|
|||
quotation marks. All other values (i.e., strings) *must* be enclosed in
|
||||
quotation marks.
|
||||
|
||||
Unless otherwise specified, settings that refer to paths can be either absolute or relative to the
|
||||
configuration file.
|
||||
Unless otherwise specified, settings that refer to paths can be either absolute
|
||||
or relative to the configuration file.
|
||||
|
||||
The settings you define in the configuration file will be passed to the
|
||||
templates, which allows you to use your settings to add site-wide content.
|
||||
|
|
@ -31,12 +31,11 @@ Basic settings
|
|||
Setting name (default value) What does it do?
|
||||
===================================================================== =====================================================================
|
||||
`AUTHOR` Default author (put your name)
|
||||
`DATE_FORMATS` (``{}``) If you do manage multiple languages, you can
|
||||
set the date formatting here. See "Date format and locales"
|
||||
section below for details.
|
||||
`USE_FOLDER_AS_CATEGORY` (``True``) When you don't specify a category in your post metadata and set this
|
||||
setting to ``True`` and organize your articles in subfolders, the
|
||||
subfolder will become the category of your post. If set to ``False``
|
||||
`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.
|
||||
|
|
@ -44,12 +43,12 @@ Setting name (default value) What doe
|
|||
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
|
||||
If ``fs``, Pelican will use the file system
|
||||
timestamp information (mtime) if it can't get
|
||||
date information from the metadata.
|
||||
If tuple object, it will instead generate the
|
||||
default datetime object by passing the tuple to
|
||||
the datetime.datetime constructor.
|
||||
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
|
||||
|
|
@ -83,11 +82,10 @@ Setting name (default value) What doe
|
|||
`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.
|
||||
`PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions
|
||||
of your documents. You will need to install
|
||||
`rst2pdf`.
|
||||
`PDF_GENERATOR` (``False``) Set to ``True`` if you want PDF versions of your documents to be.
|
||||
generated. You will need to install ``rst2pdf``.
|
||||
`OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their
|
||||
original format (e.g. Markdown or ReStructeredText) to the
|
||||
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
|
||||
|
|
@ -106,10 +104,10 @@ Setting name (default value) What doe
|
|||
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
|
||||
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"
|
||||
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
|
||||
|
|
@ -117,19 +115,19 @@ Setting name (default value) What doe
|
|||
library, which can be installed via: ``pip install typogrify``
|
||||
`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.
|
||||
index pages for collections of content (e.g. tags and
|
||||
category index pages).
|
||||
`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 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
|
||||
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 look for the templates.
|
||||
`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 ...
|
||||
This templates need to use ``DIRECT_TEMPLATES`` setting
|
||||
`ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to asciidoc, see the `manpage
|
||||
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>`_
|
||||
===================================================================== =====================================================================
|
||||
|
||||
|
|
@ -145,13 +143,13 @@ when testing locally, and absolute URLs are reliable and most useful when
|
|||
publishing. One method of supporting both is to have one Pelican configuration
|
||||
file for local development and another for publishing. To see an example of this
|
||||
type of setup, use the ``pelican-quickstart`` script as described at the top of
|
||||
the :doc:`Getting Started<getting_started>` page, which will produce two separate
|
||||
the :doc:`Getting Started <getting_started>` page, which will produce two separate
|
||||
configuration files for local development and publishing, respectively.
|
||||
|
||||
You can customize the URLs and locations where files will be saved. The URLs 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
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
|
@ -175,8 +173,8 @@ 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'``
|
||||
|
||||
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/'.
|
||||
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/``.
|
||||
|
||||
==================================================== =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
|
|
@ -206,7 +204,7 @@ Setting name (default value) What does it do?
|
|||
|
||||
.. note::
|
||||
|
||||
When any of `*_SAVE_AS` is set to False, files will not be created.
|
||||
When any of the `*_SAVE_AS` settings is set to False, files will not be created.
|
||||
|
||||
Timezone
|
||||
--------
|
||||
|
|
@ -283,12 +281,12 @@ If you want to generate custom pages besides your blog entries, you can point
|
|||
any Jinja2 template file with a path pointing to the file and the destination
|
||||
path for the generated file.
|
||||
|
||||
For instance, if you have a blog with three static pages, for a list of books,
|
||||
your resume and a contact page, you could have::
|
||||
For instance, if you have a blog with three static pages — a list of books,
|
||||
your resume, and a contact page — you could have::
|
||||
|
||||
TEMPLATE_PAGES = {'src/books.html': 'dest/books.html',
|
||||
'src/resume.html': 'dest/resume.html',
|
||||
'src/contact.html': 'dest/contact.html'}
|
||||
'src/resume.html': 'dest/resume.html',
|
||||
'src/contact.html': 'dest/contact.html'}
|
||||
|
||||
Feed settings
|
||||
=============
|
||||
|
|
@ -326,8 +324,7 @@ Setting name (default value) What does it do?
|
|||
quantity is unrestricted by default.
|
||||
================================================ =====================================================
|
||||
|
||||
If you don't want to generate some or any of these feeds, set ``None`` to the
|
||||
variables above.
|
||||
If you don't want to generate some or any of these feeds, set the above variables to ``None``.
|
||||
|
||||
.. [2] %s is the name of the category.
|
||||
|
||||
|
|
@ -399,7 +396,7 @@ N matches `TAG_CLOUD_STEPS` -1).
|
|||
Translations
|
||||
============
|
||||
|
||||
Pelican offers a way to translate articles. See the Getting Started section for
|
||||
Pelican offers a way to translate articles. See the :doc:`Getting Started <getting_started>` section for
|
||||
more information.
|
||||
|
||||
===================================================== =====================================================
|
||||
|
|
@ -467,7 +464,7 @@ Following are example ways to specify your preferred theme::
|
|||
# Specify a customized theme, via absolute path
|
||||
THEME = "~/projects/mysite/themes/mycustomtheme"
|
||||
|
||||
The built-in `notmyidea` theme can make good use of the following settings. Feel
|
||||
The built-in ``notmyidea`` theme can make good use of the following settings. Feel
|
||||
free to use them in your themes as well.
|
||||
|
||||
======================= =======================================================
|
||||
|
|
@ -496,7 +493,7 @@ Setting name What does it do ?
|
|||
if you want this button to appear.
|
||||
======================= =======================================================
|
||||
|
||||
In addition, you can use the "wide" version of the `notmyidea` theme by
|
||||
In addition, you can use the "wide" version of the ``notmyidea`` theme by
|
||||
adding the following to your configuration::
|
||||
|
||||
CSS_FILE = "wide.css"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue