diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 823e0f97..eb5a2201 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -155,6 +155,6 @@ Publishing drafts ----------------- 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 -available under the `drafts` folder, and not be listed under the index page nor +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 any category page. diff --git a/docs/settings.rst b/docs/settings.rst index 971c55dc..567039e1 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1,10 +1,7 @@ Settings ######## -Specifying the settings -======================= - -Pelican is configurable thanks to a configuration file, that you can pass to +Pelican is configurable thanks to a configuration file you can pass to the command line:: $ 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 processed. -Here are the available settings. Please note that all the settings you put in -this file will be passed to the templates as well. +The settings you define in the configuration file will be passed to the +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) -`CATEGORY_FEED` ('feeds/%s.atom.xml'[1]_) Where to put the atom categories feeds. -`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 +`SITENAME` (``'A Pelican Blog'``) Your site name `DATE_FORMATS` (``{}``) If you do manage multiple languages, you can set the date formatting here. `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_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 template. Templates can follow or not this settings. `FALLBACK_ON_FS_DATE` (``True``) If True, pelican will use the file system dates infos (mtime) if it can't get 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. -`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. -`LOCALE` (''[2]_) Change the locale. +`LOCALE` (''[1]_) Change the locale. `MARKUP` (``('rst', 'md')``) A list of available markup languages you want to use. For the moment, only available values are `rst` and `md`. @@ -64,97 +50,129 @@ Setting name (default value) what does it do? `rst2pdf`. `RELATIVE_URL` (``True``) Defines if pelican should use relative urls or 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 not a way to tell pelican to use relative urls or static ones. You should rather use the `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 on the output path "static". By default, pelican will copy the 'images' folder to the 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 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:: + + + +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 complete static path to a theme folder, or chosen between the list of default themes (see below) -`TRANSLATION_FEED` ('feeds/all-%s.atom.xml'[3]_) Where to put the RSS feed for translations. -`WITH_PAGINATION` (``False``) Activate pagination. +`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. +`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&blog=(.*)&.*') - 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: * notmyidea @@ -192,3 +210,62 @@ In addition, you can use the "wide" version of the `notmyidea` theme, by adding that in your configuration:: 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&blog=(.*)&.*') + 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). +================================================ ===================================================== +