diff --git a/README.rst b/README.rst index 84cd594d9..17905c324 100644 --- a/README.rst +++ b/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 `_) * 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 `_:: $ 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 +`_ + 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. ======================= ======================================================= diff --git a/docs/themes.rst b/docs/themes.rst new file mode 100644 index 000000000..7b7c0de58 --- /dev/null +++ b/docs/themes.rst @@ -0,0 +1,90 @@ +How to create themes for pelican +################################ + +Pelican uses the great `jinja2 `_ 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 +============= =================================================== diff --git a/pelican/generators.py b/pelican/generators.py index 34a1b181c..8ba776aba 100644 --- a/pelican/generators.py +++ b/pelican/generators.py @@ -110,8 +110,9 @@ def generate_pages(self, writer): 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 @@ def generate_output(self, writer): 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 @@ def _copy_paths(self, paths, source, destination, output_path, 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, '.') diff --git a/pelican/settings.py b/pelican/settings.py index 431340cce..88d2bde67 100644 --- a/pelican/settings.py +++ b/pelican/settings.py @@ -7,7 +7,7 @@ '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',