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 branch 'master' of https://github.com/getpelican/pelican

Browse source
This commit is contained in:
Chris Elston 2013-10-08 16:19:27 +01:00
commit 8735350245
113 changed files with 887 additions and 361 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/changelog.rst
View file

@ -1,15 +1,35 @@
Release history
###############
3.3 (XXXX-XX-XX)
================
Next release
============
- Nothing yet
3.3.0 (2013-09-24)
==================
* Drop Python 3.2 support in favor of Python 3.3
* Add ``Fabfile`` so Fabric can be used for workflow automation instead of Make
* ``OUTPUT_RETENTION`` setting can be used to preserve metadata (e.g., VCS
data such as ``.hg`` and ``.git``) from being removed from output directory
* Tumblr import
* Improve logic and consistency when cleaning output folder
* Improve documentation versioning and release automation
* Improve pagination flexibility
* Rename signals for better consistency (some plugins may need to be updated)
* Move metadata extraction from generators to readers; metadata extraction no
longer article-specific
* Deprecate ``FILES_TO_COPY`` in favor of ``STATIC_PATHS`` and
``EXTRA_PATH_METADATA``
* Add support for |tag| and |category| relative links.
* Summaries in Markdown posts no longer include footnotes
* Remove unnecessary whitespace in output via ``lstrip_blocks`` Jinja parameter
* Move PDF generation from core to plugin
* Replace ``MARKUP`` setting with ``READERS``
* Add warning if img tag is missing ``alt`` attribute
* Add support for ``{}`` in relative links syntax, besides ``||``
* Add support for ``{tag}`` and ``{category}`` relative links
* Add a ``content_written`` signal
3.2.1 and 3.2.2
===============

16
docs/conf.py
View file

@ -4,18 +4,26 @@ import sys, os
sys.path.append(os.path.abspath(os.pardir))
from pelican import __version__, __major__
from pelican import __version__
# -- General configuration -----------------------------------------------------
templates_path = ['_templates']
extensions = ['sphinx.ext.autodoc',]
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.extlinks']
source_suffix = '.rst'
master_doc = 'index'
project = 'Pelican'
copyright = '2010, Alexis Metaireau and contributors'
exclude_patterns = ['_build']
version = __version__
release = __major__
release = __version__
version = '.'.join(release.split('.')[:1])
last_stable = '3.2.2'
rst_prolog = '''
.. |last_stable| replace:: :pelican-doc:`{0}`
'''.format(last_stable)
extlinks = {
'pelican-doc': ('http://docs.getpelican.com/%s/', '')
}
# -- Options for HTML output ---------------------------------------------------

21
docs/faq.rst
View file

@ -23,8 +23,8 @@ How can I help?
There are several ways to help out. First, you can report any Pelican
suggestions or problems you might have via IRC or the `issue tracker
<https://github.com/getpelican/pelican/issues>`_. If submitting an issue
report, please check the existing issue list first in order to avoid submitting
a duplicate issue.
report, please first check the existing issue list (both open and closed) in
order to avoid submitting a duplicate issue.
If you want to contribute, please fork `the git repository
<https://github.com/getpelican/pelican/>`_, create a new feature branch, make
@ -49,7 +49,7 @@ themes to style code syntax highlighting via CSS. Specifically, you can
customize the appearance of your syntax highlighting via the ``.highlight pre``
class in your theme's CSS file. To see how various styles can be used to render
Django code, for example, use the style selector drop-down at top-right on the
`Pygments project demo site <http://pygments.org/demo/15101/>`_.
`Pygments project demo site <http://pygments.org/demo/>`_.
You can use the following example commands to generate a starting CSS file from
a Pygments built-in style (in this case, "monokai") and then copy the generated
@ -96,7 +96,8 @@ This metadata can then be accessed in templates such as ``article.html`` via::
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 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 %}
@ -191,3 +192,15 @@ Older themes that referenced the old setting names may not link properly.
In order to rectify this, please update your theme for compatibility by changing
the relevant values in your template files. For an example of complete feed
headers and usage please check out the ``simple`` theme.
Is Pelican only suitable for blogs?
===================================
No. Pelican can be easily configured to create and maintain any type of static site.
This may require a little customization of your theme and Pelican configuration.
For example, if you are building a launch site for your product and do not need
tags on your site, you could remove the relevant HTML code from your theme.
You can also disable generation of tag-related pages via::
TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''

