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

merge with master

Browse source
This commit is contained in:
Alexis Métaireau 2012-10-25 14:54:19 +02:00
commit 0ebba1c4ab
57 changed files with 1056 additions and 382 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/contribute.rst
View file

@ -23,7 +23,7 @@ different projects.
To create a virtual environment, use the following syntax::
$ mkvirtualenv pelican
$ mkvirtualenv pelican
To clone the Pelican source::
@ -65,5 +65,5 @@ Try to respect what is described in the `PEP8 specification
<http://www.python.org/dev/peps/pep-0008/>`_ when providing patches. This can be
eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
particular will give you some useful hints about ways in which the
particular will give you some useful hints about ways in which the
code/formatting can be improved.

8
docs/faq.rst
View file

@ -26,7 +26,7 @@ suggestions or problems you might have via IRC or the issue tracker.
If you want to contribute, please fork `the git repository
<https://github.com/getpelican/pelican/>`_, create a new feature branch, make
your changes, and issue a pull request. Someone will review your changes as soon
as possible. Please refer to the :doc:`How to Contribute <contribute>` section
as possible. Please refer to the :doc:`How to Contribute <contribute>` section
for more details.
You can also contribute by creating themes and improving the documentation.
@ -43,7 +43,7 @@ I'm creating my own theme. How do I use Pygments for syntax highlighting?
Pygments adds some classes to the generated content. These classes are used by
themes to style code syntax highlighting via CSS. Specifically, you can
customize the appearance of your syntax highlighting via the ``.codehilite pre``
customize the appearance of your syntax highlighting via the ``.codehilite pre``
class in your theme's CSS file. To see how various styles can be used to render
Django code, for example, you can use the demo `on the project website
<http://pygments.org/demo/15101/>`_.
@ -105,7 +105,7 @@ I'm getting a warning about feeds generated without SITEURL being set properly
In order to properly generate all URLs properly in Pelican you will need to set
``SITEURL`` to the full path of your blog. When using ``make html`` and the
default Makefile provided by the `pelican-quickstart` bootstrap script to test
build your site, it's normal to see this warning since ``SITEURL`` is
build your site, it's normal to see this warning since ``SITEURL`` is
deliberately left undefined. If configured properly no other ``make`` commands
should result in this warning.
@ -124,5 +124,5 @@ setting names). Here is an exact list of the renamed setting names::
Older 2.x themes that referenced the old setting names may not link properly.
In order to rectify this, please update your theme for compatibility with 3.0+
by changing the relevant values in your template files. For an example of
by changing the relevant values in your template files. For an example of
complete feed headers and usage please check out the ``simple`` theme.

13
docs/fr/configuration.rst
View file

@ -77,8 +77,11 @@ Traductions
DEFAULT_LANG :
Le langage par défaut à utiliser. «*en*» par défaut ;
TRANSLATION_FEED :
Chemin du flux pour les traductions.
TRANSLATION_FEED_ATOM :
Chemin du flux Atom pour les traductions.
TRANSLATION_FEED_RSS :
Chemin du flux RSS pour les traductions.
Thèmes
@ -155,7 +158,5 @@ SITEURL :
STATIC_PATHS :
Les chemins statiques que vous voulez avoir accès sur le chemin de sortie "statique" ;
MARKDOWN_EXTENSIONS :
Liste des extentions Markdown que vous souhaitez utiliser ;

18
docs/getting_started.rst
View file

@ -17,7 +17,7 @@ While the above is the simplest method, the recommended approach is to create
a virtual environment for Pelican via virtualenv_ and virtualenvwrapper_ before
installing Pelican. Assuming you've followed the virtualenvwrapper
`installation <http://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_
and `shell configuration
and `shell configuration
<http://virtualenvwrapper.readthedocs.org/en/latest/install.html#shell-startup-file>`_
steps, you can then open a new terminal session and create a new virtual
environment for Pelican::
@ -26,7 +26,7 @@ environment for Pelican::
Once the virtual environment has been created and activated, Pelican can be
be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
you have the project source, you can install Pelican using the distutils
you have the project source, you can install Pelican using the distutils
method::
$ cd path-to-Pelican-source
@ -69,6 +69,7 @@ Optionally:
* pygments, for syntax highlighting
* Markdown, for supporting Markdown as an input format
* Typogrify, for typographical enhancements
Kickstart a blog
================
@ -220,7 +221,7 @@ Pages
If you create a folder named ``pages``, all the files in it will be used to
generate static pages.
Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to
Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to
the menu.
If you want to exclude any pages from being linked to or listed in the menu
@ -230,7 +231,7 @@ things like making error pages that fit the generated theme of your site.
Importing an existing blog
--------------------------
It is possible to import your blog from Dotclear, WordPress, and RSS feeds using
It is possible to import your blog from Dotclear, WordPress, and RSS feeds using
a simple script. See :ref:`import`.
Translations
@ -288,14 +289,15 @@ For RestructuredText, use the code-block directive::
<indented code block goes here>
For Markdown, include the language identifier just above code blocks::
For Markdown, include the language identifier just above the code block,
indenting both the identifier and code::
A block of text.
:::identifier
<code goes here>
(indent both the identifier and code)
The specified identifier (e.g. ``python``, ``ruby``) should be one that
The specified identifier (e.g. ``python``, ``ruby``) should be one that
appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
Publishing drafts

