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

Enhance and correct documentation

Browse source
This commit is contained in:
Justin Mayer 2013-09-23 19:30:51 +02:00
commit f6c9237a01
7 changed files with 129 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

13
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
@ -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 %}
@ -196,10 +197,10 @@ Is Pelican only suitable for blogs?
===================================
No. Pelican can be easily configured to create and maintain any type of static site.
This may require little customization of your theme and Pelican configuration.
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 can hide tags by removing relevant html code from your theme.
You can also disable generation of tags pages::
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 = ''

58
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
---------
@ -452,25 +457,24 @@ And ``image-test.md`` would include::
![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.
For backward compatibility, Pelican also supports bars ``||``, besides ``{}``,
i.e. the ``filename``, ``tag`` and ``category`` identifiers can be enclosed
in bars ``|`` instead of braces ``{}``, for example, ``|filename|an_article.rst``,
``|tag|tagname``, ``|category|foobar``.
Using ``{}`` ensures that the syntax will not collide with markdown extensions or
reST directives.
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
--------------------------
@ -590,12 +594,12 @@ tagsfile string ctags file to use for name definitions.
tagurlformat string format for the ctag links.
============= ============ =========================================
Note that, depending on its version, your pygments module might not have
all of these available. See the `Pygments documentation
<http://pygments.org/docs/formatters/>`_ for the HTML formatter for more
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 below code block enables line numbers, starting at 153,
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::
@ -606,25 +610,25 @@ more unique and avoid possible CSS conflicts::
<indented code block goes here>
It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable
in your Pelican configuration file for settings that will be
automatically applied to every code block.
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 wanted to have line numbers on for 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 the configuration file.
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

10
docs/index.rst
View file

@ -51,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)

77
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,9 +153,9 @@ 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
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`.
@ -173,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
@ -181,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.
@ -213,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.
@ -222,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.
@ -299,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::
@ -320,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
@ -473,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.
@ -483,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.
@ -528,7 +528,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 %}
@ -536,9 +536,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;

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,

48
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,28 +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
How to add YouTube or Vimeo Videos
==================================
The easiest way is to paste embed code of the video from these sites in your
markup file.
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`` or ``pelican_youtube``
or ``pelican_vimeo`` to embed videos in your blog.
Alternatively, you can also use Pelican plugins like ``liquid_tags``,
``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your content.