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 pull request #228 from justinmayer/master

Browse source 
Improved English documentation with enhanced clarity, grammar, and spelling
This commit is contained in:
Alexis Metaireau 2012-03-06 06:38:02 -08:00
commit 8997a08cd7
11 changed files with 429 additions and 403 deletions
Download patch file Download diff file Expand all files Collapse all files

45
README.rst
View file

@ -3,51 +3,54 @@ Pelican
Pelican is a simple weblog generator, written in `Python <http://www.python.org/>`_. Pelican is a simple weblog generator, written in `Python <http://www.python.org/>`_.
* Write your weblog entries directly with your editor of choice (vim!) and * Write your weblog entries directly with your editor of choice (vim!)
directly in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_, or `Markdown <http://daringfireball.net/projects/markdown/>`_. in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ or `Markdown <http://daringfireball.net/projects/markdown/>`_
* A simple cli-tool to (re)generate the weblog. * Includes a simple CLI tool to (re)generate the weblog
* Easy to interface with DVCSes and web hooks * Easy to interface with DVCSes and web hooks
* Completely static output, so easy to host anywhere ! * Completely static output is easy to host anywhere
Features Features
-------- --------
Pelican currently supports: Pelican currently supports:
* blog articles and pages * Blog articles and pages
* comments, via an external service (disqus). Please notice that while * Comments, via an external service (Disqus). (Please note that while
it's useful, it's an external service, and you'll not manage the useful, Disqus is an external service, and thus the comment data will be
comments by yourself. It could potentially eat your data. somewhat outside of your control and potentially subject to data loss.)
* theming support (themes are done using `jinja2 <http://jinjna.pocoo.org>`_) * Theming support (themes are created using `jinja2 <http://jinja.pocoo.org/>`_)
* PDF generation of the articles/pages (optional). * PDF generation of the articles/pages (optional)
* Translations * Publication of articles in multiple languages
* Syntactic recognition * Atom/RSS feeds
* Code syntax highlighting
* Import from WordPress, Dotclear, or RSS feeds
* Integration with external tools: Twitter, Google Analytics, etc. (optional)
Have a look to `the documentation <http://alexis.notmyidea.org/pelican/>`_ for Have a look at `the documentation <http://pelican.notmyidea.org/en/latest/>`_ for
more informations. more information.
Why the name "Pelican" ? Why the name "Pelican"?
------------------------ ------------------------
Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;) Heh, you didn't notice? "Pelican" is an anagram for "Calepin" ;)
Source code Source code
----------- -----------
You can access the source code via git on http://github.com/ametaireau/pelican/ You can access the source code via git at: https://github.com/ametaireau/pelican
If you feel hackish, have a look to the `pelican's internals explanations If you feel hackish, have a look at the `pelican's internals explanation
<http://alexis.notmyidea.org/pelican/internals.html>`_. <http://pelican.notmyidea.org/en/latest/internals.html>`_.
Feedback / Contact us Feedback / Contact us
===================== =====================
If you want to see new features in Pelican, dont hesitate to tell me, to clone If you want to see new features in Pelican, don't hesitate to tell me, to clone
the repository, etc. That's open source, dude! the repository, etc. That's open source, dude!
Contact me at "alexis at notmyidea dot org" for any request/feedback! You can Contact me at "alexis at notmyidea dot org" for any request/feedback! You can
also join the team at `#pelican on irc.freenode.org also join the team at `#pelican on irc.freenode.org
<irc://irc.freenode.net/pelican>`_ <irc://irc.freenode.net/pelican>`_
(or if you don't have any IRC client, using `the webchat (or if you don't have any IRC client, use `the webchat
<http://webchat.freenode.net/?channels=pelican&uio=d4>`_) <http://webchat.freenode.net/?channels=pelican&uio=d4>`_)
for quick feedback. for quick feedback.

36
docs/contribute.rst
View file

@ -1,28 +1,28 @@
How to contribute ? How to contribute?
################### ###################
There are many ways to contribute to pelican. You can enhance the There are many ways to contribute to Pelican. You can enhance the
documentation, add missing features, fix bugs or just report them. documentation, add missing features, and fix bugs (or just report them).
Don't hesitate to fork and make a pull request on github. Don't hesitate to fork and make a pull request on GitHub.
Set up the development environment Setting up the development environment
================================== ======================================
You're free to setup up the environment in any way you like. Here is a way You're free to set up your development environment any way you like. Here is a
using virtualenv and virtualenvwrapper. If you don't have them, you can install way using virtualenv and virtualenvwrapper. If you don't have them, you can
them using:: install these packages via::
$ pip install virtualenvwrapper $ pip install virtualenvwrapper
Virtual environments allow you to work on an installation of python which is Virtual environments allow you to work on Python projects which are isolated
not the one installed on your system. Especially, it will install the different from one another so you can use different packages (and package versions) with
projects under a different location. different projects.
To create the virtualenv environment, you have to do:: To create a virtual environment, use the following syntax::
$ mkvirtualenv pelican --no-site-package $ mkvirtualenv pelican
Then you would have to install all the dependencies:: To manually install the dependencies::
$ pip install -r dev_requirements.txt $ pip install -r dev_requirements.txt
$ python setup.py develop $ python setup.py develop
@ -31,10 +31,10 @@ Running the test suite
====================== ======================
Each time you add a feature, there are two things to do regarding tests: Each time you add a feature, there are two things to do regarding tests:
checking that the tests run in a right way, and be sure that you add tests for checking that the existing tests pass, and adding tests for your new feature
the feature you are working on or the bug you're fixing. or for the bug you're fixing.
The tests leaves under "pelican/tests" and you can run them using the The tests live in "pelican/tests" and you can run them using the
"discover" feature of unittest2:: "discover" feature of unittest2::
$ unit2 discover $ unit2 discover

55
docs/faq.rst
View file

@ -1,50 +1,51 @@
Frequently Asked Questions (FAQ) Frequently Asked Questions (FAQ)
################################ ################################
Here is a summary of the frequently asked questions for pelican. Here is a summary of the frequently asked questions for Pelican.
Is it mandatory to have a configuration file ? Is it mandatory to have a configuration file?
============================================== =============================================
No, it's not. Configurations files are just an easy way to configure pelican. No, it's not. Configuration files are just an easy way to configure Pelican.
For the basic operations, it's possible to specify options while invoking For basic operations, it's possible to specify options while invoking Pelican
pelican with the command line (see `pelican --help` for more informations about via the command line. See `pelican --help` for more information.
that)
I'm creating my own theme, how to use pygments ? I'm creating my own theme. How do I use Pygments for syntax highlighting?
================================================ =========================================================================
Pygment add some classes to the generated content, so the theming of your theme Pygments adds some classes to the generated content. These classes are used by
will be done thanks to a css file. You can have a look to the one proposed by themes to style code syntax highlighting via CSS. Specifically, you can
default `on the project website <http://pygments.org/demo/15101/>`_ 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/>`_.
How do I create my own theme ? How do I create my own theme?
============================== ==============================
Please refer yourself to :ref:`theming-pelican`. Please refer to :ref:`theming-pelican`.
How can I help ? How can I help?
================ ================
You have different options to help. First, you can use pelican, and report any There are several ways to help out. First, you can use Pelican and report any
idea or problem you have on `the bugtracker suggestions or problems you might have on `the bugtracker
<http://github.com/ametaireau/pelican/issues>`_. <http://github.com/ametaireau/pelican/issues>`_.
If you want to contribute, please have a look to `the git repository If you want to contribute, please fork `the git repository
<https://github.com/ametaireau/pelican/>`_, fork it, add your changes and do <https://github.com/ametaireau/pelican/>`_, make your changes, and issue
a pull request, I'll review them as soon as possible. a pull request. I'll review your changes as soon as possible.
You can also contribute by creating themes, and making the documentation You can also contribute by creating themes and improving the documentation.
better.
I want to use markdown, but I got an error I want to use Markdown, but I got an error.
========================================== ===========================================
Markdown is not a hard dependency for pelican, so you will need to install it Markdown is not a hard dependency for Pelican, so you will need to explicitly
by yourself. You can do so by typing:: install it. You can do so by typing::
$ (sudo) pip install markdown $ (sudo) pip install markdown
In case you don't have pip installed, consider installing it by doing:: In case you don't have pip installed, consider installing it via::
$ (sudo) easy_install pip $ (sudo) easy_install pip