2
docs/importer.rst
View file

@ -31,7 +31,7 @@ BeatifulSoup can be installed like any other Python package::
$ pip install BeautifulSoup
For pandoc, install a package for your operating system from the
For pandoc, install a package for your operating system from the
`pandoc site <http://johnmacfarlane.net/pandoc/installing.html>`_.

4
docs/index.rst
View file

@ -3,7 +3,7 @@ Pelican
Pelican is a static site generator, written in Python_.
* Write your weblog entries directly with your editor of choice (vim!)
* Write your weblog entries directly with your editor of choice (vim!)
in reStructuredText_ or Markdown_
* Includes a simple CLI tool to (re)generate the weblog
* Easy to interface with DVCSes and web hooks
@ -79,4 +79,4 @@ A French version of the documentation is available at :doc:`fr/index`.
.. _`Pelican documentation`: http://docs.getpelican.com/latest/
.. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
.. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4
.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4

4
docs/internals.rst
View file

@ -52,7 +52,7 @@ Take a look at the Markdown reader::
text = open(filename)
md = Markdown(extensions = ['meta', 'codehilite'])
content = md.convert(text)
metadata = {}
for name, value in md.Meta.items():
if name in _METADATA_FIELDS:
@ -81,7 +81,7 @@ both; only the existing ones will be called.
context is shared between all generators, and will be passed to the
templates. For instance, the ``PageGenerator`` ``generate_context`` method
finds all the pages, transforms them into objects, and populates the context
with them. Be careful *not* to output anything using this context at this
with them. Be careful *not* to output anything using this context at this
stage, as it is likely to change by the effect of other generators.
* ``generate_output`` is then called. And guess what is it made for? Oh,

10
docs/pelican-themes.rst
View file

@ -64,7 +64,7 @@ In this example, we can see there are three themes available: ``notmyidea``, ``s
Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get more verbose output, like this:
.. code-block:: console
$ pelican-themes -v -l
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
@ -118,7 +118,7 @@ Creating symbolic links
To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option:
.. code-block:: console
# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
In this example, the ``two-column`` theme is now symbolically linked to the Pelican themes path, so we can use it, but we can also modify it without having to reinstall it after each modification.
@ -130,11 +130,11 @@ This is useful for theme development:
$ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ firefox /tmp/out/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-coumn/static/img/bg.png
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html
$ pelican ~/Blog/content -o /tmp/out -t two-column
@ -152,7 +152,7 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
--symlink ~/Dev/Python/pelican-themes/two-column \
--verbose
In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr``
In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr``

196
docs/plugins.rst
View file

