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 remote-tracking branch 'upstream/master'

Browse source
This commit is contained in:
daniel 2013-08-06 13:02:04 +01:00
commit b3a37f8a15
106 changed files with 2861 additions and 2507 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/faq.rst
View file

@ -90,12 +90,16 @@ For reStructuredText, this metadata should of course be prefixed with a colon::
:Modified: 2012-08-08
This metadata can then be accessed in the template::
This metadata can then be accessed in templates such as ``article.html`` via::
{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}
If you want to include metadata in templates outside the article context (e.g., ``base.html``), the ``if`` statement should instead be:
{% if article and article.modified %}
How do I assign custom templates on a per-page basis?
=====================================================

20
docs/getting_started.rst
View file

@ -41,7 +41,7 @@ method::
If you have Git installed and prefer to install the latest bleeding-edge
version of Pelican rather than a stable release, use the following command::
$ pip install -e git://github.com/getpelican/pelican#egg=pelican
$ pip install -e git+https://github.com/getpelican/pelican.git#egg=pelican
If you plan on using Markdown as a markup format, you'll need to install the
Markdown library as well::
@ -331,11 +331,11 @@ interprets the HTML in a very straightforward manner, reading metadata from
<html>
<head>
<title>My super title</title>
<meta name="tags" contents="thats, awesome" />
<meta name="date" contents="2012-07-09 22:28" />
<meta name="category" contents="yeah" />
<meta name="author" contents="Alexis Métaireau" />
<meta name="summary" contents="Short version for index and feeds" />
<meta name="tags" content="thats, awesome" />
<meta name="date" content="2012-07-09 22:28" />
<meta name="category" content="yeah" />
<meta name="author" content="Alexis Métaireau" />
<meta name="summary" content="Short version for index and feeds" />
</head>
<body>
This is the content of my super blog post.
@ -418,8 +418,8 @@ In this example, ``article1.rst`` could look like::
See below intra-site link examples in reStructuredText format.
`a link relative to content root <|filename|/cat/article2.md>`_
`a link relative to current file <|filename|cat/article2.md>`_
`a link relative to content root <|filename|/cat/article2.rst>`_
`a link relative to current file <|filename|cat/article2.rst>`_
and ``article2.md``::
@ -428,8 +428,8 @@ and ``article2.md``::
See below intra-site link examples in Markdown format.
[a link relative to content root](|filename|/article1.rst)
[a link relative to current file](|filename|../article1.rst)
[a link relative to content root](|filename|/article1.md)
[a link relative to current file](|filename|../article1.md)
Embedding non-article or non-page content is slightly different in that the
directories need to be specified in ``pelicanconf.py`` file. The ``images``

1
docs/index.rst
View file

@ -22,7 +22,6 @@ Pelican currently supports:
* Publication of articles in multiple languages
* Atom/RSS feeds
* Code syntax highlighting
* PDF generation of the articles/pages (optional)
* Import from WordPress, Dotclear, or RSS feeds
* Integration with external tools: Twitter, Google Analytics, etc. (optional)

66
docs/plugins.rst
View file

@ -123,3 +123,69 @@ request if you need them!
static_generate_context static_generator_context
static_generate_preread static_generator_preread
========================== ===========================
Recipes
=======
We eventually realised some of the recipes to create plugins would be best
shared in the documentation somewhere, so here they are!
How to create a new reader
--------------------------
One thing you might want is to add the support for your very own input
format. While it might make sense to add this feature in pelican core, we
wisely chose to avoid this situation, and have the different readers defined in
plugins.
The rationale behind this choice is mainly that plugins are really easy to
write and don't slow down pelican itself when they're not active.
No more talking, here is the example::
from pelican import signals
from pelican.readers import EXTENSIONS, Reader
# Create a new reader class, inheriting from the pelican.reader.Reader
class NewReader(Reader):
enabled = True # Yeah, you probably want that :-)
# The list of extensions you want this reader to match with.
# In the case multiple readers use the same extensions, the latest will
# win (so the one you're defining here, most probably).
file_extensions = ['yeah']
# You need to have a read method, which takes a filename and returns
# some content and the associated metadata.
def read(self, filename):
metadata = {'title': 'Oh yeah',
'category': 'Foo',
'date': '2012-12-01'}
parsed = {}
for key, value in metadata.items():
parsed[key] = self.process_metadata(key, value)
return "Some content", parsed
def add_reader(arg):
EXTENSIONS['yeah'] = NewReader
# this is how pelican works.
def register():
signals.initialized.connect(add_reader)
Adding a new generator
----------------------
Adding a new generator is also really easy. You might want to have a look at
:doc:`internals` for more information on how to create your own generator.
::
def get_generators(generators):
# define a new generator here if you need to
return generators
signals.get_generators.connect(get_generators)

29
docs/settings.rst
View file

@ -153,6 +153,8 @@ Setting name (default value) What doe
These templates need to use ``DIRECT_TEMPLATES`` setting.
`ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to AsciiDoc. See the `manpage
<http://www.methods.co.nz/asciidoc/manpage.html>`_
`WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a
default status of draft.
===================================================================== =====================================================================
.. [#] Default is the system locale.
@ -477,8 +479,32 @@ Setting name (default value) What does it do?
`DEFAULT_PAGINATION` (``False``) The maximum number of articles to include on a
page, not including orphans. False to disable
pagination.
`PAGINATION_PATTERNS` A set of patterns that are used to determine advanced
pagination output.
================================================ =====================================================
Using Pagination Patterns
-------------------------
The ``PAGINATION_PATTERNS`` setting can be used to configure where
subsequent pages are created. The setting is a sequence of three
element tuples, where each tuple consists of::
(minimum page, URL setting, SAVE_AS setting,)
For example, if you wanted the first page to just be ``/``, and the
second (and subsequent) pages to be ``/page/2/``, you would set
``PAGINATION_PATTERNS`` as follows::
PAGINATION_PATTERNS = (
(1, '{base_name}/', '{base_name}/index.html'),
(2, '{base_name}/page/{number}/', '{base_name}/page/{number}/index.html'),
)
This would cause the first page to be written to
``{base_name}/index.html``, and subsequent ones would be written into
``page/{number}`` directories.
Tag cloud
=========
@ -555,6 +581,9 @@ Setting name (default value) What does it do?
or absolute path to a theme folder, or the name of a
default theme or a theme installed via
``pelican-themes`` (see below).
`THEME_STATIC_DIR` (``'theme'``) Destination directory in the output path where
Pelican will place the files collected from
`THEME_STATIC_PATHS`. Default is `theme`.
`THEME_STATIC_PATHS` (``['static']``) Static theme paths you want to copy. Default
value is `static`, but if your theme has
other static paths, you can put them here.