140
docs/getting_started.rst
View file

@ -4,13 +4,12 @@ Getting started
Installing Installing
========== ==========
You're ready? Let's go ! You can install pelican in a lot of different ways, You're ready? Let's go! You can install Pelican via several different methods. The simplest is via `pip <http://pip.openplans.org/>`_::
the simpler one is via `pip <http://pip.openplans.org/>`_::
$ pip install pelican $ pip install pelican
If you have the sources, you can install pelican using the distutils command If you have the project source, you can install Pelican using the distutils
install. I recommend to do so in a virtualenv:: method. I recommend doing so in a virtualenv::
$ virtualenv pelican_venv $ virtualenv pelican_venv
$ source bin/activate $ source bin/activate
@ -19,30 +18,30 @@ install. I recommend to do so in a virtualenv::
Dependencies Dependencies
------------ ------------
At this time, pelican is dependent of the following python packages: At this time, Pelican is dependent on the following Python packages:
* feedgenerator, to generate the ATOM feeds. * feedgenerator, to generate the Atom feeds
* jinja2, for templating support. * jinja2, for templating support
If you're not using python 2.7, you will also need `argparse`. If you're not using Python 2.7, you will also need `argparse`.
Optionally: Optionally:
* docutils, for reST support * pygments, for syntax highlighting
* pygments, to have syntactic colorization with resT input * docutils, for supporting reStructuredText as an input format
* Markdown, for Markdown as an input format * Markdown, for supporting Markdown as an input format
Writing articles using pelican Writing articles using Pelican
============================== ==============================
Files metadata File metadata
-------------- --------------
Pelican tries to be smart enough to get the informations it needs from the Pelican tries to be smart enough to get the information it needs from the
file system (for instance, about the category of your articles), but you need to file system (for instance, about the category of your articles), but some
provide by hand some of those informations in your files. information you need to provide in the form of metadata inside your files.
You could provide the metadata in the restructured text files, using the You can provide this metadata in reStructuredText text files via the
following syntax (give your file the `.rst` extension):: following syntax (give your file the `.rst` extension)::
My super title My super title
@ -54,31 +53,35 @@ following syntax (give your file the `.rst` extension)::
:author: Alexis Metaireau :author: Alexis Metaireau
You can also use a markdown syntax (with a file ending in `.md`):: You can also use Markdown syntax (with a file ending in `.md`)::
Date: 2010-12-03 Date: 2010-12-03
Title: My super title Title: My super title
Tags: thats, awesome
Slug: my-super-post
Put you content here. This is the content of my super blog post.
Note that none of those are mandatory: if the date is not specified, pelican will Note that, aside from the title, none of this metadata is mandatory: if the date
rely on the mtime of your file, and the category can also be determined by the is not specified, Pelican will rely on the file's "mtime" timestamp, and the
directory where the rst file is. For instance, the category of category can be determined by the directory in which the file resides. For
`python/foobar/myfoobar.rst` is `foobar`. example, a file located at `python/foobar/myfoobar.rst` will have a category of
`foobar`.
Generate your blog Generate your blog
------------------ ------------------
To launch pelican, just use the `pelican` command:: To launch Pelican, just use the `pelican` command::
$ pelican /path/to/your/content/ [-s path/to/your/settings.py] $ pelican /path/to/your/content/ [-s path/to/your/settings.py]
And… that's all! You can see your weblog generated on the `content/` folder. And… that's all! Your weblog will be generated and saved in the `content/`
folder.
This one will just generate a simple output, with the default theme. It's not The above command will use the default theme to produce a simple site. It's not
really sexy, as it's a simple HTML output (without any style). very sexy, as it's just simple HTML output (without any style).
You can create your own style if you want, have a look to the help to see all You can create your own style if you want. Have a look at the help to see all
the options you can use:: the options you can use::
$ pelican --help $ pelican --help
@ -88,7 +91,7 @@ Kickstart a blog
You also can use the `pelican-quickstart` script to start a new blog in You also can use the `pelican-quickstart` script to start a new blog in
seconds, by just answering few questions. Just run `pelican-quickstart` and seconds, by just answering few questions. Just run `pelican-quickstart` and
you're done! (Added in pelican 3) you're done! (Added in Pelican 3.0)
Pages Pages
----- -----
@ -102,26 +105,26 @@ the menu.
Importing an existing blog Importing an existing blog
-------------------------- --------------------------
It is possible to import your blog from dotclear, wordpress and an RSS feed using It is possible to import your blog from Dotclear, WordPress, and RSS feeds using
a simple script. See :ref:`import`. a simple script. See :ref:`import`.
Translations Translations
------------ ------------
It is possible to translate articles. To do so, you need to add a `lang` meta It is possible to translate articles. To do so, you need to add a `lang` meta
in your articles/pages, and to set a `DEFAULT_LANG` setting (which is en by attribute to your articles/pages and set a `DEFAULT_LANG` setting (which is
default). English [en] by default). With those settings in place, only articles with the
Then, only articles with this default language will be listed, and default language will be listed, and each article will be accompanied by a list
each article will have a translation list. of available translations for that article.
Pelican uses the "slug" of two articles to compare if they are translations of Pelican uses the article's URL "slug" to determine if two or more articles are
each others. So it's possible to define (in restructured text) the slug translations of one another. The slug can be set manually in the file's
directly. metadata; if not set explicitly, Pelican will auto-generate the slug from the
title of the article.
Here is an exemple of two articles (one in english and the other one in Here is an example of two articles, one in English and the other in French.
french).
The english one:: The English article::
Foobar is not dead Foobar is not dead
################## ##################
@ -129,9 +132,9 @@ The english one::
:slug: foobar-is-not-dead :slug: foobar-is-not-dead
:lang: en :lang: en
That's true, foobar is still alive ! That's true, foobar is still alive!
And the french one:: And the French version::
Foobar n'est pas mort ! Foobar n'est pas mort !
####################### #######################
@ -141,56 +144,67 @@ And the french one::
Oui oui, foobar est toujours vivant ! Oui oui, foobar est toujours vivant !
Despite the text quality, you can see that only the slug is the same here. Post content quality notwithstanding, you can see that only item in common
You're not forced to define the slug that way, and it's completely possible to between the two articles is the slug, which is functioning here as an
have two translations with the same title (which defines the slug) identifier. If you'd rather not explicitly define the slug this way, you must
then instead ensure that the translated article titles are identical, since the
slug will be auto-generated from the article title.
Syntactic recognition Syntax highlighting
--------------------- ---------------------
Pelican is able to regognise the syntax you are using, and to colorize the Pelican is able to provide colorized syntax highlighting for your code blocks.
right way your block codes. To do so, you have to use the following syntax:: To do so, you have to use the following convention for reStructuredText::
.. code-block:: identifier .. code-block:: identifier
your code goes here your code goes here
The identifier is one of the lexers available `here For Markdown, format your code blocks thusly:
<http://pygments.org/docs/lexers/>`_.
You also can use the default `::` syntax:: ::identifier
your code goes here
The specified identifier should be one that appears on the
`list of available lexers <http://pygments.org/docs/lexers/>`_.
You also can use the default `::` syntax, in which case it will be assumed
that your code is written in Python. For reStructuredText::
:: ::
your code goes here your code goes here
It will be assumed that your code is witten in python. For Markdown:
::
your code goes here
Autoreload Autoreload
---------- ----------
It's possible to tell pelican to watch for your modifications, instead of It's possible to tell Pelican to watch for your modifications, instead of
manually launching it each time you need. Use the `-r` option, or manually launching it every time you want to see your changes. To enable this,
`--autoreload`. run the `pelican` command with the `-r` or `--autoreload` options.
Publishing drafts 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 before
instance, you can add a ``status: draft`` to its metadata, it will then be publishing, for example), you can add a ``status: draft`` attribute to its
available under the ``drafts`` folder, and not be listed under the index page nor metadata. That article will then be output to the ``drafts`` folder and not
any category page. listed on the index page nor on any category page.
Viewing the generated files Viewing the generated files
--------------------------- ---------------------------
The files generated by pelican are static files, so you don't actually need The files generated by Pelican are static files, so you don't actually need
something special to see what's hapenning with the generated files. anything special to see what's happening with the generated files.
You can either run your browser on the files on your disk:: You can either use your browser to open the files on your disk::
$ firefox output/index.html $ firefox output/index.html
Or run a simple web server using python:: Or run a simple web server using Python::
cd output && python -m SimpleHTTPServer cd output && python -m SimpleHTTPServer

8
docs/importer.rst
View file

@ -10,11 +10,11 @@ Description
``pelican-import`` is a command line tool for converting articles from other ``pelican-import`` is a command line tool for converting articles from other
software to ReStructuredText. The supported formats are: software to ReStructuredText. The supported formats are:
- Wordpress XML export - WordPress XML export
- Dotclear export - Dotclear export
- RSS/ATOM feed - RSS/Atom feed
The conversion from HTML to ReStructuredText relies on `pandoc The conversion from HTML to reStructuredText relies on `pandoc
<http://johnmacfarlane.net/pandoc/>`_. For Dotclear, if the source posts are <http://johnmacfarlane.net/pandoc/>`_. For Dotclear, if the source posts are
written with Markdown syntax, they will not be converted (as Pelican also written with Markdown syntax, they will not be converted (as Pelican also
supports Markdown). supports Markdown).
@ -40,7 +40,7 @@ Optional arguments:
Examples Examples
======== ========
for Wordpress:: for WordPress::
$ pelican-import --wpfile -o ~/output ~/posts.xml $ pelican-import --wpfile -o ~/output ~/posts.xml

41
docs/index.rst
View file

@ -1,57 +1,58 @@
Pelican Pelican
####### #######
Pelican is a simple weblog generator, written in python. Pelican is a simple weblog generator, written in Python.
* Write your weblog entries directly with your editor of choice (vim!) and * Write your weblog entries directly with your editor of choice (vim!) in
directly in restructured text, or markdown. reStructuredText or Markdown
* A simple cli-tool to (re)generate the weblog. * A simple CLI tool to (re)generate the weblog
* Easy to interface with DVCSes and web hooks * Easy to interface with DVCSes and web hooks
* Completely static output, so easy to host anywhere ! * Completely static output is easy to host anywhere
Features Features
======== ========
Pelican currently supports: Pelican currently supports:
* blog articles and simple pages * Blog articles and pages
* comments, via an external service (disqus). Please notice that while * Comments, via an external service (Disqus). (Please note that while
it's useful, it's an external service, and you'll not manage the useful, Disqus is an external service, and thus the comment data will be
comments by yourself. It could potentially eat your data. (optional) somewhat outside of your control and potentially subject to data loss.)
* easy theming (themes are done using `jinja2 <http://jinja.pocoo.org>`_) * Theming support (themes are created using `jinja2 <http://jinja.pocoo.org/>`_)
* PDF generation of the articles/pages (optional). * PDF generation of the articles/pages (optional)
* publication of articles in various languages * Publication of articles in multiple languages
* RSS/Atom feeds * Atom/RSS feeds
* wordpress/dotclear or RSS imports * Code syntax highlighting
* integration with various tools: twitter/google analytics (optional) * Import from WordPress, Dotclear, or RSS feeds
* Integration with external tools: Twitter, Google Analytics, etc. (optional)
Why the name "Pelican" ? Why the name "Pelican" ?
======================== ========================
Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;) Heh, you didn't notice? "Pelican" is an anagram for "Calepin" ;)
Source code Source code
=========== ===========
You can access the source code via git on http://github.com/ametaireau/pelican/ You can access the source code via git at http://github.com/ametaireau/pelican/
Feedback / Contact us Feedback / Contact us
===================== =====================
If you want to see new features in Pelican, dont hesitate to tell me, to clone If you want to see new features in Pelican, don't hesitate to tell me, to clone
the repository, etc. That's open source, dude! the repository, etc. That's open source, dude!
Contact me at "alexis at notmyidea dot org" for any request/feedback! You can Contact me at "alexis at notmyidea dot org" for any request/feedback! You can
also join the team at `#pelican on irc.freenode.org also join the team at `#pelican on irc.freenode.org
<irc://irc.freenode.net/pelican>`_ <irc://irc.freenode.net/pelican>`_
(or if you don't have any IRC client, using `the webchat (or if you don't have any IRC client, use `the webchat
<http://webchat.freenode.net/?channels=pelican&uio=d4>`_) <http://webchat.freenode.net/?channels=pelican&uio=d4>`_)
for quick feedback. for quick feedback.
Documentation Documentation
============= =============
A french version of the documentation is available at :doc:`fr/index`. A French version of the documentation is available at :doc:`fr/index`.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

91
docs/internals.rst
View file

