mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
merge with master
This commit is contained in:
Alexis Métaireau
commit
0ebba1c4ab
57 changed files with 1056 additions and 382 deletions
|
|
@ -16,6 +16,9 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -43,9 +46,12 @@ Setting name (default value) What doe
|
|||
If tuple object, it will instead generate the
|
||||
default datetime object by passing the tuple to
|
||||
the datetime.datetime constructor.
|
||||
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
|
||||
`DELETE_OUTPUT_DIRECTORY` (``False``) Delete the content of the output directory before
|
||||
generating new files.
|
||||
`FILES_TO_COPY` (``()``) A list of files to copy from the source (inside the content
|
||||
directory) to the destination (inside the output directory).
|
||||
For example: ``(('extra/robots.txt', 'robots.txt'),)``.
|
||||
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
|
||||
`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
|
||||
|
|
@ -58,14 +64,20 @@ Setting name (default value) What doe
|
|||
Python-Markdown documentation for a complete list of
|
||||
supported extensions.
|
||||
`OUTPUT_PATH` (``'output/'``) Where to output the generated files.
|
||||
`PATH` (``None``) Path to look at for input files.
|
||||
`PAGE_DIR` (``'pages'``) Directory to look at for pages.
|
||||
`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.
|
||||
`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`.
|
||||
`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
|
||||
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` (``True``) Defines whether Pelican should use document-relative URLs or
|
||||
not. If set to ``False``, Pelican will use the SITEURL
|
||||
setting to construct absolute URLs.
|
||||
|
|
@ -100,7 +112,12 @@ Setting name (default value) What doe
|
|||
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 look for the templates.
|
||||
Can be used to separate templates from the theme.
|
||||
Example: projects, resume, profile ...
|
||||
This templates need to use ``DIRECT_TEMPLATES`` setting
|
||||
|
||||
`MARKDOWN_EXTENSIONS` (``['toc',]``) A list of any Markdown extensions you want to use.
|
||||
===================================================================== =====================================================================
|
||||
|
||||
.. [#] Default is the system locale.
|
||||
|
|
@ -144,37 +161,37 @@ Also, you can use other file metadata attributes as well:
|
|||
|
||||
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'
|
||||
* 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/'.
|
||||
|
||||
================================================ =====================================================
|
||||
Setting name (default value) what does it do?
|
||||
================================================ =====================================================
|
||||
`ARTICLE_URL` ('{slug}.html') The URL to refer to an ARTICLE.
|
||||
`ARTICLE_SAVE_AS` ('{slug}.html') The place where we will save an article.
|
||||
`ARTICLE_LANG_URL` ('{slug}-{lang}.html') The URL to refer to an ARTICLE which doesn't use the
|
||||
default language.
|
||||
`ARTICLE_LANG_SAVE_AS` ('{slug}-{lang}.html' The place where we will save an article which
|
||||
doesn't use the default language.
|
||||
`PAGE_URL` ('pages/{slug}.html') The URL we will use to link to a page.
|
||||
`PAGE_SAVE_AS` ('pages/{slug}.html') The location we will save the page.
|
||||
`PAGE_LANG_URL` ('pages/{slug}-{lang}.html') The URL we will use to link to a page which doesn't
|
||||
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.
|
||||
`AUTHOR_URL` ('author/{name}.html') The URL to use for an author.
|
||||
`AUTHOR_SAVE_AS` ('author/{name}.html') The location to save an author.
|
||||
`CATEGORY_URL` ('category/{name}.html') The URL to use for a category.
|
||||
`CATEGORY_SAVE_AS` ('category/{name}.html') The location to save a category.
|
||||
`TAG_URL` ('tag/{name}.html') The URL to use for a tag.
|
||||
`TAG_SAVE_AS` ('tag/{name}.html') The location to save the tag page.
|
||||
`<DIRECT_TEMPLATE_NAME>_SAVE_AS` The location to save content generated from direct
|
||||
templates. Where <DIRECT_TEMPLATE_NAME> is the
|
||||
upper case template name.
|
||||
================================================ =====================================================
|
||||
==================================================== =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
==================================================== =====================================================
|
||||
`ARTICLE_URL` (``'{slug}.html'``) The URL to refer to an ARTICLE.
|
||||
`ARTICLE_SAVE_AS` (``'{slug}.html'``) The place where we will save an article.
|
||||
`ARTICLE_LANG_URL` (``'{slug}-{lang}.html'``) The URL to refer to an ARTICLE which doesn't use the
|
||||
default language.
|
||||
`ARTICLE_LANG_SAVE_AS` (``'{slug}-{lang}.html'``) The place where we will save an article which
|
||||
doesn't use the default language.
|
||||
`PAGE_URL` (``'pages/{slug}.html'``) The URL we will use to link to a page.
|
||||
`PAGE_SAVE_AS` (``'pages/{slug}.html'``) The location we will save the page.
|
||||
`PAGE_LANG_URL` (``'pages/{slug}-{lang}.html'``) The URL we will use to link to a page which doesn't
|
||||
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.
|
||||
`AUTHOR_URL` (``'author/{name}.html'``) The URL to use for an author.
|
||||
`AUTHOR_SAVE_AS` (``'author/{name}.html'``) The location to save an author.
|
||||
`CATEGORY_URL` (``'category/{name}.html'``) The URL to use for a category.
|
||||
`CATEGORY_SAVE_AS` (``'category/{name}.html'``) The location to save a category.
|
||||
`TAG_URL` (``'tag/{name}.html'``) The URL to use for a tag.
|
||||
`TAG_SAVE_AS` (``'tag/{name}.html'``) The location to save the tag page.
|
||||
`<DIRECT_TEMPLATE_NAME>_SAVE_AS` The location to save content generated from direct
|
||||
templates. Where <DIRECT_TEMPLATE_NAME> is the
|
||||
upper case template name.
|
||||
==================================================== =====================================================
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -197,14 +214,14 @@ Have a look at `the wikipedia page`_ to get a list of valid timezone values.
|
|||
Date format and locale
|
||||
----------------------
|
||||
|
||||
If no DATE_FORMAT is set, fall back to DEFAULT_DATE_FORMAT. If you need to
|
||||
If no DATE_FORMATS is set, fall back to DEFAULT_DATE_FORMAT. If you need to
|
||||
maintain multiple languages with different date formats, you can set this dict
|
||||
using language name (``lang`` in your posts) as key. Regarding available format
|
||||
codes, see `strftime document of python`_ :
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
DATE_FORMAT = {
|
||||
DATE_FORMATS = {
|
||||
'en': '%a, %d %b %Y',
|
||||
'jp': '%Y-%m-%d(%a)',
|
||||
}
|
||||
|
|
@ -223,13 +240,13 @@ above:
|
|||
|
||||
.. parsed-literal::
|
||||
# On Unix/Linux
|
||||
DATE_FORMAT = {
|
||||
DATE_FORMATS = {
|
||||
'en': ('en_US','%a, %d %b %Y'),
|
||||
'jp': ('ja_JP','%Y-%m-%d(%a)'),
|
||||
}
|
||||
|
||||
# On Windows
|
||||
DATE_FORMAT = {
|
||||
DATE_FORMATS = {
|
||||
'en': ('usa','%a, %d %b %Y'),
|
||||
'jp': ('jpn','%Y-%m-%d(%a)'),
|
||||
}
|
||||
|
|
@ -313,10 +330,10 @@ You can use the following settings to configure the pagination.
|
|||
================================================ =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
================================================ =====================================================
|
||||
`DEFAULT_ORPHANS` (0) The minimum number of articles allowed on the
|
||||
`DEFAULT_ORPHANS` (``0``) The minimum number of articles allowed on the
|
||||
last page. Use this when you don't want to
|
||||
have a last page with very few articles.
|
||||
`DEFAULT_PAGINATION` (False) The maximum number of articles to include on a
|
||||
`DEFAULT_PAGINATION` (``False``) The maximum number of articles to include on a
|
||||
page, not including orphans. False to disable
|
||||
pagination.
|
||||
================================================ =====================================================
|
||||
|
|
@ -330,9 +347,9 @@ following settings.
|
|||
================================================ =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
================================================ =====================================================
|
||||
`TAG_CLOUD_STEPS` (4) Count of different font sizes in the tag
|
||||
`TAG_CLOUD_STEPS` (``4``) Count of different font sizes in the tag
|
||||
cloud.
|
||||
`TAG_CLOUD_MAX_ITEMS` (100) Maximum number of tags in the cloud.
|
||||
`TAG_CLOUD_MAX_ITEMS` (``100``) Maximum number of tags in the cloud.
|
||||
================================================ =====================================================
|
||||
|
||||
The default theme does not support tag clouds, but it is pretty easy to add::
|
||||
|
|
@ -352,12 +369,13 @@ Translations
|
|||
Pelican offers a way to translate articles. See the Getting Started section for
|
||||
more information.
|
||||
|
||||
================================================ =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
================================================ =====================================================
|
||||
`DEFAULT_LANG` (``'en'``) The default language to use.
|
||||
`TRANSLATION_FEED` ('feeds/all-%s.atom.xml'[3]_) Where to put the feed for translations.
|
||||
================================================ =====================================================
|
||||
===================================================== =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
===================================================== =====================================================
|
||||
`DEFAULT_LANG` (``'en'``) The default language to use.
|
||||
`TRANSLATION_FEED_ATOM` ('feeds/all-%s.atom.xml'[3]_) Where to put the Atom feed for translations.
|
||||
`TRANSLATION_FEED_RSS` (``None``, i.e. no RSS) Where to put the RSS feed for translations.
|
||||
===================================================== =====================================================
|
||||
|
||||
.. [3] %s is the language
|
||||
|
||||
|
|
@ -373,19 +391,19 @@ Setting name (default value) What does it do?
|
|||
alphabetical order; default lists alphabetically.)
|
||||
================================================ =====================================================
|
||||
|
||||
Theming
|
||||
=======
|
||||
Themes
|
||||
======
|
||||
|
||||
Theming is addressed in a dedicated section (see :ref:`theming-pelican`).
|
||||
However, here are the settings that are related to theming.
|
||||
Creating Pelican themes is addressed in a dedicated section (see :ref:`theming-pelican`).
|
||||
However, here are the settings that are related to themes.
|
||||
|
||||
================================================ =====================================================
|
||||
Setting name (default value) What does it do?
|
||||
================================================ =====================================================
|
||||
`THEME` Theme to use to produce the output. Can be the
|
||||
complete static path to a theme folder, or
|
||||
chosen between the list of default themes (see
|
||||
below)
|
||||
`THEME` Theme to use to produce the output. Can be a relative
|
||||
or absolute path to a theme folder, or the name of a
|
||||
default theme or a theme installed via
|
||||
``pelican-themes`` (see below).
|
||||
`THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default
|
||||
value is `static`, but if your theme has
|
||||
other static paths, you can put them here.
|
||||
|
|
@ -393,22 +411,32 @@ Setting name (default value) What does it do?
|
|||
`WEBASSETS` (``False``) Asset management with `webassets` (see below)
|
||||
================================================ =====================================================
|
||||
|
||||
By default, two themes are available. You can specify them using the `-t` option:
|
||||
|
||||
By default, two themes are available. You can specify them using the `THEME` setting or by passing the
|
||||
``-t`` option to the ``pelican`` command:
|
||||
|
||||
* notmyidea
|
||||
* simple (a synonym for "full text" :)
|
||||
|
||||
You can define your own theme too, and specify its placement in the same
|
||||
manner. (Be sure to specify the full absolute path to it.)
|
||||
|
||||
Here is :doc:`a guide on how to create your theme <themes>`
|
||||
|
||||
You can find a list of themes at http://github.com/getpelican/pelican-themes.
|
||||
* simple (a synonym for "plain text" :)
|
||||
|
||||
There are a number of other themes available at http://github.com/getpelican/pelican-themes.
|
||||
Pelican comes with :doc:`pelican-themes`, a small script for managing themes.
|
||||
|
||||
The `notmyidea` theme can make good use of the following settings. I recommend
|
||||
using them in your themes as well.
|
||||
You can define your own theme, either by starting from scratch or by duplicating
|
||||
and modifying a pre-existing theme. Here is :doc:`a guide on how to create your theme <themes>`.
|
||||
|
||||
Following are example ways to specify your preferred theme::
|
||||
|
||||
# Specify name of a built-in theme
|
||||
THEME = "notmyidea"
|
||||
# Specify name of a theme installed via the pelican-themes tool
|
||||
THEME = "chunk"
|
||||
# Specify a customized theme, via path relative to the settings file
|
||||
THEME = "themes/mycustomtheme"
|
||||
# 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
|
||||
free to use them in your themes as well.
|
||||
|
||||
======================= =======================================================
|
||||
Setting name What does it do ?
|
||||
|
|
@ -444,26 +472,27 @@ adding the following to your configuration::
|
|||
Asset management
|
||||
----------------
|
||||
|
||||
The `WEBASSETS` setting allows to use the `webassets`_ module to manage assets
|
||||
(css, js). The module must first be installed::
|
||||
The `WEBASSETS` setting allows you to use the `webassets`_ module to manage
|
||||
assets such as CSS and JS files. The module must first be installed::
|
||||
|
||||
pip install webassets
|
||||
|
||||
`webassets` allows to concatenate your assets and to use almost all of the
|
||||
hype tools of the moment (see the `documentation`_):
|
||||
The `webassets` module allows you to perform a number of useful asset management
|
||||
functions, including:
|
||||
|
||||
* css minifier (`cssmin`, `yuicompressor`, ...)
|
||||
* css compiler (`less`, `sass`, ...)
|
||||
* js minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
|
||||
* CSS minifier (`cssmin`, `yuicompressor`, ...)
|
||||
* CSS compiler (`less`, `sass`, ...)
|
||||
* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
|
||||
|
||||
Others filters include gzip compression, integration of images in css with
|
||||
`datauri` and more. Webassets also append a version identifier to your asset
|
||||
url to convince browsers to download new versions of your assets when you use
|
||||
far future expires headers.
|
||||
Others filters include gzip compression, integration of images in CSS via data
|
||||
URIs, and more. `webassets` can also append a version identifier to your asset
|
||||
URL to convince browsers to download new versions of your assets when you use
|
||||
far-future expires headers. Please refer to the `webassets documentation`_ for
|
||||
more information.
|
||||
|
||||
When using it with Pelican, `webassets` is configured to process assets in the
|
||||
``OUTPUT_PATH/theme`` directory. You can use it in your templates with a
|
||||
template tag, for example:
|
||||
When using with Pelican, `webassets` is configured to process assets in the
|
||||
``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by
|
||||
including one or more template tags. For example...
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
|
|
@ -471,43 +500,43 @@ template tag, for example:
|
|||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
will produce a minified css file with the version identifier:
|
||||
... will produce a minified css file with a version identifier:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
|
||||
|
||||
The filters can be combined, for example to use the `sass` compiler and minify
|
||||
the output::
|
||||
These filters can be combined. Here is an example that uses the SASS compiler
|
||||
and minifies the output:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
Another example for javascript:
|
||||
Another example for Javascript:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="uglifyjs,gzip", output="js/packed.js", "js/jquery.js", "js/base.js", "js/widgets.js" %}
|
||||
<script src="{{ ASSETS_URL }}"></script>
|
||||
<script src="{{ ASSET_URL }}"></script>
|
||||
{% endassets %}
|
||||
|
||||
will produce a minified and gzipped js file:
|
||||
The above will produce a minified and gzipped JS file:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
|
||||
|
||||
Pelican's debug mode is propagated to webassets to disable asset packaging,
|
||||
Pelican's debug mode is propagated to `webassets` to disable asset packaging
|
||||
and instead work with the uncompressed assets. However, this also means that
|
||||
the `less` and `sass` files are not compiled, this should be fixed in a future
|
||||
version of webassets (cf. the related `bug report
|
||||
the LESS and SASS files are not compiled. This should be fixed in a future
|
||||
version of `webassets` (cf. the related `bug report
|
||||
<https://github.com/getpelican/pelican/issues/481>`_).
|
||||
|
||||
.. _webassets: https://github.com/miracle2k/webassets
|
||||
.. _documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
|
||||
.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
|
||||
|
||||
Example settings
|
||||
================
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue