weeheavy/pelican-theme
1
0
Fork 0
forked from github/pelican
Code Pull requests Activity

Add a documentation about themes.

Browse source
This commit is contained in:
Alexis Metaireau 2010-12-05 19:15:02 +00:00
commit f49c91070a
4 changed files with 125 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

45
README.rst
View file

@ -36,8 +36,8 @@ You can also use a markdown syntax (with a file ending in `.md`)::
Put you content here.
Note that none of those are mandatory: if the date is not specified, pelican will
rely on the mtime of your file, and the category can also be determined by the
directory where the rst file is. For instance, the category of
rely on the mtime of your file, and the category can also be determined by the
directory where the rst file is. For instance, the category of
`python/foobar/myfoobar.rst` is `foobar`.
Features
@ -46,8 +46,8 @@ Features
Pelican currently supports:
* blog articles
* comments, via an external service (disqus). Please notice that while
it's useful, it's an external service, and you'll not manage the
* comments, via an external service (disqus). Please notice that while
it's useful, it's an external service, and you'll not manage the
comments by yourself. It could potentially eat your data.
* theming support (themes are done using `jinja2 <http://jinjna.pocoo.org>`_)
* PDF generation of the articles/pages (optional).
@ -55,7 +55,7 @@ Pelican currently supports:
Getting started — Generate your blog
-------------------------------------
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 in a lot of different ways,
the simpler one is via `pip <http://pip.openplans.org/>`_::
$ pip install pelican
@ -67,7 +67,7 @@ Then, you have just to launch pelican, like this::
And… that's all! You can see your weblog generated on the `content/` folder.
This one will just generate a simple output, with the default theme. It's not
really sexy, as it's a simple HTML output (without any style).
really sexy, as it's a simple HTML output (without any style).
You can create your own style if you want, have a look to the help to see all
the options you can use::
@ -82,7 +82,7 @@ the command line::
$ pelican -s path/to/your/settingsfile.py path
Here are the available settings. Please note that all the settings you put in
Here are the available settings. Please note that all the settings you put in
this file will be passed to the templates as well.
======================= =======================================================
@ -96,7 +96,7 @@ Setting name what it does ?
`OUTPUT_PATH` Where to output the generated files. Default to
"output"
`SITENAME` Your site name,
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
Templates can follow or not this settings.
`PDF_PROCESSOR` Put True if you want to have PDF versions of your
documents. You will need to install `rst2pdf`.
@ -106,14 +106,22 @@ Setting name what it does ?
metadata?
`MARKUP` A list of available markup languages you want to use.
moment, only available values are `rst` and `md`.
`STATIC_PATHS` The static paths you want to copy under "static"
`FEED` relative url to output the feed. Default is
`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.
`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)
`CATEGORY_FEED` Where to put the categories feeds. default is
`feeds/%s.atom.xml`
`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
`FEED_RSS` relative url to output the rss feed. Default is
None (no rss)
`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')
======================= =======================================================
@ -124,11 +132,14 @@ Themes
* notmyidea
* simple (a synonym for "full text" :)
* martyalchin
* 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).
Here is `a guide on how to create your theme
<http://alexis.notmyidea.org/pelican/themes.html>`_
The `notmyidea` theme can make good use of the following settings. I recommend
to use them too in your themes.
@ -142,7 +153,7 @@ Setting name what it does ?
`LINKS` A list of tuples (Title, Url) for links to appear on
the header.
`SOCIAL` A list of tuples (Title, Url) to appear in the "social"
section.
section.
`GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate google analytics.
======================= =======================================================

90
docs/themes.rst Normal file
View file

@ -0,0 +1,90 @@
How to create themes for pelican
################################
Pelican uses the great `jinja2 <http://jinjna.pocoo.org>`_ templating engine to
generate it's HTML output.
Structure
=========
To make your own theme, you must follow the following structure::
├── static
│   ├── css
│   └── images
└── templates
├── archives.html
├── article.html
├── categories.html
├── category.html
├── index.html
├── page.html
├── tag.html
└── tags.html
* `static` contains all the static content. It will be copied on the output
`theme/static` folder then. I've put the css and image folders, but they are
just examples. Put what you need here.
* `templates` contains all the templates that will be used to generate the content.
I've just put the mandatory templates here, you can define your own if it helps
you to organize yourself while doing the theme.
Templates and variables
=======================
It's using a simple syntax, that you can embbed into your html pages.
This document describes which templates should exists on a theme, and which
variables will be passed to each template, while generating it.
All templates will receive the variables defined in your settings file, if they
are in caps. You can access them directly.
Common variables
----------------
============= ===================================================
Variable Description
============= ===================================================
articles That's the list of articles, ordsered desc. by date
all the elements are `Article` objects, so you can
access their properties (e.g. title, summary, author
etc.
dates The same list of article, but ordered by date,
ascending
tags A dict containing each tags (keys), and the list of
relative articles.
categories A dict containing each category (keys), and the
list of relative articles.
pages The list of pages
============= ===================================================
category.html
-------------
============= ===================================================
Variable Description
============= ===================================================
articles The articles of this category
category The name of the category being processed
============= ===================================================
article.html
-------------
============= ===================================================
Variable Description
============= ===================================================
article The article object to be displayed
category The name of the category of the current article
============= ===================================================
tag.html
--------
============= ===================================================
Variable Description
============= ===================================================
tag The name of the tag being processed
articles Articles related to this tag
============= ===================================================

10
pelican/generators.py
View file

@ -110,8 +110,9 @@ class ArticlesGenerator(Generator):
for template in _DIRECT_TEMPLATES:
write('%s.html' % template, templates[template], self.context,
blog=True)
for tag in self.tags:
write('tag/%s.html' % tag, templates['tag'], self.context, tag=tag)
for tag, articles in self.tags.items():
write('tag/%s.html' % tag, templates['tag'], self.context, tag=tag,
articles=articles)
for cat in self.categories:
write('category/%s.html' % cat, templates['category'], self.context,
category=cat, articles=self.categories[cat])
@ -193,7 +194,8 @@ class PagesGenerator(Generator):
class StaticGenerator(Generator):
"""copy static paths to output"""
"""copy static paths (what you want to cpy, like images, medias etc.
to output"""
def _copy_paths(self, paths, source, destination, output_path,
final_path=None):
@ -204,7 +206,7 @@ class StaticGenerator(Generator):
def generate_output(self, writer):
self._copy_paths(self.settings['STATIC_PATHS'], self.path,
'static', self.output_path)
self._copy_paths(self.settings['THEME_PATHS'], self.theme,
self._copy_paths(self.settings['THEME_STATIC_PATHS'], self.theme,
'theme', self.output_path, '.')

2
pelican/settings.py
View file

@ -7,7 +7,7 @@ _DEFAULT_CONFIG = {'PATH': None,
'OUTPUT_PATH': 'output/',
'MARKUP': ('rst', 'md'),
'STATIC_PATHS': ['images',],
'THEME_PATHS': ['static',],
'THEME_STATIC_PATHS': ['static',],
'FEED': 'feeds/all.atom.xml',
'CATEGORY_FEED': 'feeds/%s.atom.xml',
'SITENAME': 'A Pelican Blog',