@ -1,49 +1,48 @@
Pelican internals Pelican internals
################# #################
This section describe how pelican is working internally. As you'll see, it's This section describe how Pelican works internally. As you'll see, it's
quite simple, but a bit of documentation doesn't hurt :) quite simple, but a bit of documentation doesn't hurt. :)
You can also find in :doc:`report` an excerpt of a report the original author You can also find in the :doc:`report` section an excerpt of a report the
wrote, with some software design information. original author wrote with some software design information.
.. _report: :doc:`report` .. _report: :doc:`report`
Overall structure Overall structure
================= =================
What `pelican` does, is taking a list of files, and processing them, to some What `pelican` does is take a list of files and process them into some
sort of output. Usually, the files are restructured text and markdown files, sort of output. Usually, the input files are reStructuredText and Markdown
and the output is a blog, but it can be anything you want. files, and the output is a blog, but both input and output can be anything you
want.
I've separated the logic in different classes and concepts: The logic is separated into different classes and concepts:
* `writers` are responsible of all the writing process of the * `writers` are responsible for writing files: .html files, RSS feeds, and so
files. It's writing .html files, RSS feeds and so on. Since those operations on. Since those operations are commonly used, the object is created once and
are commonly used, the object is created once, and then passed to the then passed to the generators.
generators.
* `readers` are used to read from various formats (Markdown, and Restructured * `readers` are used to read from various formats (Markdown and
Text for now, but the system is extensible). Given a file, they return reStructuredText for now, but the system is extensible). Given a file, they return
metadata (author, tags, category etc) and content (HTML formated) metadata (author, tags, category, etc.) and content (HTML-formatted).
* `generators` generate the different outputs. For instance, pelican comes with * `generators` generate the different outputs. For instance, Pelican comes with
`ArticlesGenerator` and `PageGenerator`, into others. Given `ArticlesGenerator` and `PageGenerator`. Given a configuration, they can do
a configurations, they can do whatever they want. Most of the time it's whatever they want. Most of the time, it's generating files from inputs.
generating files from inputs.
* `pelican` also uses `templates`, so it's easy to write you own theme. The * `pelican` also uses `templates`, so it's easy to write your own theme. The
syntax is `jinja2`, and, trust me, really easy to learn, so don't hesitate syntax is `jinja2`, and, trust me, really easy to learn, so don't hesitate
a second. to jump in and build your own theme.
How to implement a new reader ? How to implement a new reader?
=============================== ==============================
There is an awesome markup language you want to add to pelican ? Is there an awesome markup language you want to add to Pelican?
Well, the only thing you have to do is to create a class that have a `read` Well, the only thing you have to do is to create a class with a `read`
method, that is returning an HTML content and some metadata. method that returns HTML content and some metadata.
Take a look to the Markdown reader:: Take a look at the Markdown reader::
class MarkdownReader(Reader): class MarkdownReader(Reader):
enabled = bool(Markdown) enabled = bool(Markdown)
@ -63,31 +62,31 @@ Take a look to the Markdown reader::
metadata[name.lower()] = meta metadata[name.lower()] = meta
return content, metadata return content, metadata
Simple isn't it ? Simple, isn't it?
If your new reader requires additional Python dependencies then you should wrap If your new reader requires additional Python dependencies, then you should wrap
their `import` statements in `try...except`. Then inside the reader's class their `import` statements in a `try...except` block. Then inside the reader's
set the `enabled` class attribute to mark import success or failure. This makes class, set the `enabled` class attribute to mark import success or failure.
it possible for users to continue using their favourite markup method without This makes it possible for users to continue using their favourite markup method
needing to install modules for all the additional formats they don't use. without needing to install modules for formats they don't use.
How to implement a new generator ? How to implement a new generator?
================================== =================================
Generators have basically two important methods. You're not forced to create Generators have two important methods. You're not forced to create
both, only the existing ones will be called. both; only the existing ones will be called.
* `generate_context`, that is called in a first place, for all the generators. * `generate_context`, that is called first, for all the generators.
Do whatever you have to do, and update the global context if needed. This Do whatever you have to do, and update the global context if needed. This
context is shared between all generators, and will be passed to the context is shared between all generators, and will be passed to the
templates. For instance, the `PageGenerator` `generate_context` method find templates. For instance, the `PageGenerator` `generate_context` method finds
all the pages, transform them into objects, and populate the context with all the pages, transforms them into objects, and populates the context with
them. Be careful to *not* output anything using this context at this stage, them. Be careful *not* to output anything using this context at this stage,
as it is likely to change by the effect of others generators. 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, * `generate_output` is then called. And guess what is it made for? Oh,
generating the output :) That's here that you may want to look at the context generating the output. :) It's here that you may want to look at the context
and call the methods of the `writer` object, that is passed at the first and call the methods of the `writer` object that is passed as the first
argument of this function. In the `PageGenerator` example, this method will argument of this function. In the `PageGenerator` example, this method will
look at all the pages recorded in the global context, and output a file on look at all the pages recorded in the global context and output a file on
the disk (using the writer method `write_file`) for each page encountered. the disk (using the writer method `write_file`) for each page encountered.

14
docs/pelican-themes.rst
View file

@ -57,11 +57,11 @@ With ``pelican-themes``, you can see the available themes by using the ``-l`` or
two-column@ two-column@
simple simple
In this example, we can see there is 3 themes available: ``notmyidea``, ``simple`` and ``two-column``. In this example, we can see there are three themes available: ``notmyidea``, ``simple``, and ``two-column``.
``two-column`` is prefixed with an ``@`` because this theme is not copied to the Pelican theme path, but just linked to it (see `Creating symbolic links`_ for details about creating symbolic links). ``two-column`` is prefixed with an ``@`` because this theme is not copied to the Pelican theme path, but is instead just linked to it (see `Creating symbolic links`_ for details about creating symbolic links).
Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get a more verbose output, like this: Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get more verbose output, like this:
.. code-block:: console .. code-block:: console
@ -95,8 +95,8 @@ This option takes as argument the path(s) of the theme(s) you want to install, a
Removing themes Removing themes
""""""""""""""" """""""""""""""
Pelican themes can also removes themes from the Pelican themes path. The ``pelican-themes`` command can also remove themes from the Pelican themes path.
The ``-r`` or ``--remove`` takes as argument the name(s) of the theme(s) you want to remove, and can be combined with the ``--verbose`` option. The ``-r`` or ``--remove`` option takes as argument the name(s) of the theme(s) you want to remove, and can be combined with the ``--verbose`` option.
.. code-block:: console .. code-block:: console
@ -113,7 +113,7 @@ The ``-r`` or ``--remove`` takes as argument the name(s) of the theme(s) you wan
Creating symbolic links Creating symbolic links
""""""""""""""""""""""" """""""""""""""""""""""
``pelican-themes`` can also install themes by creating symbolic links instead of copying the whole themes in the Pelican themes path. ``pelican-themes`` can also install themes by creating symbolic links instead of copying entire themes into the Pelican themes path.
To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option: To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option:
@ -152,7 +152,7 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
--symlink ~/Dev/Python/pelican-themes/two-column \ --symlink ~/Dev/Python/pelican-themes/two-column \
--verbose --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``

208
docs/settings.rst
View file