@ -16,7 +16,7 @@ To load plugins, you have to specify them in your settings file. You have two
ways to do so.
Either by specifying strings with the path to the callables::
PLUGINS = ['pelican.plugins.gravatar',]
PLUGINS = ['pelican.plugins.gravatar',]
Or by importing them and adding them to the list::
@ -48,35 +48,71 @@ which you map the signals to your plugin logic. Let's take a simple example::
signals.initialized.connect(test)
List of signals
===============
Here is the list of currently implemented signals:
========================= ============================ =========================================
Signal Arguments Description
========================= ============================ =========================================
initialized pelican object
article_generate_context article_generator, metadata
article_generator_init article_generator invoked in the ArticlesGenerator.__init__
pages_generate_context pages_generator, metadata
pages_generator_init pages_generator invoked in the PagesGenerator.__init__
========================= ============================ =========================================
============================= ============================ ===========================================================================
Signal Arguments Description
============================= ============================ ===========================================================================
initialized pelican object
finalized pelican object invoked after all the generators are executed and just before pelican exits
usefull for custom post processing actions, such as:
- minifying js/css assets.
- notify/ping search engines with an updated sitemap.
article_generate_context article_generator, metadata
article_generator_init article_generator invoked in the ArticlesGenerator.__init__
article_generator_finalized article_generator invoked at the end of ArticlesGenerator.generate_context
get_generators generators invoked in Pelican.get_generator_classes,
can return a Generator, or several
generator in a tuple or in a list.
pages_generate_context pages_generator, metadata
pages_generator_init pages_generator invoked in the PagesGenerator.__init__
============================= ============================ ===========================================================================
The list is currently small, don't hesitate to add signals and make a pull
request if you need them!
.. note::
The signal ``content_object_init`` can send different type of object as
argument. If you want to register only one type of object then you will
need to specify the sender when you are connecting to the signal.
::
from pelican import signals
from pelican import contents
def test(sender, instance):
print "%s : %s content initialized !!" % (sender, instance)
def register():
signals.content_object_init.connect(test, sender=contents.Article)
List of plugins
===============
Not all the list are described here, but a few of them have been extracted from
the Pelican core and provided in ``pelican.plugins``. They are described here:
The following plugins are currently included with Pelican under ``pelican.plugins``:
Tag cloud
---------
* `GitHub activity`_
* `Global license`_
* `Gravatar`_
* `HTML tags for reStructuredText`_
* `Related posts`_
* `Sitemap`_
Translation
-----------
Ideas for plugins that haven't been written yet:
* Tag cloud
* Translation
Plugin descriptions
===================
GitHub activity
---------------
@ -108,3 +144,131 @@ variable, as in the example::
``github_activity`` is a list of lists. The first element is the title
and the second element is the raw HTML from GitHub.
Global license
--------------
This plugin allows you to define a LICENSE setting and adds the contents of that
license variable to the article's context, making that variable available to use
from within your theme's templates.
Gravatar
--------
This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
makes the variable available within the article's context. You can add
AUTHOR_EMAIL to your settings file to define the default author's email
address. Obviously, that email address must be associated with a Gravatar
account.
Alternatively, you can provide an email address from within article metadata::
:email: john.doe@example.com
If the email address is defined via at least one of the two methods above,
the ``author_gravatar`` variable is added to the article's context.
HTML tags for reStructuredText
------------------------------
This plugin allows you to use HTML tags from within reST documents. Following
is a usage example, which is in this case a contact form::
.. html::
<form method="GET" action="mailto:some email">
<p>
<input type="text" placeholder="Subject" name="subject">
<br />
<textarea name="body" placeholder="Message">
</textarea>
<br />
<input type="reset"><input type="submit">
</p>
</form>
Related posts
-------------
This plugin adds the ``related_posts`` variable to the article's context.
To enable, add the following to your settings file::
from pelican.plugins import related_posts
PLUGINS = [related_posts]
You can then use the ``article.related_posts`` variable in your templates.
For example::
{% if article.related_posts %}
<ul>
{% for related_post in article.related_posts %}
<li>{{ related_post }}</li>
{% endfor %}
</ul>
{% endif %}
Sitemap
-------
The sitemap plugin generates plain-text or XML sitemaps. You can use the
``SITEMAP`` variable in your settings file to configure the behavior of the
plugin.
The ``SITEMAP`` variable must be a Python dictionary, it can contain three keys:
- ``format``, which sets the output format of the plugin (``xml`` or ``txt``)
- ``priorities``, which is a dictionary with three keys:
- ``articles``, the priority for the URLs of the articles and their
translations
- ``pages``, the priority for the URLs of the static pages
- ``indexes``, the priority for the URLs of the index pages, such as tags,
author pages, categories indexes, archives, etc...
All the values of this dictionary must be decimal numbers between ``0`` and ``1``.
- ``changefreqs``, which is a dictionary with three items:
- ``articles``, the update frequency of the articles
- ``pages``, the update frequency of the pages
- ``indexes``, the update frequency of the index pages
Valid frequency values are ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``,
``yearly`` and ``never``.
If a key is missing or a value is incorrect, it will be replaced with the
default value.
The sitemap is saved in ``<output_path>/sitemap.<format>``.
.. note::
``priorities`` and ``changefreqs`` are informations for search engines.
They are only used in the XML sitemaps.
For more information: <http://www.sitemaps.org/protocol.html#xmlTagDefinitions>
**Example**
Here is an example configuration (it's also the default settings):
.. code-block:: python
PLUGINS=['pelican.plugins.sitemap',]
SITEMAP = {
'format': 'xml',
'priorities': {
'articles': 0.5,
'indexes': 0.5,
'pages': 0.5
},
'changefreqs': {
'articles': 'monthly',
'indexes': 'daily',
'pages': 'monthly'
}
}

4
docs/report.rst
View file

@ -4,7 +4,7 @@ Some history about Pelican
.. warning::
This page comes from a report the original author (Alexis Métaireau) wrote
right after writing Pelican, in December 2010. The information may not be
right after writing Pelican, in December 2010. The information may not be
up-to-date.
Pelican is a simple static blog generator. It parses markup files
@ -113,7 +113,7 @@ concepts. Here is what happens when calling the ``generate_context``
method:
* Read the folder “path”, looking for restructured text files, load
each of them, and construct a content object (``Article``) with it. To do so,
each of them, and construct a content object (``Article``) with it. To do so,
use ``Reader`` objects.
* Update the ``context`` with all those articles.

211
docs/settings.rst
View file

@ -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
================

36
docs/themes.rst
View file

@ -35,7 +35,7 @@ To make your own theme, you must follow the following structure::
* `templates` contains all the templates that will be used to generate the content.
I've just put the mandatory templates here; you can define your own if it helps
you keep things organized while creating your theme.
Templates and variables
=======================
@ -44,7 +44,7 @@ This document describes which templates should exist in a theme, and which
variables will be passed to each template at generation time.
All templates will receive the variables defined in your settings file, if they
are in all-caps. You can access them directly.
are in all-caps. You can access them directly.
Common variables
----------------
@ -55,14 +55,14 @@ All of these settings will be available to all templates.
Variable Description
============= ===================================================
articles The list of articles, ordered descending by date
All the elements are `Article` objects, so you can
All the elements are `Article` objects, so you can
access their attributes (e.g. title, summary, author
etc.)
dates The same list of articles, but ordered by date,
ascending
tags A key-value dict containing the tags (the keys) and
the list of respective articles (the values)
categories A key-value dict containing the categories (keys)
categories A key-value dict containing the categories (keys)
and the list of respective articles (values)
pages The list of pages
============= ===================================================
@ -92,8 +92,8 @@ author.html
This template will be processed for each of the existing authors, with
output generated at output/author/`author_name`.html.
If pagination is active, subsequent pages will reside at
output/author/`author_name``n`.html.
If pagination is active, subsequent pages will reside as defined by setting
AUTHOR_SAVE_AS (`Default:` output/author/`author_name'n'`.html).
=================== ===================================================
Variable Description
@ -108,8 +108,8 @@ dates_paginator A paginator object for the article list, ordered by
date, ascending.
dates_page The current page of articles, ordered by date,
ascending.
page_name 'author/`author_name`' -- useful for pagination
links
page_name AUTHOR_URL where everything after `{slug}` is
removed -- useful for pagination links
=================== ===================================================
category.html
@ -118,8 +118,8 @@ category.html
This template will be processed for each of the existing categories, with
output generated at output/category/`category_name`.html.
If pagination is active, subsequent pages will reside at
output/category/`category_name``n`.html.
If pagination is active, subsequent pages will reside as defined by setting
CATEGORY_SAVE_AS (`Default:` output/category/`category_name'n'`.html).
=================== ===================================================
Variable Description
@ -134,8 +134,8 @@ dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
page_name 'category/`category_name`' -- useful for pagination
links
page_name CATEGORY_URL where everything after `{slug}` is
removed -- useful for pagination links
=================== ===================================================
article.html
@ -170,8 +170,8 @@ tag.html
This template will be processed for each tag, with corresponding .html files
saved as output/tag/`tag_name`.html.
If pagination is active, subsequent pages will reside at
output/tag/`tag_name``n`.html.
If pagination is active, subsequent pages will reside as defined in setting
TAG_SAVE_AS (`Default:` output/tag/`tag_name'n'`.html).
=================== ===================================================
Variable Description
@ -182,11 +182,12 @@ dates Articles related to this tag, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
dates_paginator A paginator object for the list of articles,
dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
page_name 'tag/`tag_name`' -- useful for pagination links
page_name TAG_URL where everything after `{slug}` is removed
-- useful for pagination links
=================== ===================================================
Feeds
@ -202,7 +203,8 @@ Here is a complete list of the feed variables::
CATEGORY_FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS
Inheritance

6
docs/tips.rst
View file

@ -12,11 +12,11 @@ file generator, we can take advantage of this.
User Pages
----------
GitHub allows you to create user pages in the form of ``username.github.com``.
GitHub allows you to create user pages in the form of ``username.github.com``.
Whatever is created in the master branch will be published. For this purpose,
just the output generated by Pelican needs to pushed to GitHub.
So given a repository containing your articles, just run Pelican over the posts
So given a repository containing your articles, just run Pelican over the posts
and deploy the master branch to GitHub::
$ pelican -s pelican.conf.py ./path/to/posts -o /path/to/output
@ -35,7 +35,7 @@ really easy, which can be installed via::
$ pip install ghp-import
Then, given a repository containing your articles, you would simply run
Then, given a repository containing your articles, you would simply run
Pelican and upload the output to GitHub::
$ pelican -s pelican.conf.py .