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

Split the settings into different sections.

Browse source 
Fixes #112
This commit is contained in:
Alexis Metaireau 2011-05-08 16:15:43 +01:00
commit aab3ee78dc
2 changed files with 166 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/getting_started.rst
View file

@ -155,6 +155,6 @@ Publishing drafts
----------------- -----------------
If you want to publish an article as a draft, for friends to review it for If you want to publish an article as a draft, for friends to review it for
instance, you can add a `status: draft` to its metadata, it will then be instance, you can add a ``status: draft`` to its metadata, it will then be
available under the `drafts` folder, and not be listed under the index page nor available under the ``drafts`` folder, and not be listed under the index page nor
any category page. any category page.

275
docs/settings.rst
View file

@ -1,10 +1,7 @@
Settings Settings
######## ########
Specifying the settings Pelican is configurable thanks to a configuration file you can pass to
=======================
Pelican is configurable thanks to a configuration file, that you can pass to
the command line:: the command line::
$ pelican -s path/to/your/settingsfile.py path $ pelican -s path/to/your/settingsfile.py path
@ -16,44 +13,33 @@ example by looking at `/samples/pelican.conf.py
All the settings identifiers must be set in caps, otherwise they will not be All the settings identifiers must be set in caps, otherwise they will not be
processed. processed.
Here are the available settings. Please note that all the settings you put in The settings you define in the configuration file will be passed to the
this file will be passed to the templates as well. templates, it allows you to use them to add site-wide contents if you need.
Here is a list of settings for pelican, regarding the different features.
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)
`CATEGORY_FEED` ('feeds/%s.atom.xml'[1]_) Where to put the atom categories feeds. `SITENAME` (``'A Pelican Blog'``) Your site name
`CATEGORY_FEED_RSS` (``None``, i.e. no RSS) Where to put the categories rss feeds.
`CSS_FILE` (``'main.css'``) specify the CSS file you want to load
`DATE_FORMATS` (``{}``) If you do manage multiple languages, you can `DATE_FORMATS` (``{}``) If you do manage multiple languages, you can
set the date formatting here. set the date formatting here.
`DEFAULT_CATEGORY` (``'misc'``) The default category to fallback on. `DEFAULT_CATEGORY` (``'misc'``) The default category to fallback 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.
`DEFAULT_LANG` (``'en'``) The default language to use.
`DEFAULT_METADATA` (``()``) A list containing the default metadata for
each content (articles, pages, etc.)
`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` (5) The maximum number of articles to include on a
page, not including orphans.
`DISPLAY_PAGES_ON_MENU` (``True``) Display or not the pages on the menu of the `DISPLAY_PAGES_ON_MENU` (``True``) Display or not the pages on the menu of the
template. Templates can follow or not this template. Templates can follow or not this
settings. settings.
`FALLBACK_ON_FS_DATE` (``True``) If True, pelican will use the file system `FALLBACK_ON_FS_DATE` (``True``) If True, pelican will use the file system
dates infos (mtime) if it can't get dates infos (mtime) if it can't get
informations from the metadata informations from the metadata
`FEED` (``'feeds/all.atom.xml'``) relative url to output the atom feed.
`FEED_RSS` (``None``, i.e. no RSS) relative url to output the rss feed.
`FILES_TO_COPY` (``()``, no files) A list of tuples (source, destination) of files
to copy from the source directory to the
output path
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use. `JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
`DELETE_OUTPUT_DIRECTORY` (``False``) Delete the output directory instead of just updating all `DELETE_OUTPUT_DIRECTORY` (``False``) Delete the output directory and just
the generated files. the generated files.
`LOCALE` (''[2]_) Change the locale. `LOCALE` (''[1]_) Change the locale.
`MARKUP` (``('rst', 'md')``) A list of available markup languages you want `MARKUP` (``('rst', 'md')``) A list of available markup languages you want
to use. For the moment, only available values to use. For the moment, only available values
are `rst` and `md`. are `rst` and `md`.
@ -64,97 +50,129 @@ Setting name (default value) what does it do?
`rst2pdf`. `rst2pdf`.
`RELATIVE_URL` (``True``) Defines if pelican should use relative urls or `RELATIVE_URL` (``True``) Defines if pelican should use relative urls or
not. not.
`REVERSE_ARCHIVE_ORDER` (``False``) Reverse the archives order. (True makes it in
descending order: the newer first)
`REVERSE_CATEGORY_ORDER` (``False``) Reverse the category order. (True makes it in
descending order, default is alphabetically)
`SITEURL` base URL of your website. Note that this is `SITEURL` base URL of your website. Note that this is
not a way to tell pelican to use relative urls not a way to tell pelican to use relative urls
or static ones. You should rather use the or static ones. You should rather use the
`RELATIVE_URL` setting for such use. `RELATIVE_URL` setting for such use.
`SITENAME` (``'A Pelican Blog'``) Your site name
`SKRIBIT_TYPE` The type of skribit widget (TAB or WIDGET).
`SKRIBIT_TAB_COLOR` Tab color (#XXXXXX, default #333333).
`SKRIBIT_TAB_HORIZ` Tab Distance from Left (% or distance, default Null).
`SKRIBIT_TAB_VERT` Tab Distance from Top (% or distance, default 20%).
`SKRIBIT_TAB_PLACEMENT` Tab placement (Top, Bottom, Left or Right,
default LEFT).
`SKRIBIT_TAB_SITENAME` Tab identifier (See Skribit part below).
`SKRIBIT_WIDGET_ID` Widget identifier (See Skribit part below).
`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.
`THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default ================================================ =====================================================
values is `static`, but if your theme has
other static paths, you can put them here.
.. [1] Default is the system locale. Default is to delete the output directory.
Feed settings
=============
By default, pelican uses atom feeds. However, it is possible to use RSS feeds
instead, at your covenience.
Pelican generates category feeds as well as feeds for all your articles.
================================================ =====================================================
Setting name (default value) what does it do?
================================================ =====================================================
`CATEGORY_FEED` ('feeds/%s.atom.xml'[2]_) Where to put the atom categories feeds.
`CATEGORY_FEED_RSS` (``None``, i.e. no RSS) Where to put the categories rss feeds.
`FEED` (``'feeds/all.atom.xml'``) relative url to output the atom feed.
`FEED_RSS` (``None``, i.e. no RSS) relative url to output the rss feed.
================================================ =====================================================
.. [2] %s is the name of the category.
Pagination
==========
The default behaviour of pelican is to list all the articles titles alongside
with a short description of them on the index page. While it works pretty well
for little to medium blogs, it is convenient to have a way to paginate this.
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
last page. Use this when you don't want to
have a last page with very few articles.
`DEFAULT_PAGINATION` (5) The maximum number of articles to include on a
page, not including orphans.
`WITH_PAGINATION` (``False``) Activate pagination.
================================================ =====================================================
Tag cloud
=========
If you want to generate a tag cloud with all your tags, you can do so using the
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. cloud.
`TAG_CLOUD_MAX_ITEMS` (100) Maximum tags count in the cloud. `TAG_CLOUD_MAX_ITEMS` (100) Maximum tags count in the cloud.
================================================ =====================================================
The default theme does not support tag clouds, but it is pretty easy to add::
<ul>
{% for tag in tag_cloud %}
<li class="tag-{{ tag.1 }}"><a href="/tag/{{ tag.0 }}/">{{ tag.0 }}</a></li>
{% endfor %}
</ul>
You should then also define a CSS with the appropriate classes (tag-0 to tag-N, where
N matches `TAG_CLOUD_STEPS` -1.
Translations
============
Pelican offers a way to translate articles. See the section on getting started for
more information about that.
================================================ =====================================================
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 RSS feed for translations.
================================================ =====================================================
.. [3] %s is the language
Ordering contents
=================
================================================ =====================================================
Setting name (default value) what does it do?
================================================ =====================================================
`REVERSE_ARCHIVE_ORDER` (``False``) Reverse the archives order. (True makes it in
descending order: the newer first)
`REVERSE_CATEGORY_ORDER` (``False``) Reverse the category order. (True makes it in
descending order, default is alphabetically)
================================================ =====================================================
Theming
=======
Theming is addressed in a dedicated section (see :ref:`theming-pelican`).
However, here are the settings that are related to theming.
================================================ =====================================================
Setting name (default value) what does it do?
================================================ =====================================================
`THEME` theme to use to produce the output. can be the `THEME` theme to use to produce the output. can be the
complete static path to a theme folder, or complete static path to a theme folder, or
chosen between the list of default themes (see chosen between the list of default themes (see
below) below)
`TRANSLATION_FEED` ('feeds/all-%s.atom.xml'[3]_) Where to put the RSS feed for translations. `THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default
`WITH_PAGINATION` (``False``) Activate pagination. values is `static`, but if your theme has
other static paths, you can put them here.
`CSS_FILE` (``'main.css'``) specify the CSS file you want to load
================================================ ===================================================== ================================================ =====================================================
.. [1] %s is the name of the category.
.. [2] Default is the system locale. Default is to delete the output directory.
.. [3] %s is the language
Skribit
=======
Skribit has two ways to display suggestions : as a sidebar widget or as a
suggestions tab. You can choose one of the display by setting the SKRIBIT_TYPE
in your config.
Sidebar widget
--------------
The settings for sidebar widget is :
* SKRIBIT_WIDGET_ID : the identifier of your blog.
All the customizations are done in the skribit web interface.
To retrieve your identifier from the code snippet, you can use this python code::
import re
regex = re.compile('.*http://assets.skribit.com/javascripts/SkribitWidget.\
js\?renderTo=writeSkribitHere&amp;blog=(.*)&amp;.*')
snippet = '''SNIPPET CONTENT'''
snippet = snippet.replace('\n', '')
identifier = regex.match(snippet).groups()[0]
Suggestion tab
--------------
The setting for suggestion tab's customizations are :
* SKRIBIT_TAB_COLOR
* SKRIBIT_TAB_DISTANCE_HORIZ
* SKRIBIT_TAB_DISTANCE_VERT
* SKRIBIT_TAB_PLACEMENT
The identifier is :
* SKRIBIT_TAB_SITENAME : the identifier of your blog
To retrieve your sitename from the code snippet, you can use this python code::
import re
regex = re.compile('.*http://skribit.com/lightbox/(.*)\',.*')
snippet = '''SNIPPET CONTENT'''
snippet = snippet.replace('\n', '')
identifier = regex.match(snippet).groups()[0]
Themes
======
By default, two themes are availablee. You can specify them using the `-t` option: By default, two themes are availablee. You can specify them using the `-t` option:
* notmyidea * notmyidea
@ -192,3 +210,62 @@ In addition, you can use the "wide" version of the `notmyidea` theme, by
adding that in your configuration:: adding that in your configuration::
CSS_FILE = "wide.css" CSS_FILE = "wide.css"
Skribit
-------
Skribit has two ways to display suggestions : as a sidebar widget or as a
suggestions tab. You can choose one of the display by setting the SKRIBIT_TYPE
in your config.
* SKRIBIT_WIDGET_ID : the identifier of your blog.
All the customizations are done in the skribit web interface.
To retrieve your identifier from the code snippet, you can use this python code::
import re
regex = re.compile('.*http://assets.skribit.com/javascripts/SkribitWidget.\
js\?renderTo=writeSkribitHere&amp;blog=(.*)&amp;.*')
snippet = '''SNIPPET CONTENT'''
snippet = snippet.replace('\n', '')
identifier = regex.match(snippet).groups()[0]
Suggestion tab
--------------
The setting for suggestion tab's customizations are :
* SKRIBIT_TAB_COLOR
* SKRIBIT_TAB_DISTANCE_HORIZ
* SKRIBIT_TAB_DISTANCE_VERT
* SKRIBIT_TAB_PLACEMENT
The identifier is :
* SKRIBIT_TAB_SITENAME : the identifier of your blog
To retrieve your sitename from the code snippet, you can use this python code::
import re
regex = re.compile('.*http://skribit.com/lightbox/(.*)\',.*')
snippet = '''SNIPPET CONTENT'''
snippet = snippet.replace('\n', '')
identifier = regex.match(snippet).groups()[0]
Skribit settings
----------------
================================================ =====================================================
Setting name (default value) what does it do?
================================================ =====================================================
`SKRIBIT_TYPE` The type of skribit widget (TAB or WIDGET).
`SKRIBIT_TAB_COLOR` Tab color (#XXXXXX, default #333333).
`SKRIBIT_TAB_HORIZ` Tab Distance from Left (% or distance, default Null).
`SKRIBIT_TAB_VERT` Tab Distance from Top (% or distance, default 20%).
`SKRIBIT_TAB_PLACEMENT` Tab placement (Top, Bottom, Left or Right,
default LEFT).
`SKRIBIT_TAB_SITENAME` Tab identifier (See Skribit part below).
`SKRIBIT_WIDGET_ID` Widget identifier (See Skribit part below).
================================================ =====================================================