@ -6,26 +6,26 @@ the command line::
$ pelican -s path/to/your/settingsfile.py path $ pelican -s path/to/your/settingsfile.py path
Settings are given as the form of a python module (a file). You can have an Settings are configured in the form of a Python module (a file). You can see an
example by looking at `/samples/pelican.conf.py example by looking at `/samples/pelican.conf.py
<https://github.com/ametaireau/pelican/raw/master/samples/pelican.conf.py>`_ <https://github.com/ametaireau/pelican/raw/master/samples/pelican.conf.py>`_
All the settings identifiers must be set in caps, otherwise they will not be All the setting identifiers must be set in all-caps, otherwise they will not be
processed. processed.
The settings you define in the configuration file will be passed to the 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. templates, which allows you to use your settings to add site-wide content.
Here is a list of settings for pelican, regarding the different features. Here is a list of settings for Pelican:
Basic settings Basic settings
============== ==============
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? Setting name (default value) What does it do?
================================================ ===================================================== ================================================ =====================================================
`ARTICLE_PERMALINK_STRUCTURE` (``''``) Empty by default. Allows to render URLs in a `ARTICLE_PERMALINK_STRUCTURE` (``''``) Empty by default. Enables some customization of URL
particular way, see below. structure (see below for more detail).
`AUTHOR` Default author (put your name) `AUTHOR` Default author (put your name)
`CLEAN_URLS` (``False``) If set to `True`, the URLs will not be suffixed by `CLEAN_URLS` (``False``) If set to `True`, the URLs will not be suffixed by
`.html`, so you will have to setup URL rewriting on `.html`, so you will have to setup URL rewriting on
@ -33,68 +33,71 @@ Setting name (default value) what does it do?
`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. See "Date format and locales" set the date formatting here. See "Date format and locales"
section below for details. section below for details.
`DEFAULT_CATEGORY` (``'misc'``) The default category to fallback on. `DEFAULT_CATEGORY` (``'misc'``) The default category to fall back on.
`DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use. `DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``) The default date format you want to use.
`DISPLAY_PAGES_ON_MENU` (``True``) Display or not the pages on the menu of the `DISPLAY_PAGES_ON_MENU` (``True``) Whether to display pages on the menu of the
template. Templates can follow or not this template. Templates may or not honor this
settings. setting.
`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 timestamp information (mtime) if it can't get
informations from the metadata date information from the metadata.
`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 and just `DELETE_OUTPUT_DIRECTORY` (``False``) Delete the output directory as well as
the generated files. the generated files.
`LOCALE` (''[#]_) Change the locale. A list of locales can be provided `LOCALE` (''[#]_) Change the locale. A list of locales can be provided
here or a single string representing one locale. here or a single string representing one locale.
When providing a list, all the locales will be tried When providing a list, all the locales will be tried
until one works. until one works.
`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, the only available values
are `rst` and `md`. are `rst` and `md`.
`MD_EXTENSIONS` (``('codehilite','extra')``) A list of the extensions that the markdown processor `MD_EXTENSIONS` (``('codehilite','extra')``) A list of the extensions that the Markdown processor
will use. Refer to the extensions chapter in the will use. Refer to the extensions chapter in the
Python-Markdown documentation for a complete list of Python-Markdown documentation for a complete list of
supported extensions. supported extensions.
`OUTPUT_PATH` (``'output/'``) Where to output the generated files. `OUTPUT_PATH` (``'output/'``) Where to output the generated files.
`PATH` (``None``) path to look at for input files. `PATH` (``None``) Path to look at for input files.
`PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions `PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions
of your documents. You will need to install of your documents. You will need to install
`rst2pdf`. `rst2pdf`.
`RELATIVE_URLS` (``True``) Defines if pelican should use relative urls or `RELATIVE_URLS` (``True``) Defines whether Pelican should use relative URLs or
not. not.
`SITENAME` (``'A Pelican Blog'``) Your site name `SITENAME` (``'A Pelican Blog'``) Your site name
`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 whether to use relative URLs
or static ones. You should rather use the or static ones. You should instead use the
`RELATIVE_URL` setting for such use. `RELATIVE_URL` setting for that purpose.
`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.
`TIMEZONE` The timezone used in the date information, to `TIMEZONE` The timezone used in the date information, to
generate atom and rss feeds. See the "timezone" generate Atom and RSS feeds. See the "timezone"
section below for more info. section below for more info.
================================================ ===================================================== ================================================ =====================================================
.. [#] Default is the system locale. Default is to delete the output directory. .. [#] Default is the system locale.
Article permalink structure Article permalink structure
--------------------------- ---------------------------
Allow to render articles sorted by date, in case you specify a format as
specified in the example. It follows the python datetime directives: This setting allows you to output your articles sorted by date, provided that
you specify a format as specified below. This format follows the Python
``datetime`` directives:
* %Y: Year with century as a decimal number. * %Y: Year with century as a decimal number.
* %m: Month as a decimal number [01,12]. * %m: Month as a decimal number [01,12].
* %d: Day of the month as a decimal number [01,31]. * %d: Day of the month as a decimal number [01,31].
Note: if you specify a datetime directive, it will be substituted using the Note: If you specify a datetime directive, it will be substituted using the
date metadata field into the rest file. if the date is not specified, pelican input files' date metadata attribute. If the date is not specified for a
will rely on the mtime of your file. particular file, Pelican will rely on the file's mtime timestamp.
Check the python datetime documentation at http://bit.ly/cNcJUC for more Check the Python datetime documentation at http://bit.ly/cNcJUC for more
information. information.
Also, you can use any metadata in the restructured text files: Also, you can use other file metadata attributes as well:
* category: '%(category)s' * category: '%(category)s'
* author: '%(author)s' * author: '%(author)s'
@ -103,20 +106,19 @@ Also, you can use any metadata in the restructured text files:
Example usage: Example usage:
* '/%Y/%m/' it will be something like '/2011/07/sample-post.html'. * '/%Y/%m/' will render something like '/2011/07/sample-post.html'.
* '/%Y/%(category)s/' it will be something like '/2011/life/sample-post.html'. * '/%Y/%(category)s/' will render something like '/2011/life/sample-post.html'.
Timezone Timezone
-------- --------
If no timezone is defined, UTC is assumed. This means that the generated atom If no timezone is defined, UTC is assumed. This means that the generated Atom
and rss feeds will have wrong date information if your locale is not UTC. and RSS feeds will contain incorrect date information if your locale is not UTC.
Pelican issues a warning in case this setting is not defined, as it was not Pelican issues a warning in case this setting is not defined, as it was not
mandatory in old versions. mandatory in previous versions.
Have a look at `the wikipedia page`_ to get a list of values to set your Have a look at `the wikipedia page`_ to get a list of valid timezone values.
timezone.
.. _the wikipedia page: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones .. _the wikipedia page: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
@ -124,9 +126,9 @@ timezone.
Date format and locale Date format and locale
---------------------- ----------------------
If no DATE_FORMAT is set, fallback to DEFAULT_DATE_FORMAT. If you need to If no DATE_FORMAT is set, fall back to DEFAULT_DATE_FORMAT. If you need to
maintain multiple languages with different date format, you can set this dict maintain multiple languages with different date formats, you can set this dict
using language name (``lang`` in your posts) as key. About available format using language name (``lang`` in your posts) as key. Regarding available format
codes, see `strftime document of python`_ : codes, see `strftime document of python`_ :
DATE_FORMAT = { DATE_FORMAT = {
@ -140,8 +142,8 @@ You can set locale to further control date format:
'en_US', 'ja_JP' # On Unix/Linux 'en_US', 'ja_JP' # On Unix/Linux
) )
Also, it is possible to set different locale settings for each language, if you Also, it is possible to set different locale settings for each language. If you
put (locale, format) tuple in dict, and this will override the LOCALE setting put (locale, format) tuples in the dict, this will override the LOCALE setting
above: above:
# On Unix/Linux # On Unix/Linux
@ -156,8 +158,9 @@ above:
'jp': ('jpn','%Y-%m-%d(%a)'), 'jp': ('jpn','%Y-%m-%d(%a)'),
} }
For available list of `locales on Windows`_ . On Unix/Linux usually you can get This is a list of available `locales on Windows`_ . On Unix/Linux, usually you
a list of available locales with command ``locale -a``, see manpage `locale(1)`_ for help. can get a list of available locales via the ``locale -a`` command; see manpage
`locale(1)`_ for more information.
.. _strftime document of python: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. _strftime document of python: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
@ -169,26 +172,26 @@ a list of available locales with command ``locale -a``, see manpage `locale(1)`_
Feed settings Feed settings
============= =============
By default, pelican uses atom feeds. However, it is possible to use RSS feeds By default, Pelican uses Atom feeds. However, it is also possible to use RSS
instead, at your covenience. feeds if you prefer.
Pelican generates category feeds as well as feeds for all your articles. It does Pelican generates category feeds as well as feeds for all your articles. It does
not generate feeds for tags per default, but it is possible to do so using not generate feeds for tags by default, but it is possible to do so using
the ``TAG_FEED`` and ``TAG_FEED_RSS`` settings: the ``TAG_FEED`` and ``TAG_FEED_RSS`` settings:
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? Setting name (default value) What does it do?
================================================ ===================================================== ================================================ =====================================================
`CATEGORY_FEED` ('feeds/%s.atom.xml'[2]_) Where to put the atom categories feeds. `CATEGORY_FEED` ('feeds/%s.atom.xml'[2]_) Where to put the category Atom feeds.
`CATEGORY_FEED_RSS` (``None``, i.e. no RSS) Where to put the categories rss feeds. `CATEGORY_FEED_RSS` (``None``, i.e. no RSS) Where to put the category RSS feeds.
`FEED` (``'feeds/all.atom.xml'``) relative url to output the atom feed. `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. `FEED_RSS` (``None``, i.e. no RSS) Relative URL to output the RSS feed.
`TAG_FEED` (``None``, ie no tag feed) relative url to output the tags atom feed. It should `TAG_FEED` (``None``, ie no tag feed) Relative URL to output the tag Atom feed. It should
be defined using a "%s" matchin the tag name be defined using a "%s" match in the tag name.
`TAG_FEED_RSS` (``None``, ie no RSS tag feed) relative url to output the tag RSS feed `TAG_FEED_RSS` (``None``, ie no RSS tag feed) Relative URL to output the tag RSS feed
`FEED_MAX_ITEMS` Maximum number of items allowed in a feed. Feeds are `FEED_MAX_ITEMS` Maximum number of items allowed in a feed. Feed item
unrestricted by default. quantity is unrestricted by default.
================================================ ===================================================== ================================================ =====================================================
.. [2] %s is the name of the category. .. [2] %s is the name of the category.
@ -196,14 +199,15 @@ Setting name (default value) what does it do?
Pagination Pagination
========== ==========
The default behaviour of pelican is to list all the articles titles alongside The default behaviour of Pelican is to list all the article titles along
with a short description of them on the index page. While it works pretty well with a short description on the index page. While it works pretty well
for little to medium blogs, it is convenient to have a way to paginate this. for small-to-medium blogs, for sites with large quantity of articles it would
be convenient to have a way to paginate the list.
You can use the following settings to configure the pagination. You can use the following settings to configure the pagination.
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? 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 last page. Use this when you don't want to
@ -220,11 +224,11 @@ If you want to generate a tag cloud with all your tags, you can do so using the
following settings. following settings.
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? 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 number of tags in the cloud.
================================================ ===================================================== ================================================ =====================================================
The default theme does not support tag clouds, but it is pretty easy to add:: The default theme does not support tag clouds, but it is pretty easy to add::
@ -235,34 +239,34 @@ The default theme does not support tag clouds, but it is pretty easy to add::
{% endfor %} {% endfor %}
</ul> </ul>
You should then also define a CSS with the appropriate classes (tag-0 to tag-N, where You should then also define a CSS style with the appropriate classes (tag-0 to tag-N, where
N matches `TAG_CLOUD_STEPS` -1. N matches `TAG_CLOUD_STEPS` -1).
Translations Translations
============ ============
Pelican offers a way to translate articles. See the section on getting started for Pelican offers a way to translate articles. See the Getting Started section for
more information about that. more information.
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? Setting name (default value) What does it do?
================================================ ===================================================== ================================================ =====================================================
`DEFAULT_LANG` (``'en'``) The default language to use. `DEFAULT_LANG` (``'en'``) The default language to use.
`TRANSLATION_FEED` ('feeds/all-%s.atom.xml'[3]_) Where to put the RSS feed for translations. `TRANSLATION_FEED` ('feeds/all-%s.atom.xml'[3]_) Where to put the feed for translations.
================================================ ===================================================== ================================================ =====================================================
.. [3] %s is the language .. [3] %s is the language
Ordering contents Ordering content
================= =================
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? Setting name (default value) What does it do?
================================================ ===================================================== ================================================ =====================================================
`REVERSE_ARCHIVE_ORDER` (``False``) Reverse the archives order. (True makes it in `REVERSE_ARCHIVE_ORDER` (``False``) Reverse the archives list order. (True: orders by date
descending order: the newer first) in descending order, with newer articles first.)
`REVERSE_CATEGORY_ORDER` (``False``) Reverse the category order. (True makes it in `REVERSE_CATEGORY_ORDER` (``False``) Reverse the category order. (True: lists by reverse
descending order, default is alphabetically) alphabetical order; default lists alphabetically.)
================================================ ===================================================== ================================================ =====================================================
Theming Theming
@ -272,45 +276,45 @@ Theming is addressed in a dedicated section (see :ref:`theming-pelican`).
However, here are the settings that are related to theming. However, here are the settings that are related to theming.
================================================ ===================================================== ================================================ =====================================================
Setting name (default value) what does it do? 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)
`THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default `THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default
values is `static`, but if your theme has value is `static`, but if your theme has
other static paths, you can put them here. other static paths, you can put them here.
`CSS_FILE` (``'main.css'``) specify the CSS file you want to load `CSS_FILE` (``'main.css'``) Specify the CSS file you want to load.
================================================ ===================================================== ================================================ =====================================================
By default, two themes are availablee. You can specify them using the `-t` option: By default, two themes are available. You can specify them using the `-t` option:
* notmyidea * notmyidea
* simple (a synonym for "full text" :) * simple (a synonym for "full text" :)
You can define your own theme too, and specify it's emplacement in the same You can define your own theme too, and specify its placement in the same
way (be sure to specify the full absolute path to it). manner. (Be sure to specify the full absolute path to it.)
Here is `a guide on how to create your theme Here is `a guide on how to create your theme
<http://alexis.notmyidea.org/pelican/themes.html>`_ <http://pelican.notmyidea.org/en/latest/themes.html>`_
You can find a list of themes at http://github.com/ametaireau/pelican-themes. You can find a list of themes at http://github.com/ametaireau/pelican-themes.
Pelican comes with :doc:`pelican-themes` a small script for managing 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 The `notmyidea` theme can make good use of the following settings. I recommend
to use them too in your themes. using them in your themes as well.
======================= ======================================================= ======================= =======================================================
Setting name what does it do ? Setting name What does it do ?
======================= ======================================================= ======================= =======================================================
`DISQUS_SITENAME` Pelican can handle disqus comments, specify the `DISQUS_SITENAME` Pelican can handle Disqus comments. Specify the
sitename you've filled in on disqus Disqus sitename identifier here.
`GITHUB_URL` Your github URL (if you have one), it will then `GITHUB_URL` Your GitHub URL (if you have one). It will then
use it to create a github ribbon. use this information to create a GitHub ribbon.
`GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate google analytics. `GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate Google Analytics.
`MENUITEMS` A list of tuples (Title, Url) for additional menu `MENUITEMS` A list of tuples (Title, URL) for additional menu
items to appear at the beginning of the main menu. items to appear at the beginning of the main menu.
`PIWIK_URL` URL to your Piwik server - without 'http://' at the `PIWIK_URL` URL to your Piwik server - without 'http://' at the
beginning. beginning.
@ -318,17 +322,17 @@ Setting name what does it do ?
you have to include this setting too. (optional) you have to include this setting too. (optional)
`PIWIK_SITE_ID` ID for the monitored website. You can find the ID `PIWIK_SITE_ID` ID for the monitored website. You can find the ID
in the Piwik admin interface > settings > websites. in the Piwik admin interface > settings > websites.
`LINKS` A list of tuples (Title, Url) for links to appear on `LINKS` A list of tuples (Title, URL) for links to appear on
the header. the header.
`SOCIAL` A list of tuples (Title, Url) to appear in the `SOCIAL` A list of tuples (Title, URL) to appear in the
"social" section. "social" section.
`TWITTER_USERNAME` Allows to add a button on the articles to tweet about `TWITTER_USERNAME` Allows for adding a button to articles to encourage
them. Add you twitter username if you want this others to tweet about them. Add your Twitter username
button to appear. if you want this button to appear.
======================= ======================================================= ======================= =======================================================
In addition, you can use the "wide" version of the `notmyidea` theme, by In addition, you can use the "wide" version of the `notmyidea` theme by
adding that in your configuration:: adding the following to your configuration::
CSS_FILE = "wide.css" CSS_FILE = "wide.css"

170
docs/themes.rst
View file

@ -1,10 +1,10 @@
.. _theming-pelican: .. _theming-pelican:
How to create themes for pelican How to create themes for Pelican
################################ ################################
Pelican uses the great `jinja2 <http://jinja.pocoo.org>`_ templating engine to Pelican uses the great `jinja2 <http://jinja.pocoo.org>`_ templating engine to
generate it's HTML output. The jinja2 syntax is really simple. If you want to generate its HTML output. The jinja2 syntax is really simple. If you want to
create your own theme, feel free to take inspiration from the "simple" theme, create your own theme, feel free to take inspiration from the "simple" theme,
which is available `here which is available `here
<https://github.com/ametaireau/pelican/tree/master/pelican/themes/simple/templates>`_ <https://github.com/ametaireau/pelican/tree/master/pelican/themes/simple/templates>`_
@ -29,179 +29,183 @@ To make your own theme, you must follow the following structure::
├── tag.html // processed for each tag ├── tag.html // processed for each tag
└── tags.html // must list all the tags. Can be a tag cloud. └── tags.html // must list all the tags. Can be a tag cloud.
* `static` contains all the static content. It will be copied on the output * `static` contains all the static assets, which will be copied to the output
`theme/static` folder then. I've put the css and image folders, but they are `theme/static` folder. I've put the CSS and image folders here, but they are
just examples. Put what you need here. just examples. Put what you need here.
* `templates` contains all the templates that will be used to generate the content. * `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 I've just put the mandatory templates here; you can define your own if it helps
you to organize yourself while doing the theme. you keep things organized while creating your theme.
Templates and variables Templates and variables
======================= =======================
It's using a simple syntax, that you can embbed into your html pages. The idea is to use a simple syntax that you can embed into your HTML pages.
This document describes which templates should exist on a theme, and which This document describes which templates should exist in a theme, and which
variables will be passed to each template, while generating it. variables will be passed to each template at generation time.
All templates will receive the variables defined in your settings file, if they All templates will receive the variables defined in your settings file, if they
are in caps. You can access them directly. are in all-caps. You can access them directly.
Common variables Common variables
---------------- ----------------
All of those settings will be given to all templates. All of these settings will be available to all templates.
============= =================================================== ============= ===================================================
Variable Description Variable Description
============= =================================================== ============= ===================================================
articles That's the list of articles, ordered desc. by date 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 properties (e.g. title, summary, author access their attributes (e.g. title, summary, author
etc.). etc.)
dates The same list of article, but ordered by date, dates The same list of articles, but ordered by date,
ascending. ascending
tags A dict containing each tags (keys), and the list of tags A key-value dict containing the tags (the keys) and
relative articles. the list of respective articles (the values)
categories A dict containing each category (keys), and the categories A key-value dict containing the categories (keys)
list of relative articles. and the list of respective articles (values)
pages The list of pages. pages The list of pages
============= =================================================== ============= ===================================================
index.html index.html
---------- ----------
Home page of your blog, will finally remain at output/index.html. This is the home page of your blog, generated at output/index.html.
If pagination is active, next pages will remain at output/index`n`.html. If pagination is active, subsequent pages will reside in output/index`n`.html.
=================== =================================================== =================== ===================================================
Variable Description Variable Description
=================== =================================================== =================== ===================================================
articles_paginator A paginator object of article list. articles_paginator A paginator object for the list of articles
articles_page The current page of articles. articles_page The current page of articles
dates_paginator A paginator object of article list, ordered by date, dates_paginator A paginator object for the article list, ordered by
ascending. date, ascending.
dates_page The current page of articles, ordered by date, dates_page The current page of articles, ordered by date,
ascending. ascending.
page_name 'index'. Useful for pagination links. page_name 'index' -- useful for pagination links
=================== =================================================== =================== ===================================================
author.html author.html
------------- -------------
This template will be processed for each of the existing authors, and will This template will be processed for each of the existing authors, with
finally remain at output/author/`author_name`.html. output generated at output/author/`author_name`.html.
If pagination is active, next pages will remain at If pagination is active, subsequent pages will reside at
output/author/`author_name``n`.html. output/author/`author_name``n`.html.
=================== =================================================== =================== ===================================================
Variable Description Variable Description
=================== =================================================== =================== ===================================================
author The name of the author being processed. author The name of the author being processed
articles Articles of this author. articles Articles by this author
dates Articles of this author, but ordered by date, dates Articles by this author, but ordered by date,
ascending. ascending
articles_paginator A paginator object of article list. articles_paginator A paginator object for the list of articles
articles_page The current page of articles. articles_page The current page of articles
dates_paginator A paginator object of article list, ordered by date, dates_paginator A paginator object for the article list, ordered by
ascending. date, ascending.
dates_page The current page of articles, ordered by date, dates_page The current page of articles, ordered by date,
ascending. ascending.
page_name 'author/`author_name`'. Useful for pagination page_name 'author/`author_name`' -- useful for pagination
links. links
=================== =================================================== =================== ===================================================
category.html category.html
------------- -------------
This template will be processed for each of the existing categories, and will This template will be processed for each of the existing categories, with
finally remain at output/category/`category_name`.html. output generated at output/category/`category_name`.html.
If pagination is active, next pages will remain at If pagination is active, subsequent pages will reside at
output/category/`category_name``n`.html. output/category/`category_name``n`.html.
=================== =================================================== =================== ===================================================
Variable Description Variable Description
=================== =================================================== =================== ===================================================
category The name of the category being processed. category The name of the category being processed
articles Articles of this category. articles Articles for this category
dates Articles of this category, but ordered by date, dates Articles for this category, but ordered by date,
ascending. ascending
articles_paginator A paginator object of article list. articles_paginator A paginator object for the list of articles
articles_page The current page of articles. articles_page The current page of articles
dates_paginator A paginator object of article list, ordered by date, dates_paginator A paginator object for the list of articles,
ascending. ordered by date, ascending
dates_page The current page of articles, ordered by date, dates_page The current page of articles, ordered by date,
ascending. ascending
page_name 'category/`category_name`'. Useful for pagination page_name 'category/`category_name`' -- useful for pagination
links. links
=================== =================================================== =================== ===================================================
article.html article.html
------------- -------------
This template will be processed for each article. .html files will be output This template will be processed for each article, with .html files saved
in output/`article_name`.html. Here are the specific variables it gets. as output/`article_name`.html. Here are the specific variables it gets.
============= =================================================== ============= ===================================================
Variable Description Variable Description
============= =================================================== ============= ===================================================
article The article object to be displayed. article The article object to be displayed
category The name of the category of the current article. category The name of the category for the current article
============= =================================================== ============= ===================================================
page.html page.html
--------- ---------
For each page, this template will be processed. It will create .html files in This template will be processed for each page, with corresponding .html files
output/`page_name`.html. saved as output/`page_name`.html.
============= =================================================== ============= ===================================================
Variable Description Variable Description
============= =================================================== ============= ===================================================
page The page object to be displayed. You can access to page The page object to be displayed. You can access its
its title, slug and content. title, slug, and content.
============= =================================================== ============= ===================================================
tag.html tag.html
-------- --------
For each tag, this template will be processed. It will create .html files in This template will be processed for each tag, with corresponding .html files
output/tag/`tag_name`.html. saved as output/tag/`tag_name`.html.
If pagination is active, next pages will remain at If pagination is active, subsequent pages will reside at
output/tag/`tag_name``n`.html. output/tag/`tag_name``n`.html.
=================== =================================================== =================== ===================================================
Variable Description Variable Description
=================== =================================================== =================== ===================================================
tag The name of the tag being processed. tag The name of the tag being processed
articles Articles related to this tag. articles Articles related to this tag
dates Articles related to this tag, but ordered by date, dates Articles related to this tag, but ordered by date,
ascending. ascending
articles_paginator A paginator object of article list. articles_paginator A paginator object for the list of articles
articles_page The current page of articles. articles_page The current page of articles
dates_paginator A paginator object of article list, ordered by date, dates_paginator A paginator object for the list of articles,
ascending. ordered by date, ascending
dates_page The current page of articles, ordered by date, dates_page The current page of articles, ordered by date,
ascending. ascending
page_name 'tag/`tag_name`'. Useful for pagination links. page_name 'tag/`tag_name`' -- useful for pagination links
=================== =================================================== =================== ===================================================
Inheritance Inheritance
=========== ===========
Since version 3, pelican supports inheritance from the ``simple`` theme, so you can reuse the templates of the ``simple`` theme in your own themes: Since version 3.0, Pelican supports inheritance from the ``simple`` theme, so
you can re-use the ``simple`` theme templates in your own themes.
If one of the mandatory files in the ``templates/`` directory of your theme is missing, it will be replaced by the matching template from the ``simple`` theme, so if the HTML structure of a template of the ``simple`` theme is right for you, you don't have to rewrite it from scratch. If one of the mandatory files in the ``templates/`` directory of your theme is
missing, it will be replaced by the matching template from the ``simple`` theme.
So if the HTML structure of a template in the ``simple`` theme is right for you,
you don't have to write a new template from scratch.
You can also extend templates of the ``simple`` themes in your own themes by using the ``{% extends %}`` directive as in the following example: You can also extend templates from the ``simple`` themes in your own themes by using the ``{% extends %}`` directive as in the following example:
.. code-block:: html+jinja .. code-block:: html+jinja
{% extends "!simple/index.html" %} <!-- extends the ``index.html`` template of the ``simple`` theme --> {% extends "!simple/index.html" %} <!-- extends the ``index.html`` template from the ``simple`` theme -->
{% extends "index.html" %} <!-- "regular" extending --> {% extends "index.html" %} <!-- "regular" extending -->
@ -226,10 +230,10 @@ The first file is the ``templates/base.html`` template:
{% endblock %} {% endblock %}
1. On the first line, we extend the ``base.html`` template of the ``simple`` theme, so we don't have to rewrite the entire file. 1. On the first line, we extend the ``base.html`` template from the ``simple`` theme, so we don't have to rewrite the entire file.
2. On the third line, we open the ``head`` block which has already been defined in the ``simple`` theme 2. On the third line, we open the ``head`` block which has already been defined in the ``simple`` theme.
3. On the fourth line, the function ``super()`` keeps the content previously inserted in the ``head`` block. 3. On the fourth line, the function ``super()`` keeps the content previously inserted in the ``head`` block.
4. On the fifth line, we append a stylesheet to the page 4. On the fifth line, we append a stylesheet to the page.
5. On the last line, we close the ``head`` block. 5. On the last line, we close the ``head`` block.
This file will be extended by all the other templates, so the stylesheet will be linked from all pages. This file will be extended by all the other templates, so the stylesheet will be linked from all pages.

18
docs/tips.rst
View file

@ -1,22 +1,22 @@
Tips Tips
#### ####
Here are some tips about pelican, which you might find useful. Here are some tips about Pelican that you might find useful.
Publishing to github Publishing to GitHub
==================== ====================
Github comes with an interesting "pages" feature: you can upload things there GitHub comes with an interesting "pages" feature: you can upload things there
and it will be available directly from their servers. As pelican is a static and it will be available directly from their servers. As Pelican is a static
file generator, we can take advantage of this. file generator, we can take advantage of this.
The excellent `ghp-import <https://github.com/davisp/ghp-import>`_ makes this The excellent `ghp-import <https://github.com/davisp/ghp-import>`_ makes this
eally easy. You would have to install it:: really easy. You will have to install it::
$ pip install ghp-import $ pip install ghp-import
Then, considering a repository containing your articles, you would simply have Then, given a repository containing your articles, you would simply have
to run pelican and upload the output to github:: to run Pelican and upload the output to GitHub::
$ pelican -s pelican.conf.py . $ pelican -s pelican.conf.py .
$ ghp-import output $ ghp-import output
@ -24,8 +24,8 @@ to run pelican and upload the output to github::
And that's it. And that's it.
If you want you can put that directly into a post commit hook, so each time you If you want, you can put that directly into a post-commit hook, so each time you
commit, your blog is up to date on github! commit, your blog is up to date on GitHub!
Put the following into `.git/hooks/post-commit`:: Put the following into `.git/hooks/post-commit`::