111
docs/getting_started.rst
View file

@ -83,15 +83,20 @@ Viewing the generated files
---------------------------
The files generated by Pelican are static files, so you don't actually need
anything special to view them. You can either use your browser to open the
files on your disk::
anything special to view them. You can use your browser to open the generated
HTML files directly::
firefox output/index.html
Or run a simple web server using Python::
Because the above method may have trouble locating your CSS and other linked
assets, running a simple web server using Python will often provide a more
reliable previewing experience::
cd output && python -m SimpleHTTPServer
Once the ``SimpleHTTPServer`` has been started, you can preview your site at
http://localhost:8000/
Upgrading
---------
@ -390,6 +395,8 @@ If you want to exclude any pages from being linked to or listed in the menu
then add a ``status: hidden`` attribute to its metadata. This is useful for
things like making error pages that fit the generated theme of your site.
.. _ref-linking-to-internal-content:
Linking to internal content
---------------------------
@ -400,7 +407,7 @@ and images that may be sitting alongside the current post (instead of having
to determine where those resources will be placed after site generation).
To link to internal content (files in the ``content`` directory), use the
following syntax: ``|filename|path/to/file``::
following syntax: ``{filename}path/to/file``::
website/
@ -421,8 +428,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.rst>`_
`a link relative to current file <|filename|cat/article2.rst>`_
`a link relative to content root <{filename}/cat/article2.rst>`_
`a link relative to current file <{filename}cat/article2.rst>`_
and ``article2.md``::
@ -431,8 +438,8 @@ and ``article2.md``::
See below intra-site link examples in Markdown format.
[a link relative to content root](|filename|/article1.md)
[a link relative to current file](|filename|../article1.md)
[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``
@ -447,21 +454,27 @@ manually::
And ``image-test.md`` would include::
![Alt Text](|filename|/images/han.jpg)
![Alt Text]({filename}/images/han.jpg)
Any content can be linked in this way. What happens is that the ``images``
directory gets copied to ``output/static/`` upon publishing. This is
because ``images`` is in the ``settings["STATIC_PATHS"]`` list by default. If
you want to have another directory, say ``pdfs`` you would need to add the
following to ``pelicanconf.py``::
directory gets copied to ``output/`` during site generation because Pelican
includes ``images`` in the ``STATIC_PATHS`` setting's list by default. If
you want to have another directory, say ``pdfs``, copied from your content to
your output during site generation, you would need to add the following to
your settings file::
STATIC_PATHS = ['images', 'pdfs']
And then the ``pdfs`` directory would also be copied to ``output/static/``.
After the above line has been added, subsequent site generation should copy the
``content/pdfs/`` directory to ``output/pdfs/``.
You can also link to categories or tags, using the `|tag|tagname` and
`|category|foobar` syntax.
You can also link to categories or tags, using the ``{tag}tagname`` and
``{category}foobar`` syntax.
For backward compatibility, Pelican also supports bars (``||``) in addition to
curly braces (``{}``). For example: ``|filename|an_article.rst``,
``|tag|tagname``, ``|category|foobar``. The syntax was changed from ``||`` to
``{}`` to avoid collision with Markdown extensions or reST directives.
Importing an existing blog
--------------------------
@ -524,6 +537,9 @@ which posts are translations::
That's true, foobar is still alive!
.. _internal_pygments_options:
Syntax highlighting
-------------------
@ -547,13 +563,72 @@ indenting both the identifier and code::
The specified identifier (e.g. ``python``, ``ruby``) should be one that
appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
When using reStructuredText the following options are available in the
code-block directive:
============= ============ =========================================
Option Valid values Description
============= ============ =========================================
anchorlinenos N/A If present wrap line numbers in <a> tags.
classprefix string String to prepend to token class names
hl_lines numbers List of lines to be highlighted.
lineanchors string Wrap each line in an anchor using this
string and -linenumber.
linenos string If present or set to "table" output line
numbers in a table, if set to
"inline" output them inline. "none" means
do not output the line numbers for this
table.
linenospecial number If set every nth line will be given the
'special' css class.
linenostart number Line number for the first line.
linenostep number Print every nth line number.
lineseparator string String to print between lines of code,
'\n' by default.
linespans string Wrap each line in a span using this and
-linenumber.
nobackground N/A If set do not output background color for
the wrapping element
nowrap N/A If set do not wrap the tokens at all.
tagsfile string ctags file to use for name definitions.
tagurlformat string format for the ctag links.
============= ============ =========================================
Note that, depending on the version, your Pygments module might not have
all of these options available. Refer to the *HtmlFormatter* section of the
`Pygments documentation <http://pygments.org/docs/formatters/>`_ for more
details on each of the options.
For example, the following code block enables line numbers, starting at 153,
and prefixes the Pygments CSS classes with *pgcss* to make the names
more unique and avoid possible CSS conflicts::
.. code-block:: identifier
:classprefix: pgcss
:linenos: table
:linenostart: 153
<indented code block goes here>
It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable in your
Pelican settings file to include options that will be automatically applied to
every code block.
For example, if you want to have line numbers displayed for every code block
and a CSS prefix you would set this variable to::
PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}
If specified, settings for individual code blocks will override the defaults in
your settings file.
Publishing drafts
-----------------
If you want to publish an article as a draft (for friends to review before
publishing, for example), you can add a ``status: draft`` attribute to its
publishing, for example), you can add a ``Status: draft`` attribute to its
metadata. That article will then be output to the ``drafts`` folder and not
listed on the index page nor on any category page.
listed on the index page nor on any category or tag page.
.. _virtualenv: http://www.virtualenv.org/
.. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime

25
docs/index.rst
View file

@ -1,5 +1,14 @@
Pelican
=======
Pelican |release|
=================
.. ifconfig:: release.endswith('.dev')
.. warning::
This documentation is for the version of Pelican currently under development.
Were you looking for version |last_stable| documentation?
Pelican is a static site generator, written in Python_.
@ -12,7 +21,7 @@ Pelican is a static site generator, written in Python_.
Features
--------
Pelican currently supports:
Pelican |version| currently supports:
* Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact")
* Comments, via an external service (Disqus). (Please note that while
@ -42,9 +51,13 @@ If you want to see new features in Pelican, don't hesitate to offer suggestions,
clone the repository, etc. There are many ways to :doc:`contribute<contribute>`.
That's open source, dude!
Send a message to "authors at getpelican dot com" with any requests/feedback! You
can also join the team at `#pelican on Freenode`_ (or if you don't have an IRC
client handy, use the webchat_ for quick feedback.
Send a message to "authors at getpelican dot com" with any requests/feedback.
For a more immediate response, you can also join the team via IRC at
`#pelican on Freenode`_ — if you don't have an IRC client handy, use the
webchat_ for quick feedback. If you ask a question via IRC and don't get an
immediate response, don't leave the channel! It may take a few hours because
of time zone differences, but f you are patient and remain in the channel,
someone will almost always respond to your inquiry.
Documentation
-------------

16
docs/plugins.rst
View file

@ -135,15 +135,15 @@ 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.
One thing you might want is to add 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 instead have the different readers
defined via 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.
write and don't slow down Pelican itself when they're not active.
No more talking, here is the example::
No more talking — here is an example::
from pelican import signals
from pelican.readers import BaseReader
@ -153,7 +153,7 @@ No more talking, here is the example::
enabled = True # Yeah, you probably want that :-)
# The list of file extensions you want this reader to match with.
# In the case multiple readers use the same extensions, the latest will
# If multiple readers were to use the same extension, the latest will
# win (so the one you're defining here, most probably).
file_extensions = ['yeah']
@ -173,7 +173,7 @@ No more talking, here is the example::
def add_reader(readers):
readers.reader_classes['yeah'] = NewReader
# this is how pelican works.
# This is how pelican works.
def register():
signals.readers_init.connect(add_reader)

90
docs/settings.rst
View file

@ -84,10 +84,10 @@ Setting name (default value) What doe
here or a single string representing one locale.
When providing a list, all the locales will be tried
until one works.
`READERS` (``{}``) A dict of file extensions / Reader classes to overwrite or
add file readers. for instance, to avoid processing .html files:
``READERS = {'html': None}``. Or to add a custom reader for the
`foo` extension: ``READERS = {'foo': FooReader}``
`READERS` (``{}``) A dictionary of file extensions / Reader classes for Pelican to
process or ignore. For example, to avoid processing .html files,
set: ``READERS = {'html': None}``. To add a custom reader for the
`foo` extension, set: ``READERS = {'foo': FooReader}``
`IGNORE_FILES` (``['.#*']``) A list of file globbing patterns to match against the
source files to be ignored by the processor. For example,
the default ``['.#*']`` will ignore emacs lock files.
@ -106,11 +106,9 @@ Setting name (default value) What doe
`PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages.
`ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`.
`ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles.
`PDF_GENERATOR` (``False``) Set to ``True`` if you want PDF versions of your documents to be.
generated. You will need to install ``rst2pdf``.
`OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their
original format (e.g. Markdown or reStructuredText) to the
specified OUTPUT_PATH.
specified ``OUTPUT_PATH``.
`OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator.
Defaults to ``.text``. If not a valid string the default value
will be used.
@ -144,7 +142,7 @@ Setting name (default value) What doe
are not needed, set ``DIRECT_TEMPLATES = ('index', 'archives')``
`PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated.
`SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will
be the default length in words of the text created.
be the default length (measured in words) of the text created.
This only applies if your content does not otherwise
specify a summary. Setting to ``None`` will cause the summary
to be a copy of the original content.
@ -155,7 +153,15 @@ Setting name (default value) What doe
`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 status of ``draft``.
`INTRASITE_LINK_REGEX` (``'[{|](?P<what>.*?)[|}]'``) Regular expression that is used to parse internal links.
Default syntax of links to internal files, tags, etc., is
to enclose the identifier, say ``filename``, in ``{}`` or ``||``.
Identifier between ``{`` and ``}`` goes into the ``what`` capturing group.
For details see :ref:`ref-linking-to-internal-content`.
`PYGMENTS_RST_OPTIONS` (``[]``) A list of default Pygments settings for your reStructuredText
code blocks. See :ref:`internal_pygments_options` for a list of
supported options.
===================================================================== =====================================================================
.. [#] Default is the system locale.
@ -165,7 +171,7 @@ URL settings
------------
The first thing to understand is that there are currently two supported methods
for URL formation: *relative* and *absolute*. Document-relative URLs are useful
for URL formation: *relative* and *absolute*. Relative URLs are useful
when testing locally, and absolute URLs are reliable and most useful when
publishing. One method of supporting both is to have one Pelican configuration
file for local development and another for publishing. To see an example of this
@ -173,16 +179,17 @@ type of setup, use the ``pelican-quickstart`` script as described at the top of
the :doc:`Getting Started <getting_started>` page, which will produce two separate
configuration files for local development and publishing, respectively.
You can customize the URLs and locations where files will be saved. The URLs and
SAVE_AS variables use Python's format strings. These variables allow you to place
your articles in a location such as ``{slug}/index.html`` and link to them as
``{slug}`` for clean URLs. These settings give you the flexibility to place your
articles and pages anywhere you want.
You can customize the URLs and locations where files will be saved. The
``*_URL`` and ``*_SAVE_AS`` variables use Python's format strings. These
variables allow you to place your articles in a location such as
``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs. These
settings give you the flexibility to place your articles and pages anywhere you
want.
.. note::
If you specify a datetime directive, it will be substituted using the
If you specify a ``datetime`` directive, it will be substituted using the
input files' date metadata attribute. If the date is not specified for a
particular file, Pelican will rely on the file's mtime timestamp.
particular file, Pelican will rely on the file's ``mtime`` timestamp.
Check the Python datetime documentation at http://bit.ly/cNcJUC for more
information.
@ -205,7 +212,7 @@ and the URL to this would be ``/posts/2011/Aug/07/sample-post/``.
Pelican can optionally create per-year, per-month, and per-day archives of your
posts. These secondary archives are disabled by default but are automatically
enabled if you supply format strings for their respective `_SAVE_AS` settings.
enabled if you supply format strings for their respective ``_SAVE_AS`` settings.
Period archives fit intuitively with the hierarchical model of web URLs and can
make it easier for readers to navigate through the posts you've written over time.
@ -214,12 +221,12 @@ Example usage:
* YEAR_ARCHIVE_SAVE_AS = ``'posts/{date:%Y}/index.html'``
* MONTH_ARCHIVE_SAVE_AS = ``'posts/{date:%Y}/{date:%b}/index.html'``
With these settings, Pelican will create an archive of all your posts for the year
at (for instance) 'posts/2011/index.html', and an archive of all your posts for
the month at 'posts/2011/Aug/index.html'.
With these settings, Pelican will create an archive of all your posts for the
year at (for instance) ``posts/2011/index.html`` and an archive of all your
posts for the month at ``posts/2011/Aug/index.html``.
.. note::
Period archives work best when the final path segment is 'index.html'.
Period archives work best when the final path segment is ``index.html``.
This way a reader can remove a portion of your URL and automatically
arrive at an appropriate archive of posts, without having to specify
a page name.
@ -271,7 +278,7 @@ Setting name (default value) What does it do?
If you do not want one or more of the default pages to be created (e.g.,
you are the only author on your site and thus do not need an Authors page),
set the corresponding ``*_SAVE_AS`` setting to ``False`` to prevent the
set the corresponding ``*_SAVE_AS`` setting to ``None`` to prevent the
relevant page from being generated.
Timezone
@ -291,10 +298,11 @@ Have a look at `the wikipedia page`_ to get a list of valid timezone values.
Date format and locale
----------------------
If no DATE_FORMATS are set, Pelican will fall back to DEFAULT_DATE_FORMAT. If
you need to maintain multiple languages with different date formats, you can
set this dict using the language name (``lang`` metadata in your post content)
as the key. Regarding available format codes, see `strftime document of python`_ :
If no ``DATE_FORMATS`` are set, Pelican will fall back to
``DEFAULT_DATE_FORMAT``. If you need to maintain multiple languages with
different date formats, you can set the ``DATE_FORMATS`` dictionary using the
language name (``lang`` metadata in your post content) as the key. Regarding
available format codes, see `strftime document of python`_ :
.. parsed-literal::
@ -312,8 +320,8 @@ You can set locale to further control date format:
)
Also, it is possible to set different locale settings for each language. If you
put (locale, format) tuples in the dict, this will override the LOCALE setting
above:
put (locale, format) tuples in the dict, this will override the ``LOCALE``
setting above:
.. parsed-literal::
# On Unix/Linux
@ -465,9 +473,9 @@ Pagination
==========
The default behaviour of Pelican is to list all the article titles along
with a short description on the index page. While it works pretty well
for small-to-medium blogs, for sites with large quantity of articles it would
be convenient to have a way to paginate the list.
with a short description on the index page. While this works well for
small-to-medium sites, sites with a large quantity of articles will probably
benefit from paginating this list.
You can use the following settings to configure the pagination.
@ -475,8 +483,8 @@ You can use the following settings to configure the pagination.
Setting name (default value) What does it do?
================================================ =====================================================
`DEFAULT_ORPHANS` (``0``) The minimum number of articles allowed on the
last page. Use this when you don't want to
have a last page with very few articles.
last page. Use this when you don't want the last page
to only contain a handful of articles.
`DEFAULT_PAGINATION` (``False``) The maximum number of articles to include on a
page, not including orphans. False to disable
pagination.
@ -526,7 +534,7 @@ Setting name (default value) What does it do?
`TAG_CLOUD_MAX_ITEMS` (``100``) Maximum number of tags in the cloud.
================================================ =====================================================
The default theme does not include a tag cloud, but it is pretty easy to add::
The default theme does not include a tag cloud, but it is pretty easy to add one::
<ul class="tagcloud">
{% for tag in tag_cloud %}
@ -534,9 +542,10 @@ The default theme does not include a tag cloud, but it is pretty easy to add::
{% endfor %}
</ul>
You should then also define CSS styles with appropriate classes (tag-0 to tag-N, where
N matches `TAG_CLOUD_STEPS` -1), tag-0 being the most frequent, and define a ul.tagcloud
class with appropriate list-style to create the cloud, for example::
You should then also define CSS styles with appropriate classes (tag-0 to tag-N,
where N matches ``TAG_CLOUD_STEPS`` -1), tag-0 being the most frequent, and
define a ``ul.tagcloud`` class with appropriate list-style to create the cloud.
For example::
ul.tagcloud {
list-style: none;
@ -603,7 +612,10 @@ Setting name (default value) What does it do?
`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.
other static paths, you can put them here. If files
or directories with the same names are included in
the paths defined in this settings, they will be
progressively overwritten.
`CSS_FILE` (``'main.css'``) Specify the CSS file you want to load.
================================================ =====================================================

23
docs/themes.rst
View file

@ -30,12 +30,12 @@ To make your own theme, you must follow the following structure::
└── tags.html // must list all the tags. Can be a tag cloud.
* `static` contains all the static assets, which will be copied to the output
`theme` folder. I've put the CSS and image folders here, but they are
just examples. Put what you need here.
`theme` folder. The above filesystem layout includes CSS and image folders,
but those 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 keep things organized while creating your theme.
The template files listed above are mandatory; you can add your own templates
if it helps you keep things organized while creating your theme.
Templates and variables
=======================
@ -44,8 +44,8 @@ The idea is to use a simple syntax that you can embed into your HTML pages.
This document describes which templates should exist in a theme, and which
variables will be passed to each template at generation time.
All templates will receive the variables defined in your settings file, if they
are in all-caps. You can access them directly.
All templates will receive the variables defined in your settings file, as long
as they are in all-caps. You can access them directly.
Common variables
----------------
@ -58,19 +58,18 @@ Variable Description
output_file The name of the file currently being generated. For
instance, when Pelican is rendering the homepage,
output_file will be "index.html".
articles The list of articles, ordered descending by date
articles The list of articles, ordered descending by date.
All the elements are `Article` objects, so you can
access their attributes (e.g. title, summary, author
etc.). Sometimes this is shadowed (for instance in
the tags page). You will then find info about it
in the `all_articles` variable.
dates The same list of articles, but ordered by date,
ascending
ascending.
tags A list of (tag, articles) tuples, containing all
the tags.
categories A list of (category, articles) tuples, containing
all the categories.
and the list of respective articles (values)
all the categories and corresponding articles (values)
pages The list of pages
============= ===================================================
@ -91,9 +90,9 @@ __ http://jinja.pocoo.org/docs/templates/#sort
Date Formatting
---------------
Pelican formats the date with according to your settings and locale
Pelican formats the date according to your settings and locale
(``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a
``locale_date`` attribute. On the other hand, ``date`` attribute will
``locale_date`` attribute. On the other hand, the ``date`` attribute will
be a `datetime`_ object. If you need custom formatting for a date
different than your settings, use the Jinja filter ``strftime``
that comes with Pelican. Usage is same as Python `strftime`_ format,

47
docs/tips.rst
View file

@ -15,16 +15,16 @@ Project Pages and User Pages.
Project Pages
-------------
To publish a Pelican site as Project Pages you need to *push* the content of
To publish a Pelican site as a Project Page you need to *push* the content of
the ``output`` dir generated by Pelican to a repository's ``gh-pages`` branch
on GitHub.
The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which can
be installed with ``easy_install`` or ``pip``, makes this process really easy.
For example, if the sources of your Pelican site are contained in a GitHub
repository, and if you want to publish your Pelican site as Project Pages of
this repository, you can then use the following::
For example, if the source of your Pelican site is contained in a GitHub
repository, and if you want to publish that Pelican site in the form of Project
Pages to this repository, you can then use the following::
$ pelican content -o output -s pelicanconf.py
$ ghp-import output
@ -38,28 +38,28 @@ already exist). The ``git push origin gh-pages`` command updates the remote
.. note::
The ``github`` target of the Makefile created by the ``pelican-quickstart``
command publishes the Pelican site as Project Pages as described above.
command publishes the Pelican site as Project Pages, as described above.
User Pages
----------
To publish a Pelican site as User Pages you need to *push* the content of the
``output`` dir generated by Pelican to the ``master`` branch of your
``<username>.github.com`` repository on GitHub.
To publish a Pelican site in the form of User Pages, you need to *push* the
content of the ``output`` dir generated by Pelican to the ``master`` branch of
your ``<username>.github.io`` repository on GitHub.
Again, you can take advantage of ``ghp-import``::
$ pelican content -o output -s pelicanconf.py
$ ghp-import output
$ git push git@github.com:elemoine/elemoine.github.com.git gh-pages:master
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master
The ``git push`` command pushes the local ``gh-pages`` branch (freshly updated
by the ``ghp-import`` command) to the ``elemoine.github.com`` repository's
by the ``ghp-import`` command) to the ``elemoine.github.io`` repository's
``master`` branch on GitHub.
.. note::
To publish your Pelican site as User Pages feel free to adjust the the
To publish your Pelican site as User Pages, feel free to adjust the
``github`` target of the Makefile.
Extra Tips
@ -67,19 +67,30 @@ Extra Tips
Tip #1:
To automatically update your Pelican site on each commit you can create
To automatically update your Pelican site on each commit, you can create
a post-commit hook. For example, you can add the following to
``.git/hooks/post-commit``::
pelican pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
Tip #2:
To use a `custom domain
<https://help.github.com/articles/setting-up-a-custom-domain-with-pages>`_ with
GitHub Pages you need to have a ``CNAME`` file at the root of your pages. For
that you will add ``CNAME`` file to your ``content``, dir and use the
``FILES_TO_COPY`` setting variable to tell Pelican to copy that file
to the ``output`` dir. For example::
GitHub Pages, you need to put the domain of your site (e.g.,
``blog.example.com``) inside a ``CNAME`` file at the root of your site. To do
this, create the ``content/extras/`` directory and add a ``CNAME`` file to it.
Then use the ``STATIC_PATHS`` setting to tell Pelican to copy this file to your
output directory. For example::
FILES_TO_COPY = (('extra/CNAME', 'CNAME'),)
STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}
How to add YouTube or Vimeo Videos
==================================
The easiest way is to paste the embed code of the video from these sites
directly into your source content.
Alternatively, you can also use Pelican plugins like ``liquid_tags``,
``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your content.