mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Merge branch 'master' of git://github.com/ametaireau/pelican
Conflicts: docs/settings.rst pelican/generators.py pelican/settings.py
This commit is contained in:
Alexander Artemenko
commit
138e19fa19
83 changed files with 1664 additions and 1701 deletions
|
|
@ -8,12 +8,15 @@ import sys, os
|
|||
|
||||
# -- General configuration -----------------------------------------------------
|
||||
templates_path = ['_templates']
|
||||
extensions = ['sphinx.ext.autodoc',]
|
||||
source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
project = u'Pelican'
|
||||
copyright = u'2010, Alexis Metaireau'
|
||||
copyright = u'2010, Alexis Metaireau and contributors'
|
||||
exclude_patterns = ['_build']
|
||||
pygments_style = 'sphinx'
|
||||
version = "2"
|
||||
release = version
|
||||
|
||||
# -- Options for HTML output ---------------------------------------------------
|
||||
|
||||
|
|
|
|||
38
docs/faq.rst
Normal file
38
docs/faq.rst
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
Frequently Asked Questions (FAQ)
|
||||
################################
|
||||
|
||||
Here is a summary of the frequently asked questions for pelican.
|
||||
|
||||
Is it mandatory to have a configuration file ?
|
||||
==============================================
|
||||
|
||||
No, it's not. Configurations files are just an easy way to configure pelican.
|
||||
For the basic operations, it's possible to specify options while invoking
|
||||
pelican with the command line (see `pelican --help` for more informations about
|
||||
that)
|
||||
|
||||
I'm creating my own theme, how to use pygments ?
|
||||
================================================
|
||||
|
||||
Pygment add some classes to the generated content, so the theming of your theme
|
||||
will be done thanks to a css file. You can have a look to the one proposed by
|
||||
default `on the project website <http://pygments.org/demo/15101/>`_
|
||||
|
||||
How do I create my own theme ?
|
||||
==============================
|
||||
|
||||
Please refer yourself to :ref:`theming-pelican`.
|
||||
|
||||
How can I help ?
|
||||
================
|
||||
|
||||
You have different options to help. First, you can use pelican, and report any
|
||||
idea or problem you have on `the bugtracker
|
||||
<http://github.com/ametaireau/pelican/issues>`_.
|
||||
|
||||
If you want to contribute, please have a look to `the git repository
|
||||
<https://github.com/ametaireau/pelican/>`_, fork it, add your changes and do
|
||||
a pull request, I'll review them as soon as possible.
|
||||
|
||||
You can also contribute by creating themes, and making the documentation
|
||||
better.
|
||||
20
docs/fr/astuces.rst
Normal file
20
docs/fr/astuces.rst
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
Trucs et astuces pour Pelican
|
||||
#############################
|
||||
|
||||
Personnaliser l'url d'un article pour Pelican
|
||||
=============================================
|
||||
|
||||
Par défaut, quand vous créez un article ayant pour titre *Mon article pour Pelican*,
|
||||
l'url par défaut devient *mon-article-pour-pelican.html*. Cependant, il est possible
|
||||
de modifier cela en utilisant la technique utilisée pour les traductions d'article,
|
||||
c'est à dire le paramètre *:slug:* ::
|
||||
|
||||
Mon article pour Pelican
|
||||
########################
|
||||
|
||||
:date: 2011-01-31 11:05
|
||||
:slug: super-article-pour-pelican
|
||||
|
||||
bla, bla, bla …
|
||||
|
||||
En prenant cet exemple ci dessus, votre url deviendra *super-article-pour-pelican.html*
|
||||
58
docs/fr/bases.rst
Normal file
58
docs/fr/bases.rst
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
Les bases de Pelican
|
||||
####################
|
||||
|
||||
Créer son premier article
|
||||
=========================
|
||||
|
||||
Pour créer notre premier article, nous allons éditer un fichier, par exemple premier_article.rst ::
|
||||
|
||||
Premier article pour Pelican
|
||||
############################
|
||||
:author: Guillaume
|
||||
:date: 2011-01-08 10:20
|
||||
:category: GNU-Linux
|
||||
:tags: tutoriel, git
|
||||
Ceci est un tutoriel pour configurer git.
|
||||
Bla, bla, bla ....
|
||||
|
||||
Maintenant que ce fichier est créé, on va lancer la création du blog ::
|
||||
|
||||
pelican .
|
||||
|
||||
Vous aller obtenir une sortie comme celle ci — $PATH représente le dossier où vous
|
||||
avez créé votre article ::
|
||||
|
||||
[ok] writing $PATH/output/feeds/all.atom.xml
|
||||
[ok] writing $PATH/output/feeds/GNU/Linux.atom.xml
|
||||
[ok] writing $PATH/output/feeds/all-en.atom.xml
|
||||
[ok] writing $PATH/output/premier-article-pour-pelican.html
|
||||
[ok] writing $PATH/output/index.html
|
||||
[ok] writing $PATH/output/tags.html
|
||||
[ok] writing $PATH/output/categories.html
|
||||
[ok] writing $PATH/output/archives.html
|
||||
[ok] writing $PATH/output/tag/tutoriel.html
|
||||
[ok] writing $PATH/output/tag/git.html
|
||||
[ok] writing $PATH/output/category/GNU-Linux.html
|
||||
|
||||
|
||||
Première analyse
|
||||
================
|
||||
|
||||
Nous allons décortiquer un peu tout ça ensemble.
|
||||
|
||||
* Un dossier output/ a été créé pour y mettre le fichiers xml et html du blog.
|
||||
* Dans le dossier feeds/, nous retrouvons les différents flux de syndication.
|
||||
* Le fichier de l’article et la page principale du blog a été généré.
|
||||
* Le répertoire tag/ propose une page par tag.
|
||||
* La page correspondant à la catégorie est générée dans le répertoire category/
|
||||
|
||||
Si vous ouvrez le fichier index.html — ou un autre — avec votre navigateur, vous
|
||||
remarquerez que :
|
||||
|
||||
* Le thème utilisé par défaut est notmyidea
|
||||
* Le nom du blog est A Pelican Blog.
|
||||
|
||||
Bien évidemment, il y a des paramètres de base que l’on peut modifier pour mettre
|
||||
un peu tout ça à sa sauce. C’est ce que nous allons voir au travers du fichier de configuration.
|
||||
|
||||
|
||||
154
docs/fr/configuration.rst
Normal file
154
docs/fr/configuration.rst
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
Fichier de configuration
|
||||
************************
|
||||
|
||||
On va créer un fichier de configuration que l’on va appeler **settings.py**. On peut
|
||||
utiliser Pelican sans faire ce fichier, mais il faudrait à chaque fois passer les paramètres
|
||||
en ligne de commande. Et comme il va nous servir à faire d’autres choses bien utile,
|
||||
autant l’appréhender de suite. Cependant, nous n’allons voir que la base pour l’instant.
|
||||
|
||||
Paramètres de base
|
||||
==================
|
||||
|
||||
AUTHOR :
|
||||
Désigne l’auteur par défaut ;
|
||||
|
||||
DEFAULT_CATEGORY :
|
||||
La catégorie par défaut des articles. Si ce paramètre n’est
|
||||
pas documenté, il prendra la valeur misc — pour miscellaneous (divers en français) ;
|
||||
|
||||
SITENAME :
|
||||
Le nom de votre site ;
|
||||
|
||||
OUTPUT_PATH :
|
||||
Le répertoire de sortie du blog.
|
||||
|
||||
Quand je dis qu’on va faire simple, on fait simple !
|
||||
Passons donc à ce quoi doit ressembler le fichier de configuration ::
|
||||
|
||||
# -*- coding: utf-8 -*-
|
||||
AUTHOR = "Guillaume"
|
||||
DEFAULT_CATEGORY = "GNU-Linux"
|
||||
SITENAME = "Free Culture"
|
||||
|
||||
|
||||
Si vous avez un serveur comme Apache de configuré pour votre machine, vous
|
||||
pouvez paramétrer le répertoire de sortie vers **/var/www/blog** par exemple ::
|
||||
|
||||
OUTPUT_PATH = "/var/www/blog"
|
||||
|
||||
Une remarque importante. Si vous avez besoin de passer un caractère accentué, il
|
||||
faut le préciser que la chaine est en unicode en faisant par exemple
|
||||
*AUTHOR = u"Guillaume LAMÉ"*
|
||||
|
||||
Pour bien vérifier que les paramètres sont bien pris en compte, nous allons enlever les lignes *:author: Guillaume* et *:category: GNU-Linux* de notre fichier
|
||||
**premier_article.rst** et regénérer le blog.
|
||||
|
||||
Rafraichissez votre page, ce devrait être bon.
|
||||
|
||||
Nous allons maintenant passer en revue les différents paramètres de Pelican. Je les
|
||||
ai regroupé par thème. Cependant, c’est surtout un listing avant de rentrer dans les
|
||||
détails au prochain chapitre.
|
||||
|
||||
Flux de syndication
|
||||
===================
|
||||
|
||||
CATEGORY_FEED :
|
||||
Chemin d’écriture des flux Atom liés aux catégories ;
|
||||
|
||||
CATEGORY_FEED_RSS :
|
||||
Idem pour les flux rss (Optionnel);
|
||||
|
||||
FEED :
|
||||
Chemin du flux Atom global ;
|
||||
|
||||
FEED_RSS :
|
||||
Chemin du flux Rss global (Optionnel);
|
||||
|
||||
TAG_FEED :
|
||||
Chemin des flux Atom pour les tags (Optionnel);
|
||||
|
||||
TAG_FEED_RSS :
|
||||
Chemin des flux Rss pour les tags (Optionnel).
|
||||
|
||||
|
||||
Traductions
|
||||
===========
|
||||
|
||||
DEFAULT_LANG :
|
||||
Le langage par défaut à utiliser. «*en*» par défaut ;
|
||||
|
||||
TRANSLATION_FEED :
|
||||
Chemin du flux pour les traductions.
|
||||
|
||||
|
||||
Thèmes
|
||||
======
|
||||
|
||||
CSS_FILE :
|
||||
Fichier css à utiliser si celui-ci est différent du fichier par défaut (*main.css*) ;
|
||||
|
||||
DISPLAY_PAGES_ON_MENU :
|
||||
Affiche ou non les pages statiques sur le menu du thème ;
|
||||
|
||||
DISQUS_SITENAME :
|
||||
Indiquer le nom du site spécifié sur Disqus ;
|
||||
|
||||
GITHUB_URL :
|
||||
Indiquez votre url Github ;
|
||||
|
||||
GOOGLE_ANALYTICS :
|
||||
'UA-XXXX-YYYY' pour activer Google analytics ;
|
||||
|
||||
JINJA_EXTENSIONS :
|
||||
Liste d'extension Jinja2 que vous souhaitez utiliser ;
|
||||
|
||||
LINKS :
|
||||
Une liste de tuples (Titre, url) pour afficher la liste de lien ;
|
||||
|
||||
PDF_PROCESSOR :
|
||||
Génère ou non les articles et pages au format pdf ;
|
||||
|
||||
REVERSE_ARCHIVE_ORDER :
|
||||
Met les articles plus récent en tête de l'archive ;
|
||||
|
||||
SOCIAL :
|
||||
Une liste de tuples (Titre, url) pour afficher la liste de lien dans la section "Social" ;
|
||||
|
||||
STATIC_THEME_PATHS :
|
||||
Répertoire du thème que vous souhaitez importer dans l'arborescence finale ;
|
||||
|
||||
THEME :
|
||||
Thème à utiliser:
|
||||
|
||||
TWITTER_USERNAME :
|
||||
Permet d'afficher un bouton permettant le tweet des articles.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Paramètres divers
|
||||
=================
|
||||
|
||||
FALLBACK_ON_FS_DATE :
|
||||
Si *True*, Pelican se basera sur le *mtime* du fichier s'il n'y a pas de date spécifiée dans le fichier de l'article ;
|
||||
|
||||
KEEP_OUTPUT DIRECTORY :
|
||||
Ne génère que les fichiers modifiés et n'efface pas le repertoire de sortie ;
|
||||
|
||||
MARKUP :
|
||||
Langage de balisage à utiliser ;
|
||||
|
||||
PATH :
|
||||
Répertoire à suivre pour les fichiers inclus ;
|
||||
|
||||
SITEURL :
|
||||
URL de base de votre site ;
|
||||
|
||||
STATIC_PATHS :
|
||||
Les chemins statiques que vous voulez avoir accès sur le chemin de sortie "statique" ;
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
18
docs/fr/conventions.rst
Normal file
18
docs/fr/conventions.rst
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
Conventions
|
||||
###########
|
||||
|
||||
Environnement de test
|
||||
=====================
|
||||
|
||||
Les exemples sont basées sur une distribution Debian. Pour les autres distributions,
|
||||
il y aura des ajustements à faire, notamment pour l’installation de Pelican. Les
|
||||
noms des paquets peuvent changer.
|
||||
|
||||
Conventions typographiques
|
||||
==========================
|
||||
|
||||
Un petit rappel concernant les codes sources.
|
||||
|
||||
* $ correspond à une ligne à exécuter en tant qu’utilisateur courant du systême ;
|
||||
* # correspond à une ligne à exécuter en tant que root ;
|
||||
* **settings.py** : Les noms des répertoires et fichiers sont en gras.
|
||||
35
docs/fr/faq.rst
Normal file
35
docs/fr/faq.rst
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
*Foire aux questions (FAQ)*
|
||||
|
||||
Voici un résumé des questions fréquemment posées pour pelican.
|
||||
|
||||
*Est-il obligatoire d'avoir un fichier de configuration ?*
|
||||
|
||||
Non. Les fichiers de configuration sont juste un moyen facile de configurer
|
||||
pelican. Pour les opérations de base, il est possible de spécifier des
|
||||
options
|
||||
en invoquant pelican avec la ligne de commande (voir pelican --help pour
|
||||
plus
|
||||
d'informations à ce sujet)
|
||||
|
||||
*Je crée mon propre thème, comment utiliser pygments?*
|
||||
|
||||
Pygment ajoute quelques classes au contenu généré, de sorte qua colorisation
|
||||
de votre thème se fait grâce à un fichier css. Vous pouvez jeter un oeil à
|
||||
celui proposé par`sur le site du projet <http://pygments.org/demo/15101/>`_
|
||||
|
||||
*Comment puis-je créer mon propre thèm*
|
||||
|
||||
Vueillez vous référer à :ref:`theming-pelican-fr`.
|
||||
|
||||
*Comment puis-je aider?*
|
||||
|
||||
Vous avez plusieurs options pour aider. Tout d'abord, vous pouvez utiliser
|
||||
le
|
||||
pélican, et signaler toute idée ou problème que vous avez sur le bugtracker
|
||||
.
|
||||
|
||||
Si vous voulez contribuer, jeter un oeil au dépôt git , ajoutez vos
|
||||
modifications et faites une demande, je les regarderai dès que possible
|
||||
|
||||
Vous pouvez aussi contribuer en créant des thèmes, et/ou compléter la
|
||||
documentation.
|
||||
55
docs/fr/index.rst
Normal file
55
docs/fr/index.rst
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
Pelican
|
||||
#######
|
||||
|
||||
Pelican est un generateur de blog simple codé en python
|
||||
|
||||
* Écrivez vos articles directement dans votre éditeur favori (vim !) et
|
||||
directement en syntaxe reStructuredText ou Markdown ;
|
||||
* Un outil simple en ligne de conmmande pour (re)générer le blog ;
|
||||
* Sortie complètement statique, facile pour l'héberger n'importe où ;
|
||||
|
||||
Fonctionnalités
|
||||
===============
|
||||
|
||||
Pelican supporte actuellement :
|
||||
|
||||
* des articles de blog ;
|
||||
* des pages statiques ;
|
||||
* les commentaires via un service externe (`disqus <http://disqus.com>`_)
|
||||
Notez qu'étant bien un service externe assez pratique, vous ne gérez pas
|
||||
vous même les commentaires. Ce qui pourrait occasionner une perte de vos données;
|
||||
* support de template (les templates sont crées avec `jinja2 <http://jinjna.pocoo.org>`_) ;
|
||||
* génération optionnelle de vos pages et articles en pdf.
|
||||
|
||||
Pourquoi le nom "Pelican" ?
|
||||
============================
|
||||
|
||||
Vous n'avez pas remarqué ? "Pelican" est un anagramme pour "Calepin" ;)
|
||||
|
||||
Code source
|
||||
===========
|
||||
|
||||
Vous pouvez accéder au code source via git à l'adresse
|
||||
http://github.com/ametaireau/pelican/
|
||||
|
||||
Feedback !
|
||||
==========
|
||||
|
||||
Si vous voulez de nouvelles fonctionnalitées pour Pelican, n'hésitez pas à nous le dire,
|
||||
à cloner le dépôt, etc … C'est open source !!!
|
||||
|
||||
Contactez Alexis à "alexis at notmyidea dot org" pour quelques requêtes ou retour d'expérience que ce soi !
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
conventions
|
||||
installation
|
||||
bases
|
||||
configuration
|
||||
parametres_article
|
||||
astuces
|
||||
faq
|
||||
67
docs/fr/installation.rst
Normal file
67
docs/fr/installation.rst
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
Installation et mise à jour de Pelican
|
||||
######################################
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Il y a deux façons d’installer Pelican sur son système. La première est via l’utilitaire
|
||||
pip, l’autre façon est de télécharger Pelican via Github. Ici nous allons voir les deux
|
||||
façons de procéder.
|
||||
|
||||
Via pip
|
||||
-------
|
||||
|
||||
Pour installer Pelican via pip, vous aurez besoin du paquet python-pip. puis installez Pelican ::
|
||||
|
||||
# apt-get install python-pip
|
||||
# pip install pelican
|
||||
|
||||
|
||||
Via Github
|
||||
----------
|
||||
|
||||
Pour installer Pelican en reprenant le code via Github, nous aurons besoin du paquet
|
||||
git-core pour récupérez les sources de Pelican. Puis nous procédons à l’installation ::
|
||||
|
||||
# apt-get install git-core
|
||||
$ git clone https://github.com/ametaireau/pelican.git
|
||||
$ cd pelican
|
||||
# python setup.py install
|
||||
|
||||
Mises à jour
|
||||
============
|
||||
|
||||
Via pip
|
||||
-------
|
||||
|
||||
Rien de bien compliqué pour mettre à jour via pip ::
|
||||
|
||||
$ cd votreRepertoireSource
|
||||
$ pip install --upgrade pelican
|
||||
|
||||
|
||||
Via Github
|
||||
----------
|
||||
|
||||
C'est un peu plus long avec Github par contre ::
|
||||
|
||||
$ cd votreRepertoireSource
|
||||
$ git pull origin master
|
||||
$ cd pelican
|
||||
# python setup.py install
|
||||
|
||||
Vous aurez un message d’erreur si le module setuptools de python n’est pas installé.
|
||||
La manipulation est la suivante ::
|
||||
|
||||
# apt-get install python-setuptools
|
||||
|
||||
Alors, quelle méthode choisir ?
|
||||
===============================
|
||||
|
||||
Vous avez le choix entre deux méthodes, mais aussi entre deux concepts. La méthode
|
||||
de Github est la version de développement, où les modifications arrivent assez
|
||||
fréquemment sans être testées à fond. La version de pip est une version arrêtée avec un
|
||||
numéro de version dans laquelle vous aurez moins de bug. N’oubliez cependant pas
|
||||
que le projet est très jeune et manque donc de maturité. Si vous aimez avoir les toutes
|
||||
dernières versions utilisez Github, sinon penchez vous sur pip.
|
||||
|
||||
106
docs/fr/parametres_article.rst
Normal file
106
docs/fr/parametres_article.rst
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
Les paramètres des articles dans Pelican
|
||||
########################################
|
||||
|
||||
Les catégories
|
||||
==============
|
||||
|
||||
Nous avons vu que pour affecter un article à une catégorie, nous avions le paramètre *:category:*.
|
||||
Il y a cependant plus simple, affecter un répertoire à une catégorie.
|
||||
|
||||
Dans le répertoire ou vous avez vos articles, créez le repertoire **GNU-Linux** et déplacez y le fichier
|
||||
**premier_article.rst**. Bien évidemment nous ne verront pas la différence, car jusqu'ici *GNU-Linux*
|
||||
est notre catégorie par défaut.
|
||||
|
||||
Nous allons faire un autre exemple d'article avec la catégorie Pelican. Créez le répertoire **Pelican**
|
||||
et collez cette exemple d'article ::
|
||||
|
||||
Préparation de la documentation
|
||||
###############################
|
||||
|
||||
:date: 2011-01-27 15:28
|
||||
:tags: documentation
|
||||
|
||||
Il y a quand même pas mal de boulot pour faire une documentation !
|
||||
|
||||
Et lancez la compilation du blog. Vous voyez que la catégorie est affectée automatiquement.
|
||||
|
||||
Les tags
|
||||
========
|
||||
|
||||
Pour les tags, il n'y a rien de compliqué. il suffit de mettre le(s) tags séparés si besoin d'une virgule. ::
|
||||
|
||||
Préparation de la documentation
|
||||
###############################
|
||||
|
||||
:date: 2011-01-27 15:28
|
||||
:tags: documentation, pelican
|
||||
|
||||
Par contre, par soucis de clarté au niveau des url je vous conseille de mettre les expression de plusieurs
|
||||
mots séparées par des tirets ::
|
||||
|
||||
:tags: mise-a-jour
|
||||
|
||||
et non ::
|
||||
|
||||
:tags: mise a jour
|
||||
|
||||
|
||||
Les auteurs
|
||||
===========
|
||||
|
||||
Par défaut, vous pouvez indiqué votre nom en tant qu'auteur dans le fichier de configuration.
|
||||
S'il y a plusieurs auteurs pour le site, vous pouvez le définir manuellement dans
|
||||
l'article avec la méta-donnée ::
|
||||
|
||||
:author: Guillaume
|
||||
|
||||
La date
|
||||
=======
|
||||
|
||||
La date se met au format anglophone : **YYYY-MM-DD hh:mm** ::
|
||||
|
||||
:date: 2011-01-31 14:12
|
||||
|
||||
|
||||
Les traductions
|
||||
===============
|
||||
|
||||
Pelican permet de générer un blog multilingue assez facilement. Pour cela nous devons :
|
||||
|
||||
* Définir la langue de base du blog ;
|
||||
* Donner une référence à l'article initial ;
|
||||
* Définir la langue du fichier traduit et y reporter la référence.
|
||||
|
||||
Pour définir la langue de base nous allons modifier le fichier **settings.py** et y rajouter la ligne suivante ::
|
||||
|
||||
DEFAULT_LANG = "fr"
|
||||
|
||||
Puis ajouter la référence dans notre article d'origine qui deviendra ::
|
||||
|
||||
Préparation de la documentation
|
||||
###############################
|
||||
|
||||
:date: 2011-01-27 15:28
|
||||
:tags: documentation
|
||||
:slug: preparation-de-la-documentation
|
||||
|
||||
Il y a quand même pas mal de boulot pour faire une documentation !
|
||||
|
||||
Nous n'avons plus qu'à créer l'article en anglais ::
|
||||
|
||||
Start of documentation
|
||||
######################
|
||||
|
||||
:slug: preparation-de-la-documention
|
||||
:lang: en
|
||||
|
||||
There are still a lot of work to documentation !
|
||||
|
||||
**Il est important de comprendre que la valeur de :slug: deviendra votre url. Ne mettez donc pas un diminutif pour
|
||||
identifier l'article**
|
||||
|
||||
Rien de plus à savoir pour traduire efficacement des articles.
|
||||
|
||||
|
||||
Maintenant que vous avez toutes les clés en main pour créer un article, nous allons passer à la personnalisation
|
||||
du fichier de configuration.
|
||||
|
|
@ -17,22 +17,26 @@ install. I recommend to do so in a virtualenv::
|
|||
$ python setup.py install
|
||||
|
||||
Dependencies
|
||||
============
|
||||
------------
|
||||
|
||||
At this time, pelican is dependent of the following python packages:
|
||||
|
||||
* feedgenerator, to generate the ATOM feeds.
|
||||
* jinja2, for templating support.
|
||||
* pygments, to have syntactic colorization
|
||||
* docutils and Markdown
|
||||
|
||||
If you're not using python 2.7, you will also need `argparse`.
|
||||
|
||||
All those dependencies will be processed automatically if you install pelican
|
||||
using setuptools/distribute or pip.
|
||||
Optionally:
|
||||
|
||||
* docutils, for reST support
|
||||
* pygments, to have syntactic colorization with resT input
|
||||
* Markdown, for Markdown as an input format
|
||||
|
||||
Writing articles using pelican
|
||||
==============================
|
||||
|
||||
Files metadata
|
||||
==============
|
||||
--------------
|
||||
|
||||
Pelican tries to be smart enough to get the informations he needs from the
|
||||
file system (for instance, about the category of your articles), but you need to
|
||||
|
|
@ -63,11 +67,11 @@ directory where the rst file is. For instance, the category of
|
|||
`python/foobar/myfoobar.rst` is `foobar`.
|
||||
|
||||
Generate your blog
|
||||
==================
|
||||
------------------
|
||||
|
||||
To launch pelican, just use the `pelican` command::
|
||||
|
||||
$ pelican /path/to/your/content/
|
||||
$ 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.
|
||||
|
||||
|
|
@ -80,7 +84,7 @@ the options you can use::
|
|||
$ pelican --help
|
||||
|
||||
Pages
|
||||
=====
|
||||
-----
|
||||
|
||||
If you create a folder named `pages`, all the files in it will be used to
|
||||
generate static pages.
|
||||
|
|
@ -89,9 +93,60 @@ Then, use the `DISPLAY_PAGES_ON_MENU` setting, which will add all the pages to
|
|||
the menu.
|
||||
|
||||
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
|
||||
default). Then, only articles with this default language will be listed, and
|
||||
default).
|
||||
Then, only articles with this default language will be listed, and
|
||||
each article will have a translation list.
|
||||
|
||||
Pelican uses the "slug" of two articles to compare if they are translations of
|
||||
each others. So it's possible to define (in restructured text) the slug
|
||||
directly.
|
||||
|
||||
Here is an exemple of two articles (one in english and the other one in
|
||||
french).
|
||||
|
||||
The english one::
|
||||
|
||||
Foobar is not dead
|
||||
##################
|
||||
|
||||
:slug: foobar-is-not-dead
|
||||
:lang: en
|
||||
|
||||
That's true, foobar is still alive !
|
||||
|
||||
And the french one::
|
||||
|
||||
Foobar n'est pas mort !
|
||||
#######################
|
||||
|
||||
:slug: foobar-is-not-dead
|
||||
:lang: fr
|
||||
|
||||
Oui oui, foobar est toujours vivant !
|
||||
|
||||
Despite the text quality, you can see that only the slug is the same here.
|
||||
You're not forced to define the slug that way, and it's completely possible to
|
||||
have two translations with the same title (which defines the slug)
|
||||
|
||||
Syntactic recognition
|
||||
---------------------
|
||||
|
||||
Pelican is able to regognise the syntax you are using, and to colorize the
|
||||
right way your block codes. To do so, you have to use the following syntax::
|
||||
|
||||
.. code-block:: identifier
|
||||
your code goes here
|
||||
|
||||
The identifier is one of the lexers available `here
|
||||
<http://pygments.org/docs/lexers/>`_.
|
||||
|
||||
Autoreload
|
||||
----------
|
||||
|
||||
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
|
||||
`--autoreload`.
|
||||
|
|
|
|||
|
|
@ -29,8 +29,7 @@ Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;)
|
|||
Source code
|
||||
===========
|
||||
|
||||
You can access the source code via mercurial at http://hg.notmyidea.org/pelican/
|
||||
or via git on http://github.com/ametaireau/pelican/
|
||||
You can access the source code via git on http://github.com/ametaireau/pelican/
|
||||
|
||||
Feedback !
|
||||
==========
|
||||
|
|
@ -43,6 +42,8 @@ Contact me at "alexis at notmyidea dot org" for any request/feedback !
|
|||
Documentation
|
||||
=============
|
||||
|
||||
A french version of the documentation is available at :doc:`fr/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
|
@ -50,3 +51,4 @@ Documentation
|
|||
settings
|
||||
themes
|
||||
internals
|
||||
faq
|
||||
|
|
|
|||
|
|
@ -40,7 +40,8 @@ method, that is returning an HTML content and some metadata.
|
|||
|
||||
Take a look to the Markdown reader::
|
||||
|
||||
class MarkdownReader(object):
|
||||
class MarkdownReader(Reader):
|
||||
enabled = bool(Markdown)
|
||||
|
||||
def read(self, filename):
|
||||
"""Parse content and metadata of markdown files"""
|
||||
|
|
@ -59,6 +60,12 @@ Take a look to the Markdown reader::
|
|||
|
||||
Simple isn't it ?
|
||||
|
||||
If your new reader requires additional Python dependencies then you should wrap
|
||||
their `imports` statements in `try...except`. Then inside the reader's class
|
||||
set the `enabled` class attribute to mark import success or failure. This makes
|
||||
it possible for users to continue using their favourite markup method without
|
||||
needing to install modules for all the additional formats they don't use.
|
||||
|
||||
How to implement a new generator ?
|
||||
==================================
|
||||
|
||||
|
|
|
|||
|
|
@ -19,67 +19,135 @@ processed.
|
|||
Here are the available settings. Please note that all the settings you put in
|
||||
this file will be passed to the templates as well.
|
||||
|
||||
======================= =======================================================
|
||||
Setting name what it does ?
|
||||
======================= =======================================================
|
||||
`AUTHOR` Default author (put your name)
|
||||
`CATEGORY_FEED` Where to put the atom categories feeds. default is
|
||||
`feeds/%s.atom.xml`, where %s is the name of the
|
||||
category.
|
||||
`CATEGORY_FEED_RSS` Where to put the categories rss feeds. default is None
|
||||
(no rss)
|
||||
`CSS_FILE` To specify the CSS file you want to load, if it's not
|
||||
the default one ('main.css')
|
||||
`DEFAULT_CATEGORY` The default category to fallback on. `misc` by default.
|
||||
`DEFAULT_LANG` The default language to use. Default is 'en'.
|
||||
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
|
||||
Templates can follow or not this settings.
|
||||
`DIRECT_TEMPLATES` Tuple, containing templates to render. There should be
|
||||
a html file for each of these templates in the theme.
|
||||
`FALLBACK_ON_FS_DATE` If True, pelican will use the file system dates infos
|
||||
(mtime) if it can't get informations from the
|
||||
metadata?
|
||||
`FEED` relative url to output the atom feed. Default is
|
||||
`feeds/all.atom.xml`
|
||||
`FEED_RSS` relative url to output the rss feed. Default is
|
||||
None (no rss)
|
||||
`KEEP_OUTPUT_DIRECTORY` Keep the output directory and just update all the generated files.
|
||||
Default is to delete the output directory.
|
||||
`MARKUP` A list of available markup languages you want to use.
|
||||
For the moment, only available values are `rst` and `md`.
|
||||
`OUTPUT_PATH` Where to output the generated files. Default to
|
||||
"output"
|
||||
`PATH` path to look at for input files.
|
||||
`PDF_PROCESSOR` Put True if you want to have PDF versions of your
|
||||
documents. You will need to install `rst2pdf`.
|
||||
`REVERSE_ARCHIVE_ORDER` Reverse the archives order. (True makes it in
|
||||
descending order: the newer first)
|
||||
`SITEURL` base URL of your website.
|
||||
`SITENAME` Your site name,
|
||||
`STATIC_PATHS` The static paths you want to have accessible on the
|
||||
output path "static". By default, pelican will copy
|
||||
the 'images' folder to the output folder.
|
||||
`STATIC_THEME_PATHS` Static theme paths you want to copy. Default values
|
||||
is `static`, but if your theme have others static paths,
|
||||
you can put them here.
|
||||
`TAG_CLOUD_STEPS` Count of different font sizes in the tag cloud.
|
||||
`TAG_CLOUD_MAX_ITEMS` Maximum tags count in the cloud.
|
||||
`THEME` theme to use to product the output. can be the
|
||||
complete static path to a theme folder, or chosen
|
||||
between the list of default themes (see below)
|
||||
`TRANSLATION_FEED` Where to put the RSS feed for translations. Default
|
||||
is feeds/all-%s.atom.xml where %s is the name of the
|
||||
lang.
|
||||
======================= =======================================================
|
||||
|
||||
======================== =======================================================
|
||||
Setting name what it does ?
|
||||
======================== =======================================================
|
||||
`AUTHOR` Default author (put your name)
|
||||
`CATEGORY_FEED` Where to put the atom categories feeds. default is
|
||||
`feeds/%s.atom.xml`, where %s is the name of the
|
||||
category.
|
||||
`CATEGORY_FEED_RSS` Where to put the categories rss feeds. default is None
|
||||
(no rss)
|
||||
`CSS_FILE` To specify the CSS file you want to load, if it's not
|
||||
the default one ('main.css')
|
||||
`DATE_FORMATS` If you do manage multiple languages, you can set
|
||||
the date formatting here.
|
||||
`DEFAULT_CATEGORY` The default category to fallback on. `misc` by default.
|
||||
`DEFAULT_DATE_FORMAT` The default date format you want to use.
|
||||
`DEFAULT_LANG` The default language to use. Default is 'en'.
|
||||
`DEFAULT_ORPHANS` The minimum number of articles allowed on the last
|
||||
page, defaults to zero. Use this when you don't want
|
||||
to have a last page with very few articles.
|
||||
`DEFAULT_PAGINATION` The maximum number of articles to include on a page,
|
||||
not including orphans. Default is 5.
|
||||
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
|
||||
Templates can follow or not this settings.
|
||||
`FALLBACK_ON_FS_DATE` If True, pelican will use the file system dates infos
|
||||
(mtime) if it can't get informations from the
|
||||
metadata?
|
||||
`FEED` relative url to output the atom feed. Default is
|
||||
`feeds/all.atom.xml`
|
||||
`FEED_RSS` relative url to output the rss feed. Default is
|
||||
None (no rss)
|
||||
`JINJA_EXTENSIONS` A list of any Jinja2 extensions you want to use.
|
||||
Default is no extensions (the empty list).
|
||||
`KEEP_OUTPUT_DIRECTORY` Keep the output directory and just update all the
|
||||
generated files.
|
||||
`LOCALE` Change the locale. Default is the system locale.
|
||||
Default is to delete the output directory.
|
||||
`MARKUP` A list of available markup languages you want to use.
|
||||
For the moment, only available values are `rst` and `md`.
|
||||
`OUTPUT_PATH` Where to output the generated files. Default to
|
||||
"output"
|
||||
`PATH` path to look at for input files.
|
||||
`PDF_PROCESSOR` Put True if you want to have PDF versions of your
|
||||
documents. You will need to install `rst2pdf`.
|
||||
`REVERSE_ARCHIVE_ORDER` Reverse the archives order. (True makes it in
|
||||
descending order: the newer first)
|
||||
`REVERSE_CATEGORY_ORDER` Reverse the category order. (True makes it in
|
||||
descending order, default is alphabetically)
|
||||
`SITEURL` base URL of your website.
|
||||
`SITENAME` Your site name,
|
||||
`SKRIBIT_TYPE` The type of skribit widget (TAB or WIDGET).
|
||||
`SKRIBIT_TAB_COLOR` Tab color (#XXXXXX, default #333333).
|
||||
`SKRIBIT_TAB_HORIZ` Tab Distance from Left (% or distance, default Null).
|
||||
`SKRIBIT_TAB_VERT` Tab Distance from Top (% or distance, default 20%).
|
||||
`SKRIBIT_TAB_PLACEMENT` Tab placement (Top, Bottom, Left or Right, default
|
||||
LEFT).
|
||||
`SKRIBIT_TAB_SITENAME` Tab identifier (See Skribit part below).
|
||||
`SKRIBIT_WIDGET_ID` Widget identifier (See Skribit part below).
|
||||
`STATIC_PATHS` The static paths you want to have accessible on the
|
||||
output path "static". By default, pelican will copy
|
||||
the 'images' folder to the output folder.
|
||||
`STATIC_THEME_PATHS` Static theme paths you want to copy. Default values
|
||||
is `static`, but if your theme have others static paths,
|
||||
you can put them here.
|
||||
`TAG_CLOUD_STEPS` Count of different font sizes in the tag cloud.
|
||||
`TAG_CLOUD_MAX_ITEMS` Maximum tags count in the cloud.
|
||||
`THEME` theme to use to product the output. can be the
|
||||
complete static path to a theme folder, or chosen
|
||||
between the list of default themes (see below)
|
||||
`TRANSLATION_FEED` Where to put the RSS feed for translations. Default
|
||||
is feeds/all-%s.atom.xml where %s is the name of the
|
||||
lang.
|
||||
`WITH_PAGINATION` Activate pagination. Default is False.
|
||||
======================== =======================================================
|
||||
|
||||
Skribit
|
||||
=======
|
||||
|
||||
Skribit has two ways to display suggestions : as a sidebar widget or as a
|
||||
suggestions tab. You can choose one of the display by setting the SKRIBIT_TYPE
|
||||
in your config.
|
||||
|
||||
Sidebar widget
|
||||
--------------
|
||||
|
||||
The settings for sidebar widget is :
|
||||
|
||||
* SKRIBIT_WIDGET_ID : the identifier of your blog.
|
||||
|
||||
All the customizations are done in the skribit web interface.
|
||||
|
||||
To retrieve your identifier from the code snippet, you can use this python code::
|
||||
|
||||
import re
|
||||
regex = re.compile('.*http://assets.skribit.com/javascripts/SkribitWidget.\
|
||||
js\?renderTo=writeSkribitHere&blog=(.*)&.*')
|
||||
snippet = '''SNIPPET CONTENT'''
|
||||
snippet = snippet.replace('\n', '')
|
||||
identifier = regex.match(snippet).groups()[0]
|
||||
|
||||
Suggestion tab
|
||||
--------------
|
||||
|
||||
The setting for suggestion tab's customizations are :
|
||||
|
||||
* SKRIBIT_TAB_COLOR
|
||||
* SKRIBIT_TAB_DISTANCE_HORIZ
|
||||
* SKRIBIT_TAB_DISTANCE_VERT
|
||||
* SKRIBIT_TAB_PLACEMENT
|
||||
|
||||
The identifier is :
|
||||
|
||||
* SKRIBIT_TAB_SITENAME : the identifier of your blog
|
||||
|
||||
To retrieve your sitename from the code snippet, you can use this python code::
|
||||
|
||||
import re
|
||||
regex = re.compile('.*http://skribit.com/lightbox/(.*)\',.*')
|
||||
snippet = '''SNIPPET CONTENT'''
|
||||
snippet = snippet.replace('\n', '')
|
||||
identifier = regex.match(snippet).groups()[0]
|
||||
|
||||
Themes
|
||||
======
|
||||
|
||||
3 themes are available. You can specify them using the `-t` option:
|
||||
By default, two themes are availablee. You can specify them using the `-t` option:
|
||||
|
||||
* notmyidea
|
||||
* simple (a synonym for "full text" :)
|
||||
* martyalchin
|
||||
|
||||
You can define your own theme too, and specify it's emplacement in the same
|
||||
way (be sure to specify the full absolute path to it).
|
||||
|
|
@ -87,6 +155,8 @@ way (be sure to specify the full absolute path to it).
|
|||
Here is `a guide on how to create your theme
|
||||
<http://alexis.notmyidea.org/pelican/themes.html>`_
|
||||
|
||||
You can find a list of themes at http://github.com/ametaireau/pelican-themes.
|
||||
|
||||
The `notmyidea` theme can make good use of the following settings. I recommend
|
||||
to use them too in your themes.
|
||||
|
||||
|
|
@ -102,6 +172,9 @@ Setting name what it does ?
|
|||
the header.
|
||||
`SOCIAL` A list of tuples (Title, Url) to appear in the "social"
|
||||
section.
|
||||
`TWITTER_USERNAME` Allows to add a button on the articles to tweet about
|
||||
them. Add you twitter username if you want this
|
||||
button to appear.
|
||||
======================= =======================================================
|
||||
|
||||
In addition, you can use the "wide" version of the `notmyidea` theme, by
|
||||
|
|
|
|||
|
|
@ -1,8 +1,13 @@
|
|||
.. _theming-pelican:
|
||||
|
||||
How to create themes for pelican
|
||||
################################
|
||||
|
||||
Pelican uses the great `jinja2 <http://jinjna.pocoo.org>`_ templating engine to
|
||||
generate it's HTML output.
|
||||
generate it's 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,
|
||||
which is available `here
|
||||
<https://github.com/ametaireau/pelican/tree/master/pelican/themes/simple/templates>`_
|
||||
|
||||
Structure
|
||||
=========
|
||||
|
|
@ -61,18 +66,50 @@ categories A dict containing each category (keys), and the
|
|||
pages The list of pages
|
||||
============= ===================================================
|
||||
|
||||
index.html
|
||||
----------
|
||||
|
||||
Home page of your blog, will finally remain at output/index.html.
|
||||
|
||||
If pagination is active, next pages will remain at output/index`n`.html.
|
||||
|
||||
=================== ===================================================
|
||||
Variable Description
|
||||
=================== ===================================================
|
||||
articles_paginator A paginator object of article list
|
||||
articles_page The current page of articles
|
||||
dates_paginator A paginator object of article list, ordered by date,
|
||||
ascending
|
||||
dates_page The current page of articles, ordered by date,
|
||||
ascending
|
||||
page_name 'index'. Useful for pagination links.
|
||||
=================== ===================================================
|
||||
|
||||
category.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each of the existing categories, and will
|
||||
finally remain at output/category/`category_name`.html.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
============= ===================================================
|
||||
articles The articles of this category
|
||||
category The name of the category being processed
|
||||
============= ===================================================
|
||||
If pagination is active, next pages will remain at
|
||||
output/category/`category_name``n`.html.
|
||||
|
||||
=================== ===================================================
|
||||
Variable Description
|
||||
=================== ===================================================
|
||||
category The name of the category being processed
|
||||
articles Articles of this category
|
||||
dates Articles of this category, but ordered by date,
|
||||
ascending
|
||||
articles_paginator A paginator object of article list
|
||||
articles_page The current page of articles
|
||||
dates_paginator A paginator object of article list, ordered by date,
|
||||
ascending
|
||||
dates_page The current page of articles, ordered by date,
|
||||
ascending
|
||||
page_name 'category/`category_name`'. Useful for pagination
|
||||
links.
|
||||
=================== ===================================================
|
||||
|
||||
article.html
|
||||
-------------
|
||||
|
|
@ -91,11 +128,38 @@ tag.html
|
|||
--------
|
||||
|
||||
For each tag, this template will be processed. It will create .html files in
|
||||
/output/tag/`tag_name`.html
|
||||
/output/tag/`tag_name`.html.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
============= ===================================================
|
||||
tag The name of the tag being processed
|
||||
articles Articles related to this tag
|
||||
============= ===================================================
|
||||
If pagination is active, next pages will remain at
|
||||
output/tag/`tag_name``n`.html.
|
||||
|
||||
=================== ===================================================
|
||||
Variable Description
|
||||
=================== ===================================================
|
||||
tag The name of the tag being processed
|
||||
articles Articles related to this tag
|
||||
dates Articles related to this tag, but ordered by date,
|
||||
ascending
|
||||
articles_paginator A paginator object of article list
|
||||
articles_page The current page of articles
|
||||
dates_paginator A paginator object of article list, ordered by date,
|
||||
ascending
|
||||
dates_page The current page of articles, ordered by date,
|
||||
ascending
|
||||
page_name 'tag/`tag_name`'. Useful for pagination links.
|
||||
=================== ===================================================
|
||||
|
||||
Include skribit script
|
||||
======================
|
||||
|
||||
In order to support skribit scripts in your themes, you must following these
|
||||
actions :
|
||||
|
||||
* Copy `skribit_tab_script.html` and `skribit_widget_script.html` in your
|
||||
templates directory.
|
||||
* Add {% include 'skribit_tab_script.html' %} in your <head> part in order to
|
||||
support suggestions tab.
|
||||
* Add {% include 'skribit_widget_script.html' %} where you want in order to
|
||||
support sidebar widget.
|
||||
|
||||
You can take a look at notmyidea default theme for working example.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue