mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Add a documentation about themes.
This commit is contained in:
Alexis Metaireau
parent
9bdb5b8a88
commit
f49c91070a
4 changed files with 125 additions and 22 deletions
45
README.rst
45
README.rst
|
|
@ -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
90
docs/themes.rst
Normal 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
|
||||
============= ===================================================
|
||||
|
|
@ -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, '.')
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue