mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Merge branch 'master' into pathdocs
This commit is contained in:
Justin Mayer
GitHub
commit
e9f81d3f9c
389 changed files with 10281 additions and 4330 deletions
BIN
docs/_static/overall.png
vendored
BIN
docs/_static/overall.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 4.9 KiB |
|
|
@ -1,10 +1,99 @@
|
|||
Release history
|
||||
###############
|
||||
|
||||
Next release
|
||||
============
|
||||
4.2.0 - 2019-10-17
|
||||
==================
|
||||
|
||||
* New signal: ``feed_generated``
|
||||
* Support inline SVGs; don't treat titles in SVGs as HTML titles
|
||||
* Add category to feeds (in addition to tags)
|
||||
* Improve content metadata field docs
|
||||
* Add docs for including other Markdown/reST files in content
|
||||
|
||||
4.1.3 - 2019-10-09
|
||||
==================
|
||||
|
||||
* Fix quick-start docs regarding `pelican --listen`
|
||||
* Set default listen address to 127.0.0.1
|
||||
* Add extra/optional Markdown dependency to setup.py
|
||||
* Use correct SSH port syntax for rsync in tasks.py
|
||||
* Place all deprecated settings handling together
|
||||
* Add related project URLs for display on PyPI
|
||||
* Skip some tests on Windows that can't pass due to filesystem differences
|
||||
|
||||
4.1.2 - 2019-09-23
|
||||
==================
|
||||
|
||||
Fix pelican.settings.load_source to avoid caching issues - PR #2621
|
||||
|
||||
4.1.1 - 2019-08-23
|
||||
==================
|
||||
|
||||
* Add AutoPub to auto-publish releases on PR merge
|
||||
* Add CSS classes for reStructuredText figures
|
||||
* Pass `argv` to Pelican `main` entrypoint
|
||||
* Set default content status to a blank string rather than `None`
|
||||
|
||||
4.1.0 - 2019-07-14
|
||||
==================
|
||||
|
||||
* Live browser reload upon changed files (provided via Invoke task)
|
||||
* Add ``pyproject.toml``, managed by Poetry
|
||||
* Support for invoking ``python -m pelican``
|
||||
* Add relative source path attribute to content
|
||||
* Allow directories in ``EXTRA_PATH_METADATA``
|
||||
* Add ``all_articles`` variable to period pages (for recent posts functionality)
|
||||
* Improve debug mode output
|
||||
* Remove blank or duplicate summaries from Atom feed
|
||||
* Fix bugs in pagination, pelican-import, pelican-quickstart, and feed importer
|
||||
|
||||
4.0.1 (2018-11-30)
|
||||
==================
|
||||
|
||||
* Refactor ``pelican.server`` logging
|
||||
* Fix bug in which all static files were processed as "draft"
|
||||
* Bug fixes for Invoke/Makefile automation, Importer, and other miscellanea
|
||||
|
||||
If upgrading from 3.7.x or earlier, please note that slug-related settings in
|
||||
4.0+ use ``{slug}`` and/or ``{lang}`` rather than ``%s``. If ``%s``-style
|
||||
settings are encountered, Pelican will emit a warning and fall back to the
|
||||
default setting. Some user-submitted themes might try to format setting values
|
||||
but fail upon site build with a ``TypeError``. In such cases, the theme needs
|
||||
to be updated. For example, instead of ``TAG_FEED_ATOM|format(tag.slug)``, use
|
||||
``TAG_FEED_ATOM.format(slug=tag.slug)``
|
||||
|
||||
4.0.0 (2018-11-13)
|
||||
==================
|
||||
|
||||
* Replace ``develop_server.sh`` script with ``pelican --listen``
|
||||
* Improved copy/link behavior for large static files (e.g., videos)
|
||||
* New ``{static}`` syntax to link to static content; content linked to by
|
||||
``{static}`` and ``{attach}`` is automatically copied over even if not in
|
||||
``STATIC_PATHS``
|
||||
* Pages can now have ``draft`` status
|
||||
* Show current settings via new ``--print-settings`` flag
|
||||
* All settings for slugs now use ``{slug}`` and/or ``{lang}`` rather than
|
||||
``%s``. If ``%s``-style settings are encountered, Pelican will emit a warning
|
||||
and fallback to the default setting.
|
||||
* New signals: ``feed_generated`` and ``page_generated_write_page``
|
||||
* Replace Fabric with Invoke and ``fabfile.py`` template with ``tasks.py``
|
||||
* Replace ``PAGINATED_DIRECT_TEMPLATES`` by ``PAGINATED_TEMPLATES``, extending
|
||||
control over pagination to all templates and making page size variable
|
||||
* Replace ``SLUG_SUBSTITUTIONS`` (and friends) by ``SLUG_REGEX_SUBSTITUTIONS``
|
||||
for more finegrained control
|
||||
* ``'{base_name}'`` value in ``PAGINATION_PATTERNS`` setting no longer strips
|
||||
``'bar'`` from ``'foo/bar.html'`` (unless ``'bar' == 'index'``).
|
||||
* ``ARTICLE_ORDER_BY`` and ``PAGE_ORDER_BY`` now also affect 1) category, tag
|
||||
and author pages 2) feeds 3) draft and hidden articles and pages
|
||||
* New ``ARTICLE_TRANSLATION_ID`` and ``PAGE_TRANSLATION_ID`` settings to
|
||||
specify metadata attributes used to identify/disable translations
|
||||
* Make the HTML reader parse multiple occurrences of metadata tags as a list
|
||||
* New Blogger XML backup importer
|
||||
* Wordpress importer now updates file links to point to local copies if the
|
||||
files were downloaded with ``--wp-attach``.
|
||||
* Importer no longer inserts extra newlines, to prevent breaking of HTML
|
||||
attributes.
|
||||
* Pelican server now prioritises ``foo.html`` and ``foo/index.html`` over
|
||||
``foo/`` when resolving ``foo``.
|
||||
|
||||
3.7.1 (2017-01-10)
|
||||
==================
|
||||
|
|
@ -91,8 +180,8 @@ Next release
|
|||
directory as articles and pages using ``{attach}`` in the path.
|
||||
* Prevent Pelican from raising an exception when there are duplicate pieces of
|
||||
metadata in a Markdown file.
|
||||
* Introduce the ``TYPOGRIFY_IGNORE_TAGS`` setting to add HTML tags to be ignored
|
||||
by Typogrify.
|
||||
* Introduce the ``TYPOGRIFY_IGNORE_TAGS`` setting to add HTML tags to be
|
||||
ignored by Typogrify.
|
||||
* Add the ability to use ``-`` in date formats to strip leading zeros. For
|
||||
example, ``%-d/%-m/%y`` will now result in the date ``9/8/12``.
|
||||
* Ensure feed generation is correctly disabled during quickstart configuration.
|
||||
|
|
@ -195,8 +284,10 @@ Next release
|
|||
* Improve appearance of LinkedIn icon in default theme
|
||||
* Add GitHub and Google+ social icons support in default theme
|
||||
* Optimize social icons
|
||||
* Add ``FEED_ALL_ATOM`` and ``FEED_ALL_RSS`` to generate feeds containing all posts regardless of their language
|
||||
* Split ``TRANSLATION_FEED`` into ``TRANSLATION_FEED_ATOM`` and ``TRANSLATION_FEED_RSS``
|
||||
* Add ``FEED_ALL_ATOM`` and ``FEED_ALL_RSS`` to generate feeds containing all
|
||||
posts regardless of their language
|
||||
* Split ``TRANSLATION_FEED`` into ``TRANSLATION_FEED_ATOM`` and
|
||||
``TRANSLATION_FEED_RSS``
|
||||
* Different feeds can now be enabled/disabled individually
|
||||
* Allow for blank author: if ``AUTHOR`` setting is not set, author won't
|
||||
default to ``${USER}`` anymore, and a post won't contain any author
|
||||
|
|
@ -204,7 +295,8 @@ Next release
|
|||
* Move LESS and Webassets support from Pelican core to plugin
|
||||
* The ``DEFAULT_DATE`` setting now defaults to ``None``, which means that
|
||||
articles won't be generated unless date metadata is specified
|
||||
* Add ``FILENAME_METADATA`` setting to support metadata extraction from filename
|
||||
* Add ``FILENAME_METADATA`` setting to support metadata extraction from
|
||||
filename
|
||||
* Add ``gzip_cache`` plugin to compress common text files into a ``.gz``
|
||||
file within the same directory as the original file, preventing the server
|
||||
(e.g. Nginx) from having to compress files during an HTTP call
|
||||
|
|
@ -275,7 +367,8 @@ Next release
|
|||
* Added translations
|
||||
* Added a way to use cleaner URLs with a rewrite url module (or equivalent)
|
||||
* Added a tag cloud
|
||||
* Added an autoreloading feature: the blog is automatically regenerated each time a modification is detected
|
||||
* Added an autoreloading feature: the blog is automatically regenerated each
|
||||
time a modification is detected
|
||||
* Translate the documentation into French
|
||||
* Import a blog from an RSS feed
|
||||
* Pagination support
|
||||
|
|
|
|||
12
docs/conf.py
12
docs/conf.py
|
|
@ -1,5 +1,5 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
|
|
@ -17,11 +17,11 @@ extensions = ['sphinx.ext.autodoc',
|
|||
source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
project = 'Pelican'
|
||||
copyright = '2015, Alexis Metaireau and contributors'
|
||||
copyright = '2010 – present, Justin Mayer, Alexis Metaireau, and contributors'
|
||||
exclude_patterns = ['_build']
|
||||
release = __version__
|
||||
version = '.'.join(release.split('.')[:1])
|
||||
last_stable = '3.7.1'
|
||||
last_stable = __version__
|
||||
rst_prolog = '''
|
||||
.. |last_stable| replace:: :pelican-doc:`{0}`
|
||||
'''.format(last_stable)
|
||||
|
|
@ -30,7 +30,7 @@ rst_prolog = '''
|
|||
pygments_style = 'sphinx'
|
||||
|
||||
extlinks = {
|
||||
'pelican-doc': ('http://docs.getpelican.com/%s/', '')
|
||||
'pelican-doc': ('https://docs.getpelican.com/%s/', '')
|
||||
}
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
|
@ -68,14 +68,14 @@ def setup(app):
|
|||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
latex_documents = [
|
||||
('index', 'Pelican.tex', 'Pelican Documentation', 'Alexis Métaireau',
|
||||
('index', 'Pelican.tex', 'Pelican Documentation', 'Justin Mayer',
|
||||
'manual'),
|
||||
]
|
||||
|
||||
# -- Options for manual page output -------------------------------------------
|
||||
man_pages = [
|
||||
('index', 'pelican', 'pelican documentation',
|
||||
['Alexis Métaireau'], 1),
|
||||
['Justin Mayer'], 1),
|
||||
('pelican-themes', 'pelican-themes', 'A theme manager for Pelican',
|
||||
['Mickaël Raybaud'], 1),
|
||||
('themes', 'pelican-theming', 'How to create themes for Pelican',
|
||||
|
|
|
|||
212
docs/content.rst
212
docs/content.rst
|
|
@ -11,7 +11,7 @@ The idea behind "pages" is that they are usually not temporal in nature and are
|
|||
used for content that does not change very often (e.g., "About" or "Contact"
|
||||
pages).
|
||||
|
||||
You can find sample content in the repository at: ``pelican/samples/content/``
|
||||
You can find sample content in the repository at ``samples/content/``.
|
||||
|
||||
.. _internal_metadata:
|
||||
|
||||
|
|
@ -70,6 +70,31 @@ Metadata syntax for Markdown posts should follow this pattern::
|
|||
|
||||
This is the content of my super blog post.
|
||||
|
||||
You can also have your own metadata keys (so long as they don't conflict with
|
||||
reserved metadata keywords) for use in your templates. The following table
|
||||
contains a list of reserved metadata keywords:
|
||||
|
||||
=============== ===============================================================
|
||||
Metadata Description
|
||||
=============== ===============================================================
|
||||
``title`` Title of the article or page
|
||||
``date`` Publication date (e.g., ``YYYY-MM-DD HH:SS``)
|
||||
``modified`` Modification date (e.g., ``YYYY-MM-DD HH:SS``)
|
||||
``tags`` Content tags, separated by commas
|
||||
``keywords`` Content keywords, separated by commas (HTML content only)
|
||||
``category`` Content category (one only — not multiple)
|
||||
``slug`` Identifier used in URLs and translations
|
||||
``author`` Content author, when there is only one
|
||||
``authors`` Content authors, when there are multiple
|
||||
``summary`` Brief description of content for index pages
|
||||
``lang`` Content language ID (``en``, ``fr``, etc.)
|
||||
``translation`` Is content is a translation of another (``true`` or ``false``)
|
||||
``status`` Content status: ``draft``, ``hidden``, or ``published``
|
||||
``template`` Name of template to use to generate content (without extension)
|
||||
``save_as`` Save content to this relative file path
|
||||
``url`` URL to use for this article/page
|
||||
=============== ===============================================================
|
||||
|
||||
Readers for additional formats (such as AsciiDoc_) are available via plugins.
|
||||
Refer to `pelican-plugins`_ repository for those.
|
||||
|
||||
|
|
@ -93,12 +118,12 @@ interprets the HTML in a very straightforward manner, reading metadata from
|
|||
</body>
|
||||
</html>
|
||||
|
||||
With HTML, there is one simple exception to the standard metadata: ``tags`` can
|
||||
be specified either via the ``tags`` metadata, as is standard in Pelican, or
|
||||
via the ``keywords`` metadata, as is standard in HTML. The two can be used
|
||||
With HTML, there is one simple exception to the standard metadata: tags can be
|
||||
specified either via the ``tags`` metadata, as is standard in Pelican, or via
|
||||
the ``keywords`` metadata, as is standard in HTML. The two can be used
|
||||
interchangeably.
|
||||
|
||||
Note that, aside from the title, none of this article metadata is mandatory:
|
||||
Note that, aside from the title, none of this content metadata is mandatory:
|
||||
if the date is not specified and ``DEFAULT_DATE`` is set to ``'fs'``, Pelican
|
||||
will rely on the file's "mtime" timestamp, and the category can be determined
|
||||
by the directory in which the file resides. For example, a file located at
|
||||
|
|
@ -108,6 +133,15 @@ not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
|
|||
to ``False``. When parsing dates given in the page metadata, Pelican supports
|
||||
the W3C's `suggested subset ISO 8601`__.
|
||||
|
||||
So the title is the only required metadata. If that bothers you, worry not.
|
||||
Instead of manually specifying a title in your metadata each time, you can use
|
||||
the source content file name as the title. For example, a Markdown source file
|
||||
named ``Publishing via Pelican.md`` would automatically be assigned a title of
|
||||
*Publishing via Pelican*. If you would prefer this behavior, add the following
|
||||
line to your settings file::
|
||||
|
||||
FILENAME_METADATA = '(?P<title>.*)'
|
||||
|
||||
.. note::
|
||||
|
||||
When experimenting with different settings (especially the metadata
|
||||
|
|
@ -117,12 +151,13 @@ the W3C's `suggested subset ISO 8601`__.
|
|||
|
||||
__ `W3C ISO 8601`_
|
||||
|
||||
``modified`` should be last time you updated the article, and defaults to ``date`` if not specified.
|
||||
Besides you can show ``modified`` in the templates, feed entries in feed readers will be updated automatically
|
||||
when you set ``modified`` to the current date after you modified your article.
|
||||
``modified`` should be last time you updated the article, and defaults to
|
||||
``date`` if not specified. Besides you can show ``modified`` in the templates,
|
||||
feed entries in feed readers will be updated automatically when you set
|
||||
``modified`` to the current date after you modified your article.
|
||||
|
||||
``authors`` is a comma-separated list of article authors. If there's only one author you
|
||||
can use ``author`` field.
|
||||
``authors`` is a comma-separated list of article authors. If there's only one
|
||||
author you can use ``author`` field.
|
||||
|
||||
If you do not explicitly specify summary metadata for a given post, the
|
||||
``SUMMARY_MAX_LENGTH`` setting can be used to specify how many words from the
|
||||
|
|
@ -152,6 +187,34 @@ 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.
|
||||
|
||||
Static content
|
||||
==============
|
||||
|
||||
Static files are files other than articles and pages that are copied to the
|
||||
output folder as-is, without processing. You can control which static files
|
||||
are copied over with the ``STATIC_PATHS`` setting of the project's
|
||||
``pelicanconf.py`` file. Pelican's default configuration includes the
|
||||
``images`` directory for this, but others must be added manually. In addition,
|
||||
static files that are explicitly linked to are included (see below).
|
||||
|
||||
Mixed content in the same directory
|
||||
-----------------------------------
|
||||
|
||||
Starting with Pelican 3.5, static files can safely share a source directory
|
||||
with page source files, without exposing the page sources in the generated
|
||||
site. Any such directory must be added to both ``STATIC_PATHS`` and
|
||||
``PAGE_PATHS`` (or ``STATIC_PATHS`` and ``ARTICLE_PATHS``). Pelican will
|
||||
identify and process the page source files normally, and copy the remaining
|
||||
files as if they lived in a separate directory reserved for static files.
|
||||
|
||||
Note: Placing static and content source files together in the same source
|
||||
directory does not guarantee that they will end up in the same place in the
|
||||
generated site. The easiest way to do this is by using the ``{attach}`` link
|
||||
syntax (described below). Alternatively, the ``STATIC_SAVE_AS``,
|
||||
``PAGE_SAVE_AS``, and ``ARTICLE_SAVE_AS`` settings (and the corresponding
|
||||
``*_URL`` settings) can be configured to place files of different types
|
||||
together, just as they could in earlier versions of Pelican.
|
||||
|
||||
.. _ref-linking-to-internal-content:
|
||||
|
||||
Linking to internal content
|
||||
|
|
@ -205,13 +268,10 @@ and ``article2.md``::
|
|||
Linking to static files
|
||||
-----------------------
|
||||
|
||||
Linking to non-article or non-page content uses the same ``{filename}`` syntax
|
||||
as described above. It is important to remember that those files will not be
|
||||
copied to the output directory unless the source directories containing them
|
||||
are included in the ``STATIC_PATHS`` setting of the project's ``pelicanconf.py``
|
||||
file. Pelican's default configuration includes the ``images`` directory for
|
||||
this, but others must be added manually. Forgetting to do so will result in
|
||||
broken links.
|
||||
You can link to static content using ``{static}path/to/file``. Files linked to
|
||||
with this syntax will automatically be copied to the output directory, even if
|
||||
the source directories containing them are not included in the ``STATIC_PATHS``
|
||||
setting of the project's ``pelicanconf.py`` file.
|
||||
|
||||
For example, a project's content directory might be structured like this::
|
||||
|
||||
|
|
@ -225,48 +285,28 @@ For example, a project's content directory might be structured like this::
|
|||
|
||||
``test.md`` would include::
|
||||
|
||||
|
||||
[Our Menu]({filename}/pdfs/menu.pdf)
|
||||
|
||||
``pelicanconf.py`` would include::
|
||||
|
||||
STATIC_PATHS = ['images', 'pdfs']
|
||||
|
||||
[Our Menu]({static}/pdfs/menu.pdf)
|
||||
|
||||
Site generation would then copy ``han.jpg`` to ``output/images/han.jpg``,
|
||||
``menu.pdf`` to ``output/pdfs/menu.pdf``, and write the appropriate links
|
||||
in ``test.md``.
|
||||
|
||||
Mixed content in the same directory
|
||||
-----------------------------------
|
||||
|
||||
Starting with Pelican 3.5, static files can safely share a source directory with
|
||||
page source files, without exposing the page sources in the generated site.
|
||||
Any such directory must be added to both ``STATIC_PATHS`` and ``PAGE_PATHS``
|
||||
(or ``STATIC_PATHS`` and ``ARTICLE_PATHS``). Pelican will identify and process
|
||||
the page source files normally, and copy the remaining files as if they lived
|
||||
in a separate directory reserved for static files.
|
||||
|
||||
Note: Placing static and content source files together in the same source
|
||||
directory does not guarantee that they will end up in the same place in the
|
||||
generated site. The easiest way to do this is by using the ``{attach}`` link
|
||||
syntax (described below). Alternatively, the ``STATIC_SAVE_AS``,
|
||||
``PAGE_SAVE_AS``, and ``ARTICLE_SAVE_AS`` settings (and the corresponding
|
||||
``*_URL`` settings) can be configured to place files of different types
|
||||
together, just as they could in earlier versions of Pelican.
|
||||
If you use ``{static}`` to link to an article or a page, this will be turned
|
||||
into a link to its source code.
|
||||
|
||||
Attaching static files
|
||||
----------------------
|
||||
|
||||
Starting with Pelican 3.5, static files can be "attached" to a page or article
|
||||
using this syntax for the link target: ``{attach}path/to/file`` This works
|
||||
like the ``{filename}`` syntax, but also relocates the static file into the
|
||||
like the ``{static}`` syntax, but also relocates the static file into the
|
||||
linking document's output directory. If the static file originates from a
|
||||
subdirectory beneath the linking document's source, that relationship will be
|
||||
preserved on output. Otherwise, it will become a sibling of the linking
|
||||
document.
|
||||
|
||||
This only works for linking to static files, and only when they originate from
|
||||
a directory included in the ``STATIC_PATHS`` setting.
|
||||
This only works for linking to static files.
|
||||
|
||||
For example, a project's content directory might be structured like this::
|
||||
|
||||
|
|
@ -282,7 +322,6 @@ For example, a project's content directory might be structured like this::
|
|||
``pelicanconf.py`` would include::
|
||||
|
||||
PATH = 'content'
|
||||
STATIC_PATHS = ['blog', 'downloads']
|
||||
ARTICLE_PATHS = ['blog']
|
||||
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
|
||||
ARTICLE_URL = '{date:%Y}/{slug}.html'
|
||||
|
|
@ -312,7 +351,7 @@ the article's output directory.
|
|||
|
||||
If a static file is linked multiple times, the relocating feature of
|
||||
``{attach}`` will only work in the first of those links to be processed.
|
||||
After the first link, Pelican will treat ``{attach}`` like ``{filename}``.
|
||||
After the first link, Pelican will treat ``{attach}`` like ``{static}``.
|
||||
This avoids breaking the already-processed links.
|
||||
|
||||
**Be careful when linking to a file from multiple documents:**
|
||||
|
|
@ -326,7 +365,7 @@ file's old location might then find their links broken. **It is therefore
|
|||
advisable to use {attach} only if you use it in all links to a file, and only
|
||||
if the linking documents share a single directory.** Under these conditions,
|
||||
the file's output location will not change in future builds. In cases where
|
||||
these precautions are not possible, consider using ``{filename}`` links instead
|
||||
these precautions are not possible, consider using ``{static}`` links instead
|
||||
of ``{attach}``, and letting the file's location be determined by the project's
|
||||
``STATIC_SAVE_AS`` and ``STATIC_URL`` settings. (Per-file ``save_as`` and
|
||||
``url`` overrides can still be set in ``EXTRA_PATH_METADATA``.)
|
||||
|
|
@ -345,12 +384,49 @@ You can link to authors, categories, index and tags using the ``{author}name``,
|
|||
Deprecated internal link syntax
|
||||
-------------------------------
|
||||
|
||||
To remain compatible with earlier versions, Pelican still supports vertical bars
|
||||
(``||``) in addition to curly braces (``{}``) for internal links. For example:
|
||||
``|filename|an_article.rst``, ``|tag|tagname``, ``|category|foobar``.
|
||||
To remain compatible with earlier versions, Pelican still supports vertical
|
||||
bars (``||``) in addition to curly braces (``{}``) for internal links. 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. Support for the old syntax may eventually be
|
||||
removed.
|
||||
extensions or reST directives. Similarly, Pelican also still supports linking
|
||||
to static content with ``{filename}``. The syntax was changed to ``{static}``
|
||||
to allow linking to both generated articles and pages and their static sources.
|
||||
|
||||
Support for the old syntax may eventually be removed.
|
||||
|
||||
Including other files
|
||||
---------------------
|
||||
Both Markdown and reStructuredText syntaxes provide mechanisms for this.
|
||||
|
||||
Following below are some examples for **reStructuredText** using `the include directive`_:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. include:: file.rst
|
||||
|
||||
Include a fragment of a file delimited by two identifiers, highlighted as C++ (slicing based on line numbers is also possible):
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. include:: main.cpp
|
||||
:code: c++
|
||||
:start-after: // begin
|
||||
:end-before: // end
|
||||
|
||||
Include a raw HTML file (or an inline SVG) and put it directly into the output without any processing:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. raw:: html
|
||||
:file: table.html
|
||||
|
||||
For **Markdown**, one must rely on an extension. For example, using the `mdx_include plugin`_:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
```html
|
||||
{! template.html !}
|
||||
```
|
||||
|
||||
|
||||
Importing an existing site
|
||||
|
|
@ -375,8 +451,9 @@ of available translations for that article.
|
|||
language. For such advanced functionality the `i18n_subsites
|
||||
plugin`_ can be used.
|
||||
|
||||
Pelican uses the article's URL "slug" to determine if two or more articles are
|
||||
translations of one another. The slug can be set manually in the file's
|
||||
By default, Pelican uses the article's URL "slug" to determine if two or more
|
||||
articles are translations of one another. (This can be changed with the
|
||||
``ARTICLE_TRANSLATION_ID`` setting.) The slug can be set manually in the file's
|
||||
metadata; if not set explicitly, Pelican will auto-generate the slug from the
|
||||
title of the article.
|
||||
|
||||
|
|
@ -452,7 +529,7 @@ indenting both the identifier and the code::
|
|||
print("The path-less shebang syntax *will* show line numbers.")
|
||||
|
||||
The specified identifier (e.g. ``python``, ``ruby``) should be one that
|
||||
appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
|
||||
appears on the `list of available lexers <https://pygments.org/docs/lexers/>`_.
|
||||
|
||||
When using reStructuredText the following options are available in the
|
||||
code-block directive:
|
||||
|
|
@ -493,7 +570,7 @@ 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
|
||||
`Pygments documentation <https://pygments.org/docs/formatters/>`_ for more
|
||||
details on each of the options.
|
||||
|
||||
For example, the following code block enables line numbers, starting at 153,
|
||||
|
|
@ -522,13 +599,14 @@ 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
|
||||
metadata. That article will then be output to the ``drafts`` folder and not
|
||||
If you want to publish an article or a page as a draft (for friends to review
|
||||
before 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 or tag page.
|
||||
|
||||
If your articles should be automatically published as a draft (to not accidentally
|
||||
publish an article before it is finished) include the status in the ``DEFAULT_METADATA``::
|
||||
If your articles should be automatically published as a draft (to not
|
||||
accidentally publish an article before it is finished) include the status in
|
||||
the ``DEFAULT_METADATA``::
|
||||
|
||||
DEFAULT_METADATA = {
|
||||
'status': 'draft',
|
||||
|
|
@ -537,9 +615,11 @@ publish an article before it is finished) include the status in the ``DEFAULT_ME
|
|||
To publish a post when the default status is ``draft``, update the post's
|
||||
metadata to include ``Status: published``.
|
||||
|
||||
.. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime
|
||||
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
|
||||
.. _pelican-plugins: http://github.com/getpelican/pelican-plugins
|
||||
.. _Markdown Extensions: http://pythonhosted.org/Markdown/extensions/
|
||||
.. _CodeHilite extension: http://pythonhosted.org/Markdown/extensions/code_hilite.html#syntax
|
||||
.. _i18n_subsites plugin: http://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
|
||||
.. _W3C ISO 8601: https://www.w3.org/TR/NOTE-datetime
|
||||
.. _AsciiDoc: https://www.methods.co.nz/asciidoc/
|
||||
.. _pelican-plugins: https://github.com/getpelican/pelican-plugins
|
||||
.. _Markdown Extensions: https://python-markdown.github.io/extensions/
|
||||
.. _CodeHilite extension: https://python-markdown.github.io/extensions/code_hilite/#syntax
|
||||
.. _i18n_subsites plugin: https://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
|
||||
.. _the include directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#include
|
||||
.. _mdx_include plugin: https://github.com/neurobin/mdx_include
|
||||
|
|
|
|||
|
|
@ -7,138 +7,169 @@ can also help out by reviewing and commenting on
|
|||
`existing issues <https://github.com/getpelican/pelican/issues>`_.
|
||||
|
||||
Don't hesitate to fork Pelican and submit an issue or pull request on GitHub.
|
||||
When doing so, please adhere to the following guidelines.
|
||||
When doing so, please consider the following guidelines.
|
||||
|
||||
.. include:: ../CONTRIBUTING.rst
|
||||
|
||||
Setting up the development environment
|
||||
======================================
|
||||
|
||||
While there are many ways to set up one's development environment, following
|
||||
is a method that uses `virtualenv <http://www.virtualenv.org/>`_. If you don't
|
||||
have ``virtualenv`` installed, you can install it via::
|
||||
While there are many ways to set up one's development environment, the following
|
||||
instructions will utilize Pip_ and Poetry_. These tools facilitate managing
|
||||
virtual environments for separate Python projects that are isolated from one
|
||||
another, so you can use different packages (and package versions) for each.
|
||||
|
||||
$ pip install virtualenv
|
||||
Please note that Python 3.6+ is required for Pelican development.
|
||||
|
||||
Virtual environments allow you to work on Python projects which are isolated
|
||||
from one another so you can use different packages (and package versions) with
|
||||
different projects.
|
||||
*(Optional)* If you prefer to install Poetry once for use with multiple projects,
|
||||
you can install it via::
|
||||
|
||||
To create and activate a virtual environment, use the following syntax::
|
||||
curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
|
||||
|
||||
$ virtualenv ~/virtualenvs/pelican
|
||||
$ cd ~/virtualenvs/pelican
|
||||
$ . bin/activate
|
||||
Point your web browser to the `Pelican repository`_ and tap the **Fork** button
|
||||
at top-right. Then clone the source for your fork and add the upstream project
|
||||
as a Git remote::
|
||||
|
||||
To clone the Pelican source::
|
||||
mkdir ~/projects
|
||||
git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican
|
||||
cd ~/projects/pelican
|
||||
git remote add upstream https://github.com/getpelican/pelican.git
|
||||
|
||||
$ git clone https://github.com/getpelican/pelican.git src/pelican
|
||||
While Poetry can dynamically create and manage virtual environments, we're going
|
||||
to manually create and activate a virtual environment::
|
||||
|
||||
To install the development dependencies::
|
||||
mkdir ~/virtualenvs
|
||||
python3 -m venv ~/virtualenvs/pelican
|
||||
source ~/virtualenvs/pelican/bin/activate
|
||||
|
||||
$ cd src/pelican
|
||||
$ pip install -r requirements/developer.pip
|
||||
Install the needed dependencies and set up the project::
|
||||
|
||||
To install Pelican and its dependencies::
|
||||
pip install -e ~/projects/pelican invoke
|
||||
invoke setup
|
||||
|
||||
$ python setup.py develop
|
||||
Your local environment should now be ready to go!
|
||||
|
||||
Or using ``pip``::
|
||||
.. _Pip: https://pip.pypa.io/
|
||||
.. _Poetry: https://poetry.eustace.io/docs/#installation
|
||||
.. _Pelican repository: https://github.com/getpelican/pelican
|
||||
|
||||
$ pip install -e .
|
||||
Development
|
||||
===========
|
||||
|
||||
To conveniently test on multiple Python versions, we also provide a .tox file.
|
||||
Once Pelican has been set up for local development, create a topic branch for
|
||||
your bug fix or feature::
|
||||
|
||||
git checkout -b name-of-your-bugfix-or-feature
|
||||
|
||||
Building the docs
|
||||
=================
|
||||
|
||||
If you make changes to the documentation, you should preview your changes
|
||||
before committing them::
|
||||
|
||||
$ pip install -r requirements/docs.pip
|
||||
$ cd src/pelican/docs
|
||||
$ make html
|
||||
|
||||
Open ``_build/html/index.html`` in your browser to preview the documentation.
|
||||
Now you can make changes to Pelican, its documentation, and/or other aspects of
|
||||
the project.
|
||||
|
||||
Running the test suite
|
||||
======================
|
||||
----------------------
|
||||
|
||||
Each time you add a feature, there are two things to do regarding tests:
|
||||
check that the existing tests pass, and add tests for the new feature
|
||||
or bugfix.
|
||||
Each time you make changes to Pelican, there are two things to do regarding
|
||||
tests: check that the existing tests pass, and add tests for any new features
|
||||
or bug fixes. The tests are located in ``pelican/tests``, and you can run them
|
||||
via::
|
||||
|
||||
The tests live in ``pelican/tests`` and you can run them using the
|
||||
"discover" feature of ``unittest``::
|
||||
invoke tests
|
||||
|
||||
$ python -Wd -m unittest discover
|
||||
In addition to running the test suite, the above invocation will also check code
|
||||
style and let you know whether non-conforming patterns were found. In some cases
|
||||
these linters will make the needed changes directly, while in other cases you
|
||||
may need to make additional changes until ``invoke tests`` no longer reports any
|
||||
code style violations.
|
||||
|
||||
After making your changes and running the tests, you may see a test failure
|
||||
mentioning that "some generated files differ from the expected functional tests
|
||||
output." If you have made changes that affect the HTML output generated by
|
||||
Pelican, and the changes to that output are expected and deemed correct given
|
||||
the nature of your changes, then you should update the output used by the
|
||||
functional tests. To do so, **make sure you have both ``en_EN.utf8`` and
|
||||
``fr_FR.utf8`` locales installed**, and then run the following two commands::
|
||||
functional tests. To do so, **make sure you have both** ``en_EN.utf8`` **and**
|
||||
``fr_FR.utf8`` **locales installed**, and then run the following command::
|
||||
|
||||
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
|
||||
-s samples/pelican.conf.py samples/content/
|
||||
$ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
|
||||
-s samples/pelican.conf_FR.py samples/content/
|
||||
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
|
||||
samples/content/
|
||||
invoke update-functional-tests
|
||||
|
||||
Testing on Python 2 and 3
|
||||
-------------------------
|
||||
You may also find that some tests are skipped because some dependency (e.g.,
|
||||
Pandoc) is not installed. This does not automatically mean that these tests
|
||||
have passed; you should at least verify that any skipped tests are not affected
|
||||
by your changes.
|
||||
|
||||
Testing on Python 3 currently requires some extra steps: installing
|
||||
Python 3-compatible versions of dependent packages and plugins.
|
||||
You should run the test suite under each of the supported versions of Python.
|
||||
This is best done by creating a separate Python environment for each version.
|
||||
Tox_ is a useful tool to automate running tests inside ``virtualenv``
|
||||
environments.
|
||||
|
||||
Tox_ is a useful tool to run tests on both versions. It will install the
|
||||
Python 3-compatible version of dependent packages.
|
||||
.. _Tox: https://tox.readthedocs.io/en/latest/
|
||||
|
||||
.. _Tox: http://testrun.org/tox/latest/
|
||||
Building the docs
|
||||
-----------------
|
||||
|
||||
Python 3 development tips
|
||||
=========================
|
||||
If you make changes to the documentation, you should build and inspect your
|
||||
changes before committing them::
|
||||
|
||||
Here are some tips that may be useful when doing some code for both Python 2.7
|
||||
and Python 3 at the same time:
|
||||
invoke docserve
|
||||
|
||||
- Assume every string and literal is unicode (import unicode_literals):
|
||||
Open http://localhost:8000 in your browser to review the documentation. While
|
||||
the above task is running, any changes you make and save to the documentation
|
||||
should automatically appear in the browser, as it live-reloads when it detects
|
||||
changes to the documentation source files.
|
||||
|
||||
- Do not use prefix ``u'``.
|
||||
- Do not encode/decode strings in the middle of sth. Follow the code to the
|
||||
source (or target) of a string and encode/decode at the first/last possible
|
||||
point.
|
||||
- In other words, write your functions to expect and to return unicode.
|
||||
- Encode/decode strings if e.g. the source is a Python function that is known
|
||||
to handle this badly, e.g. strftime() in Python 2.
|
||||
Plugin development
|
||||
------------------
|
||||
|
||||
- Use new syntax: print function, "except ... *as* e" (not comma) etc.
|
||||
- Refactor method calls like ``dict.iteritems()``, ``xrange()`` etc. in a way
|
||||
that runs without code change in both Python versions.
|
||||
- Do not use magic method ``__unicode()__`` in new classes. Use only ``__str()__``
|
||||
and decorate the class with ``@python_2_unicode_compatible``.
|
||||
- Do not start int literals with a zero. This is a syntax error in Py3k.
|
||||
- Unfortunately I did not find an octal notation that is valid in both
|
||||
Pythons. Use decimal instead.
|
||||
- use six, e.g.:
|
||||
To create a *new* Pelican plugin, please refer to the `plugin template`_
|
||||
repository for detailed instructions.
|
||||
|
||||
- ``isinstance(.., basestring) -> isinstance(.., six.string_types)``
|
||||
- ``isinstance(.., unicode) -> isinstance(.., six.text_type)``
|
||||
If you want to contribute to an *existing* Pelican plugin, follow the steps
|
||||
above to set up Pelican for local development, and then create a directory to
|
||||
store cloned plugin repositories::
|
||||
|
||||
- ``setlocale()`` in Python 2 bails when we give the locale name as unicode,
|
||||
and since we are using ``from __future__ import unicode_literals``, we do
|
||||
that everywhere! As a workaround, I enclosed the localename with ``str()``;
|
||||
in Python 2 this casts the name to a byte string, in Python 3 this should do
|
||||
nothing, because the locale name already had been unicode.
|
||||
mkdir -p ~/projects/pelican-plugins
|
||||
|
||||
- Kept range() almost everywhere as-is (2to3 suggests list(range())), just
|
||||
changed it where I felt necessary.
|
||||
Assuming you wanted to contribute to the Simple Footnotes plugin, you would
|
||||
first browse to the `Simple Footnotes`_ repository on GitHub and tap the **Fork**
|
||||
button at top-right. Then clone the source for your fork and add the upstream
|
||||
project as a Git remote::
|
||||
|
||||
- Changed xrange() back to range(), so it is valid in both Python versions.
|
||||
git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes
|
||||
cd ~/projects/pelican-plugins/simple-footnotes
|
||||
git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git
|
||||
|
||||
Install the needed dependencies and set up the project::
|
||||
|
||||
invoke setup
|
||||
|
||||
Create a topic branch for your plugin bug fix or feature::
|
||||
|
||||
git checkout -b name-of-your-bugfix-or-feature
|
||||
|
||||
After writing new tests for your plugin changes, run the plugin test suite::
|
||||
|
||||
invoke tests
|
||||
|
||||
.. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin
|
||||
.. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes
|
||||
|
||||
Submitting your changes
|
||||
-----------------------
|
||||
|
||||
Assuming linting validation and tests pass, add a ``RELEASE.md`` file in the root
|
||||
of the project that contains the release type (major, minor, patch) and a
|
||||
summary of the changes that will be used as the release changelog entry.
|
||||
For example::
|
||||
|
||||
Release type: patch
|
||||
|
||||
Fix browser reloading upon changes to content, settings, or theme
|
||||
|
||||
Commit your changes and push your topic branch::
|
||||
|
||||
git add .
|
||||
git commit -m "Your detailed description of your changes"
|
||||
git push origin name-of-your-bugfix-or-feature
|
||||
|
||||
Finally, browse to your repository fork on GitHub and submit a pull request.
|
||||
|
||||
|
||||
Logging tips
|
||||
|
|
@ -156,8 +187,8 @@ For logging messages that are not repeated, use the usual Python way::
|
|||
logger.warning("A warning with %s formatting", arg_to_be_formatted)
|
||||
|
||||
Do not format log messages yourself. Use ``%s`` formatting in messages and pass
|
||||
arguments to logger. This is important, because Pelican logger will preprocess
|
||||
some arguments (like Exceptions) for Py2/Py3 compatibility.
|
||||
arguments to logger. This is important, because the Pelican logger will
|
||||
preprocess some arguments, such as exceptions.
|
||||
|
||||
Limiting extraneous log messages
|
||||
--------------------------------
|
||||
|
|
@ -173,9 +204,9 @@ Optionally, you can also set ``'limit_args'`` as a tuple of arguments in
|
|||
``extra`` dict if your generic message needs formatting.
|
||||
|
||||
Limit is set to ``5``, i.e, first four logs with the same ``'limit_msg'`` are
|
||||
outputted normally but the fifth one will be logged using
|
||||
``'limit_msg'`` (and ``'limit_args'`` if present). After the fifth,
|
||||
corresponding log messages will be ignored.
|
||||
outputted normally but the fifth one will be logged using ``'limit_msg'`` (and
|
||||
``'limit_args'`` if present). After the fifth, corresponding log messages will
|
||||
be ignored.
|
||||
|
||||
For example, if you want to log missing resources, use the following code::
|
||||
|
||||
|
|
|
|||
119
docs/faq.rst
119
docs/faq.rst
|
|
@ -12,10 +12,10 @@ 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 (preferred) or the
|
||||
`issue tracker <https://github.com/getpelican/pelican/issues>`_. If submitting
|
||||
an issue report, please first check the existing issue list (both open and
|
||||
closed) in order to avoid submitting a duplicate issue.
|
||||
suggestions or problems you might have via IRC (preferred) or the `issue
|
||||
tracker <https://github.com/getpelican/pelican/issues>`_. If submitting an
|
||||
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
|
||||
|
|
@ -35,10 +35,10 @@ via the command line. See ``pelican --help`` for more information.
|
|||
Changes to the settings file take no effect
|
||||
===========================================
|
||||
|
||||
When experimenting with different settings (especially the metadata
|
||||
ones) caching may interfere and the changes may not be visible. In
|
||||
such cases, ensure that caching is disabled via ``LOAD_CONTENT_CACHE = False``
|
||||
or use the ``--ignore-cache`` command-line switch.
|
||||
When experimenting with different settings (especially the metadata ones)
|
||||
caching may interfere and the changes may not be visible. In such cases, ensure
|
||||
that caching is disabled via ``LOAD_CONTENT_CACHE = False`` or use the
|
||||
``--ignore-cache`` command-line switch.
|
||||
|
||||
I'm creating my own theme. How do I use Pygments for syntax highlighting?
|
||||
=========================================================================
|
||||
|
|
@ -48,7 +48,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/>`_.
|
||||
`Pygments project demo site <https://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
|
||||
|
|
@ -70,9 +70,9 @@ I want to use Markdown, but I got an error.
|
|||
If you try to generate Markdown content without first installing the Markdown
|
||||
library, may see a message that says ``No valid files found in content``.
|
||||
Markdown is not a hard dependency for Pelican, so if you have content in
|
||||
Markdown format, you will need to explicitly install the Markdown library.
|
||||
You can do so by typing the following command, prepending ``sudo`` if
|
||||
permissions require it::
|
||||
Markdown format, you will need to explicitly install the Markdown library. You
|
||||
can do so by typing the following command, prepending ``sudo`` if permissions
|
||||
require it::
|
||||
|
||||
pip install markdown
|
||||
|
||||
|
|
@ -150,9 +150,9 @@ the ``'index'`` direct template.
|
|||
What if I want to disable feed generation?
|
||||
==========================================
|
||||
|
||||
To disable feed generation, all feed settings should be set to ``None``.
|
||||
All but three feed settings already default to ``None``, so if you want to
|
||||
disable all feed generation, you only need to specify the following settings::
|
||||
To disable feed generation, all feed settings should be set to ``None``. All
|
||||
but three feed settings already default to ``None``, so if you want to disable
|
||||
all feed generation, you only need to specify the following settings::
|
||||
|
||||
FEED_ALL_ATOM = None
|
||||
CATEGORY_FEED_ATOM = None
|
||||
|
|
@ -167,9 +167,9 @@ I'm getting a warning about feeds generated without SITEURL being set properly
|
|||
==============================================================================
|
||||
|
||||
`RSS and Atom feeds require all URL links to be absolute
|
||||
<http://validator.w3.org/feed/docs/rss2.html#comments>`_.
|
||||
In order to properly generate links in Pelican you will need to set ``SITEURL``
|
||||
to the full path of your site.
|
||||
<https://validator.w3.org/feed/docs/rss2.html#comments>`_. In order to properly
|
||||
generate links in Pelican you will need to set ``SITEURL`` to the full path of
|
||||
your site.
|
||||
|
||||
Feeds are still generated when this warning is displayed, but links within may
|
||||
be malformed and thus the feed may not validate.
|
||||
|
|
@ -185,26 +185,26 @@ setting names). Here is an exact list of the renamed settings::
|
|||
TAG_FEED -> TAG_FEED_ATOM
|
||||
CATEGORY_FEED -> CATEGORY_FEED_ATOM
|
||||
|
||||
Starting in 3.1, the new feed ``FEED_ALL_ATOM`` has been introduced: this
|
||||
feed will aggregate all posts regardless of their language. This setting
|
||||
generates ``'feeds/all.atom.xml'`` by default and ``FEED_ATOM`` now defaults to
|
||||
``None``. The following feed setting has also been renamed::
|
||||
Starting in 3.1, the new feed ``FEED_ALL_ATOM`` has been introduced: this feed
|
||||
will aggregate all posts regardless of their language. This setting generates
|
||||
``'feeds/all.atom.xml'`` by default and ``FEED_ATOM`` now defaults to ``None``.
|
||||
The following feed setting has also been renamed::
|
||||
|
||||
TRANSLATION_FEED -> TRANSLATION_FEED_ATOM
|
||||
|
||||
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
|
||||
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::
|
||||
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 = ''
|
||||
|
|
@ -212,52 +212,49 @@ You can also disable generation of tag-related pages via::
|
|||
Why does Pelican always write all HTML files even with content caching enabled?
|
||||
===============================================================================
|
||||
|
||||
In order to reliably determine whether the HTML output is different
|
||||
before writing it, a large part of the generation environment
|
||||
including the template contexts, imported plugins, etc. would have to
|
||||
be saved and compared, at least in the form of a hash (which would
|
||||
require special handling of unhashable types), because of all the
|
||||
possible combinations of plugins, pagination, etc. which may change in
|
||||
many different ways. This would require a lot more processing time
|
||||
and memory and storage space. Simply writing the files each time is a
|
||||
lot faster and a lot more reliable.
|
||||
In order to reliably determine whether the HTML output is different before
|
||||
writing it, a large part of the generation environment including the template
|
||||
contexts, imported plugins, etc. would have to be saved and compared, at least
|
||||
in the form of a hash (which would require special handling of unhashable
|
||||
types), because of all the possible combinations of plugins, pagination, etc.
|
||||
which may change in many different ways. This would require a lot more
|
||||
processing time and memory and storage space. Simply writing the files each
|
||||
time is a lot faster and a lot more reliable.
|
||||
|
||||
However, this means that the modification time of the files changes
|
||||
every time, so a ``rsync`` based upload will transfer them even if
|
||||
their content hasn't changed. A simple solution is to make ``rsync``
|
||||
use the ``--checksum`` option, which will make it compare the file
|
||||
checksums in a much faster way than Pelican would.
|
||||
However, this means that the modification time of the files changes every time,
|
||||
so a ``rsync`` based upload will transfer them even if their content hasn't
|
||||
changed. A simple solution is to make ``rsync`` use the ``--checksum`` option,
|
||||
which will make it compare the file checksums in a much faster way than Pelican
|
||||
would.
|
||||
|
||||
When only several specific output files are of interest (e.g. when
|
||||
working on some specific page or the theme templates), the
|
||||
`WRITE_SELECTED` option may help, see
|
||||
:ref:`writing_only_selected_content`.
|
||||
When only several specific output files are of interest (e.g. when working on
|
||||
some specific page or the theme templates), the `WRITE_SELECTED` option may
|
||||
help, see :ref:`writing_only_selected_content`.
|
||||
|
||||
How to process only a subset of all articles?
|
||||
=============================================
|
||||
|
||||
It is often useful to process only e.g. 10 articles for debugging
|
||||
purposes. This can be achieved by explicitly specifying only the
|
||||
filenames of those articles in ``ARTICLE_PATHS``. A list of such
|
||||
filenames could be found using a command similar to ``cd content;
|
||||
find -name '*.md' | head -n 10``.
|
||||
It is often useful to process only e.g. 10 articles for debugging purposes.
|
||||
This can be achieved by explicitly specifying only the filenames of those
|
||||
articles in ``ARTICLE_PATHS``. A list of such filenames could be found using a
|
||||
command similar to ``cd content; find -name '*.md' | head -n 10``.
|
||||
|
||||
My tag-cloud is missing/broken since I upgraded Pelican
|
||||
=======================================================
|
||||
|
||||
In an ongoing effort to steamline Pelican, `tag_cloud` generation has been
|
||||
moved out of the pelican core and into a separate `plugin
|
||||
<https://github.com/getpelican/pelican-plugins/tree/master/tag_cloud>`_.
|
||||
See the :ref:`plugins` documentation further information about the
|
||||
Pelican plugin system.
|
||||
<https://github.com/getpelican/pelican-plugins/tree/master/tag_cloud>`_. See
|
||||
the :ref:`plugins` documentation further information about the Pelican plugin
|
||||
system.
|
||||
|
||||
Since I upgraded Pelican my pages are no longer rendered
|
||||
========================================================
|
||||
|
||||
Pages were available to themes as lowercase ``pages`` and uppercase
|
||||
``PAGES``. To bring this inline with the :ref:`templates-variables` section,
|
||||
``PAGES`` has been removed. This is quickly resolved by updating your theme
|
||||
to iterate over ``pages`` instead of ``PAGES``. Just replace::
|
||||
Pages were available to themes as lowercase ``pages`` and uppercase ``PAGES``.
|
||||
To bring this inline with the :ref:`templates-variables` section, ``PAGES`` has
|
||||
been removed. This is quickly resolved by updating your theme to iterate over
|
||||
``pages`` instead of ``PAGES``. Just replace::
|
||||
|
||||
{% for pg in PAGES %}
|
||||
|
||||
|
|
@ -271,8 +268,8 @@ How can I stop Pelican from trying to parse my static files as content?
|
|||
Pelican's article and page generators run before it's static generator. That
|
||||
means if you use a setup similar to the default configuration, where a static
|
||||
source directory is defined inside a ``*_PATHS`` setting, all files that have a
|
||||
valid content file ending (``.html``, ``.rst``, ``.md``, ...) will be treated as
|
||||
articles or pages before they get treated as static files.
|
||||
valid content file ending (``.html``, ``.rst``, ``.md``, ...) will be treated
|
||||
as articles or pages before they get treated as static files.
|
||||
|
||||
To circumvent this issue either use the appropriate ``*_EXCLUDES`` setting or
|
||||
disable the offending reader via ``READERS`` if you don't need it.
|
||||
|
|
|
|||
|
|
@ -9,30 +9,38 @@ Description
|
|||
``pelican-import`` is a command-line tool for converting articles from other
|
||||
software to reStructuredText or Markdown. The supported import formats are:
|
||||
|
||||
- WordPress XML export
|
||||
- Blogger XML export
|
||||
- Dotclear export
|
||||
- Posterous API
|
||||
- Tumblr API
|
||||
- WordPress XML export
|
||||
- RSS/Atom feed
|
||||
|
||||
The conversion from HTML to reStructuredText or Markdown relies on `Pandoc`_.
|
||||
For Dotclear, if the source posts are written with Markdown syntax, they will
|
||||
not be converted (as Pelican also supports Markdown).
|
||||
|
||||
.. note::
|
||||
|
||||
Unlike Pelican, Wordpress supports multiple categories per article. These
|
||||
are imported as a comma-separated string. You have to resolve these
|
||||
manually, or use a plugin that enables multiple categories per article
|
||||
(like `more_categories`_).
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
``pelican-import`` has some dependencies not required by the rest of Pelican:
|
||||
|
||||
- *BeautifulSoup4* and *lxml*, for WordPress and Dotclear import. Can be installed like
|
||||
any other Python package (``pip install BeautifulSoup4 lxml``).
|
||||
- *BeautifulSoup4* and *lxml*, for WordPress and Dotclear import. Can be
|
||||
installed like any other Python package (``pip install BeautifulSoup4
|
||||
lxml``).
|
||||
- *Feedparser*, for feed import (``pip install feedparser``).
|
||||
- *Pandoc*, see the `Pandoc site`_ for installation instructions on your
|
||||
operating system.
|
||||
|
||||
.. _Pandoc: http://johnmacfarlane.net/pandoc/
|
||||
.. _Pandoc site: http://johnmacfarlane.net/pandoc/installing.html
|
||||
.. _Pandoc: https://pandoc.org/
|
||||
.. _Pandoc site: https://pandoc.org/installing.html
|
||||
|
||||
|
||||
Usage
|
||||
|
|
@ -40,9 +48,9 @@ Usage
|
|||
|
||||
::
|
||||
|
||||
pelican-import [-h] [--wpfile] [--dotclear] [--posterous] [--tumblr] [--feed] [-o OUTPUT]
|
||||
[-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--disable-slugs]
|
||||
[-e EMAIL] [-p PASSWORD] [-b BLOGNAME]
|
||||
pelican-import [-h] [--blogger] [--dotclear] [--posterous] [--tumblr] [--wpfile] [--feed]
|
||||
[-o OUTPUT] [-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--wp-custpost]
|
||||
[--wp-attach] [--disable-slugs] [-e EMAIL] [-p PASSWORD] [-b BLOGNAME]
|
||||
input|api_token|api_key
|
||||
|
||||
Positional arguments
|
||||
|
|
@ -50,31 +58,45 @@ Positional arguments
|
|||
============= ============================================================================
|
||||
``input`` The input file to read
|
||||
``api_token`` (Posterous only) api_token can be obtained from http://posterous.com/api/
|
||||
``api_key`` (Tumblr only) api_key can be obtained from http://www.tumblr.com/oauth/apps
|
||||
``api_key`` (Tumblr only) api_key can be obtained from https://www.tumblr.com/oauth/apps
|
||||
============= ============================================================================
|
||||
|
||||
Optional arguments
|
||||
------------------
|
||||
|
||||
-h, --help Show this help message and exit
|
||||
--wpfile WordPress XML export (default: False)
|
||||
--blogger Blogger XML export (default: False)
|
||||
--dotclear Dotclear export (default: False)
|
||||
--posterous Posterous API (default: False)
|
||||
--tumblr Tumblr API (default: False)
|
||||
--wpfile WordPress XML export (default: False)
|
||||
--feed Feed to parse (default: False)
|
||||
-o OUTPUT, --output OUTPUT
|
||||
Output path (default: output)
|
||||
Output path (default: content)
|
||||
-m MARKUP, --markup MARKUP
|
||||
Output markup format (supports rst & markdown)
|
||||
(default: rst)
|
||||
--dir-cat Put files in directories with categories name
|
||||
(default: False)
|
||||
--dir-page Put files recognised as pages in "pages/" sub-
|
||||
directory (wordpress import only) (default: False)
|
||||
--filter-author Import only post from the specified author.
|
||||
directory (blogger and wordpress import only)
|
||||
(default: False)
|
||||
--filter-author Import only post from the specified author
|
||||
--strip-raw Strip raw HTML code that can't be converted to markup
|
||||
such as flash embeds or iframes (wordpress import
|
||||
only) (default: False)
|
||||
--wp-custpost Put wordpress custom post types in directories. If
|
||||
used with --dir-cat option directories will be created
|
||||
as "/post_type/category/" (wordpress import only)
|
||||
--wp-attach Download files uploaded to wordpress as attachments.
|
||||
Files will be added to posts as a list in the post
|
||||
header and links to the files within the post will be
|
||||
updated. All files will be downloaded, even if they
|
||||
aren't associated with a post. Files will be downloaded
|
||||
with their original path inside the output directory,
|
||||
e.g. "output/wp-uploads/date/postname/file.jpg".
|
||||
(wordpress import only) (requires an internet
|
||||
connection)
|
||||
--disable-slugs Disable storing slugs from imported posts within
|
||||
output. With this disabled, your Pelican URLs may not
|
||||
be consistent with your original posts. (default:
|
||||
|
|
@ -90,9 +112,9 @@ Optional arguments
|
|||
Examples
|
||||
========
|
||||
|
||||
For WordPress::
|
||||
For Blogger::
|
||||
|
||||
$ pelican-import --wpfile -o ~/output ~/posts.xml
|
||||
$ pelican-import --blogger -o ~/output ~/posts.xml
|
||||
|
||||
For Dotclear::
|
||||
|
||||
|
|
@ -106,10 +128,16 @@ For Tumblr::
|
|||
|
||||
$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_token>
|
||||
|
||||
For WordPress::
|
||||
|
||||
$ pelican-import --wpfile -o ~/output ~/posts.xml
|
||||
|
||||
Tests
|
||||
=====
|
||||
|
||||
To test the module, one can use sample files:
|
||||
|
||||
- for WordPress: http://wpcandy.com/made/the-sample-post-collection
|
||||
- for WordPress: https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
|
||||
- for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt
|
||||
|
||||
.. _more_categories: https://github.com/getpelican/pelican-plugins/tree/master/more_categories
|
||||
|
|
@ -6,14 +6,14 @@ Pelican |release|
|
|||
|
||||
.. warning::
|
||||
|
||||
This documentation is for the version of Pelican currently under development.
|
||||
Were you looking for version |last_stable| documentation?
|
||||
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_. Highlights include:
|
||||
|
||||
* Write your content directly with your editor of choice
|
||||
in reStructuredText_ or Markdown_ formats
|
||||
* Write your content directly with your editor of choice in reStructuredText_
|
||||
or Markdown_ formats
|
||||
* Includes a simple CLI tool to (re)generate your site
|
||||
* Easy to interface with distributed version control systems and web hooks
|
||||
* Completely static output is easy to host anywhere
|
||||
|
|
@ -76,10 +76,10 @@ Documentation
|
|||
|
||||
.. Links
|
||||
|
||||
.. _Python: http://www.python.org/
|
||||
.. _Python: https://www.python.org/
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _Markdown: http://daringfireball.net/projects/markdown/
|
||||
.. _Jinja2: http://jinja.pocoo.org/
|
||||
.. _`Pelican documentation`: http://docs.getpelican.com/latest/
|
||||
.. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
|
||||
.. _Markdown: https://daringfireball.net/projects/markdown/
|
||||
.. _Jinja2: https://palletsprojects.com/p/jinja/
|
||||
.. _`Pelican documentation`: https://docs.getpelican.com/latest/
|
||||
.. _`Pelican's internals`: https://docs.getpelican.com/en/latest/internals.html
|
||||
.. _`Pelican plugins`: https://github.com/getpelican/pelican-plugins
|
||||
|
|
|
|||
|
|
@ -1,19 +1,23 @@
|
|||
Installing Pelican
|
||||
##################
|
||||
|
||||
Pelican currently runs best on Python 2.7.x and 3.3+; earlier versions of
|
||||
Pelican currently runs best on Python 2.7.x and 3.5+; earlier versions of
|
||||
Python are not supported.
|
||||
|
||||
You can install Pelican via several different methods. The simplest is via
|
||||
`pip <http://www.pip-installer.org/>`_::
|
||||
`pip <https://pip.pypa.io/en/stable/>`_::
|
||||
|
||||
pip install pelican
|
||||
|
||||
Or, if you plan on using Markdown::
|
||||
|
||||
pip install pelican[Markdown]
|
||||
|
||||
(Keep in mind that operating systems will often require you to prefix the above
|
||||
command with ``sudo`` in order to install Pelican system-wide.)
|
||||
|
||||
While the above is the simplest method, the recommended approach is to create
|
||||
a virtual environment for Pelican via virtualenv_ before installing Pelican.
|
||||
While the above is the simplest method, the recommended approach is to create a
|
||||
virtual environment for Pelican via virtualenv_ before installing Pelican.
|
||||
Assuming you have virtualenv_ installed, you can then open a new terminal
|
||||
session and create a new virtual environment for Pelican::
|
||||
|
||||
|
|
@ -22,9 +26,8 @@ session and create a new virtual environment for Pelican::
|
|||
source bin/activate
|
||||
|
||||
Once the virtual environment has been created and activated, Pelican can be
|
||||
installed via ``pip install pelican`` as noted above. Alternatively, if
|
||||
you have the project source, you can install Pelican using the distutils
|
||||
method::
|
||||
installed via ``pip install pelican`` as noted above. Alternatively, if you
|
||||
have the project source, you can install Pelican using the distutils method::
|
||||
|
||||
cd path-to-Pelican-source
|
||||
python setup.py install
|
||||
|
|
@ -40,13 +43,17 @@ options. For more detail, refer to the :doc:`Publish<publish>` section.
|
|||
Optional packages
|
||||
-----------------
|
||||
|
||||
If you plan on using `Markdown <http://pypi.python.org/pypi/Markdown>`_ as a
|
||||
markup format, you'll need to install the Markdown library::
|
||||
If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as a
|
||||
markup format, you can install Pelican with Markdown support::
|
||||
|
||||
pip install pelican[Markdown]
|
||||
|
||||
Or you might need to install it a posteriori::
|
||||
|
||||
pip install Markdown
|
||||
|
||||
Typographical enhancements can be enabled in your settings file, but first the
|
||||
requisite `Typogrify <http://pypi.python.org/pypi/typogrify>`_ library must be
|
||||
requisite `Typogrify <https://pypi.org/project/typogrify/>`_ library must be
|
||||
installed::
|
||||
|
||||
pip install typogrify
|
||||
|
|
@ -57,22 +64,22 @@ Dependencies
|
|||
When Pelican is installed, the following dependent Python packages should be
|
||||
automatically installed without any action on your part:
|
||||
|
||||
* `feedgenerator <http://pypi.python.org/pypi/feedgenerator>`_, to generate the
|
||||
* `feedgenerator <https://pypi.org/project/feedgenerator/>`_, to generate the
|
||||
Atom feeds
|
||||
* `jinja2 <http://pypi.python.org/pypi/Jinja2>`_, for templating support
|
||||
* `pygments <http://pypi.python.org/pypi/Pygments>`_, for syntax highlighting
|
||||
* `docutils <http://pypi.python.org/pypi/docutils>`_, for supporting
|
||||
* `jinja2 <https://pypi.org/project/Jinja2/>`_, for templating support
|
||||
* `pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting
|
||||
* `docutils <https://pypi.org/project/docutils/>`_, for supporting
|
||||
reStructuredText as an input format
|
||||
* `pytz <http://pypi.python.org/pypi/pytz>`_, for timezone definitions
|
||||
* `blinker <http://pypi.python.org/pypi/blinker>`_, an object-to-object and
|
||||
* `pytz <https://pypi.org/project/pytz/>`_, for timezone definitions
|
||||
* `blinker <https://pypi.org/project/blinker/>`_, an object-to-object and
|
||||
broadcast signaling system
|
||||
* `unidecode <http://pypi.python.org/pypi/Unidecode>`_, for ASCII
|
||||
* `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
|
||||
transliterations of Unicode text
|
||||
* `six <http://pypi.python.org/pypi/six>`_, for Python 2 and 3 compatibility
|
||||
* `six <https://pypi.org/project/six/>`_, for Python 2 and 3 compatibility
|
||||
utilities
|
||||
* `MarkupSafe <http://pypi.python.org/pypi/MarkupSafe>`_, for a markup safe
|
||||
* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup safe
|
||||
string implementation
|
||||
* `python-dateutil <https://pypi.python.org/pypi/python-dateutil>`_, to read
|
||||
* `python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read
|
||||
the date metadata
|
||||
|
||||
Upgrading
|
||||
|
|
@ -95,16 +102,23 @@ your site::
|
|||
|
||||
pelican-quickstart
|
||||
|
||||
If run inside an activated virtual environment, ``pelican-quickstart`` will
|
||||
look for an associated project path inside ``$VIRTUAL_ENV/.project``. If that
|
||||
file exists and contains a valid directory path, the new Pelican project will
|
||||
be saved at that location. Otherwise, the default is the current working
|
||||
directory. To set the new project path on initial invocation, use:
|
||||
``pelican-quickstart --path /your/desired/directory``
|
||||
|
||||
Once you finish answering all the questions, your project will consist of the
|
||||
following hierarchy (except for *pages* — shown in parentheses below — which you
|
||||
can optionally add yourself if you plan to create non-chronological content)::
|
||||
following hierarchy (except for *pages* — shown in parentheses below — which
|
||||
you can optionally add yourself if you plan to create non-chronological
|
||||
content)::
|
||||
|
||||
yourproject/
|
||||
├── content
|
||||
│ └── (pages)
|
||||
│ └── (pages)
|
||||
├── output
|
||||
├── develop_server.sh
|
||||
├── fabfile.py
|
||||
├── tasks.py
|
||||
├── Makefile
|
||||
├── pelicanconf.py # Main settings file
|
||||
└── publishconf.py # Settings to use when ready to publish
|
||||
|
|
@ -112,4 +126,4 @@ can optionally add yourself if you plan to create non-chronological content)::
|
|||
The next step is to begin to adding content to the *content* folder that has
|
||||
been created for you.
|
||||
|
||||
.. _virtualenv: http://www.virtualenv.org/
|
||||
.. _virtualenv: https://virtualenv.pypa.io/en/latest/
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
Pelican internals
|
||||
#################
|
||||
|
||||
This section describe how Pelican works internally. As you'll see, it's
|
||||
quite simple, but a bit of documentation doesn't hurt. :)
|
||||
This section describe how Pelican works internally. As you'll see, it's quite
|
||||
simple, but a bit of documentation doesn't hurt. :)
|
||||
|
||||
You can also find in the :doc:`report` section an excerpt of a report the
|
||||
original author wrote with some software design information.
|
||||
|
|
@ -13,9 +13,8 @@ Overall structure
|
|||
=================
|
||||
|
||||
What Pelican does is take a list of files and process them into some sort of
|
||||
output. Usually, the input files are reStructuredText and Markdown
|
||||
files, and the output is a blog, but both input and output can be anything you
|
||||
want.
|
||||
output. Usually, the input files are reStructuredText and Markdown files, and
|
||||
the output is a blog, but both input and output can be anything you want.
|
||||
|
||||
The logic is separated into different classes and concepts:
|
||||
|
||||
|
|
@ -27,20 +26,21 @@ The logic is separated into different classes and concepts:
|
|||
reStructuredText for now, but the system is extensible). Given a file, they
|
||||
return metadata (author, tags, category, etc.) and content (HTML-formatted).
|
||||
|
||||
* **Generators** generate the different outputs. For instance, Pelican comes with
|
||||
``ArticlesGenerator`` and ``PageGenerator``. Given a configuration, they can do
|
||||
whatever they want. Most of the time, it's generating files from inputs.
|
||||
* **Generators** generate the different outputs. For instance, Pelican comes
|
||||
with ``ArticlesGenerator`` and ``PageGenerator``. Given a configuration, they
|
||||
can do whatever they want. Most of the time, it's generating files from
|
||||
inputs.
|
||||
|
||||
* Pelican also uses templates, so it's easy to write your own theme. The
|
||||
syntax is `Jinja2 <http://jinja.pocoo.org/>`_ and is very easy to learn, so
|
||||
syntax is `Jinja2 <https://palletsprojects.com/p/jinja/>`_ and is very easy to learn, so
|
||||
don't hesitate to jump in and build your own theme.
|
||||
|
||||
How to implement a new reader?
|
||||
==============================
|
||||
|
||||
Is there an awesome markup language you want to add to Pelican?
|
||||
Well, the only thing you have to do is to create a class with a ``read``
|
||||
method that returns HTML content and some metadata.
|
||||
Is there an awesome markup language you want to add to Pelican? Well, the only
|
||||
thing you have to do is to create a class with a ``read`` method that returns
|
||||
HTML content and some metadata.
|
||||
|
||||
Take a look at the Markdown reader::
|
||||
|
||||
|
|
@ -65,17 +65,17 @@ Take a look at the Markdown reader::
|
|||
|
||||
Simple, isn't it?
|
||||
|
||||
If your new reader requires additional Python dependencies, then you should wrap
|
||||
their ``import`` statements in a ``try...except`` block. Then inside the reader's
|
||||
class, set the ``enabled`` class attribute to mark import success or failure.
|
||||
This makes it possible for users to continue using their favourite markup method
|
||||
without needing to install modules for formats they don't use.
|
||||
If your new reader requires additional Python dependencies, then you should
|
||||
wrap their ``import`` statements in a ``try...except`` block. Then inside the
|
||||
reader's class, set the ``enabled`` class attribute to mark import success or
|
||||
failure. This makes it possible for users to continue using their favourite
|
||||
markup method without needing to install modules for formats they don't use.
|
||||
|
||||
How to implement a new generator?
|
||||
=================================
|
||||
|
||||
Generators have two important methods. You're not forced to create
|
||||
both; only the existing ones will be called.
|
||||
Generators have two important methods. You're not forced to create both; only
|
||||
the existing ones will be called.
|
||||
|
||||
* ``generate_context``, that is called first, for all the generators.
|
||||
Do whatever you have to do, and update the global context if needed. This
|
||||
|
|
@ -89,5 +89,5 @@ both; only the existing ones will be called.
|
|||
generating the output. :) It's here that you may want to look at the context
|
||||
and call the methods of the ``writer`` object that is passed as the first
|
||||
argument of this function. In the ``PageGenerator`` example, this method will
|
||||
look at all the pages recorded in the global context and output a file on
|
||||
the disk (using the writer method ``write_file``) for each page encountered.
|
||||
look at all the pages recorded in the global context and output a file on the
|
||||
disk (using the writer method ``write_file``) for each page encountered.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,8 @@ pelican-themes
|
|||
Description
|
||||
===========
|
||||
|
||||
``pelican-themes`` is a command line tool for managing themes for Pelican.
|
||||
``pelican-themes`` is a command line tool for managing themes for Pelican. See
|
||||
:ref:`settings/themes` for settings related to themes.
|
||||
|
||||
|
||||
Usage
|
||||
|
|
@ -44,7 +45,8 @@ Examples
|
|||
Listing the installed themes
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
With ``pelican-themes``, you can see the available themes by using the ``-l`` or ``--list`` option:
|
||||
With ``pelican-themes``, you can see the available themes by using the ``-l``
|
||||
or ``--list`` option:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -57,11 +59,15 @@ With ``pelican-themes``, you can see the available themes by using the ``-l`` or
|
|||
two-column@
|
||||
simple
|
||||
|
||||
In this example, we can see there are three themes available: ``notmyidea``, ``simple``, and ``two-column``.
|
||||
In this example, we can see there are three themes available: ``notmyidea``,
|
||||
``simple``, and ``two-column``.
|
||||
|
||||
``two-column`` is prefixed with an ``@`` because this theme is not copied to the Pelican theme path, but is instead just linked to it (see `Creating symbolic links`_ for details about creating symbolic links).
|
||||
``two-column`` is prefixed with an ``@`` because this theme is not copied to
|
||||
the Pelican theme path, but is instead just linked to it (see `Creating
|
||||
symbolic links`_ for details about creating symbolic links).
|
||||
|
||||
Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get more verbose output, like this:
|
||||
Note that you can combine the ``--list`` option with the ``-v`` or
|
||||
``--verbose`` option to get more verbose output, like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -75,7 +81,8 @@ Installing themes
|
|||
"""""""""""""""""
|
||||
|
||||
You can install one or more themes using the ``-i`` or ``--install`` option.
|
||||
This option takes as argument the path(s) of the theme(s) you want to install, and can be combined with the verbose option:
|
||||
This option takes as argument the path(s) of the theme(s) you want to install,
|
||||
and can be combined with the verbose option:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -95,8 +102,9 @@ This option takes as argument the path(s) of the theme(s) you want to install, a
|
|||
Removing themes
|
||||
"""""""""""""""
|
||||
|
||||
The ``pelican-themes`` command can also remove themes from the Pelican themes path.
|
||||
The ``-r`` or ``--remove`` option takes as argument the name(s) of the theme(s) you want to remove, and can be combined with the ``--verbose`` option.
|
||||
The ``pelican-themes`` command can also remove themes from the Pelican themes
|
||||
path. The ``-r`` or ``--remove`` option takes as argument the name(s) of the
|
||||
theme(s) you want to remove, and can be combined with the ``--verbose`` option.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -113,15 +121,19 @@ The ``-r`` or ``--remove`` option takes as argument the name(s) of the theme(s)
|
|||
Creating symbolic links
|
||||
"""""""""""""""""""""""
|
||||
|
||||
``pelican-themes`` can also install themes by creating symbolic links instead of copying entire themes into the Pelican themes path.
|
||||
``pelican-themes`` can also install themes by creating symbolic links instead
|
||||
of copying entire themes into the Pelican themes path.
|
||||
|
||||
To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option:
|
||||
To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which
|
||||
works exactly as the ``--install`` option:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
|
||||
|
||||
In this example, the ``two-column`` theme is now symbolically linked to the Pelican themes path, so we can use it, but we can also modify it without having to reinstall it after each modification.
|
||||
In this example, the ``two-column`` theme is now symbolically linked to the
|
||||
Pelican themes path, so we can use it, but we can also modify it without having
|
||||
to reinstall it after each modification.
|
||||
|
||||
This is useful for theme development:
|
||||
|
||||
|
|
@ -142,7 +154,9 @@ This is useful for theme development:
|
|||
Doing several things at once
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclusive, so you can combine them in the same command line to do more than one operation at time, like this:
|
||||
The ``--install``, ``--remove`` and ``--symlink`` option are not mutually
|
||||
exclusive, so you can combine them in the same command line to do more than one
|
||||
operation at time, like this:
|
||||
|
||||
|
||||
.. code-block:: console
|
||||
|
|
@ -152,4 +166,5 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
|
|||
--symlink ~/Dev/Python/pelican-themes/two-column \
|
||||
--verbose
|
||||
|
||||
In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr``
|
||||
In this example, the theme ``notmyidea-cms`` is replaced by the theme
|
||||
``notmyidea-cms-fr``
|
||||
|
|
|
|||
101
docs/plugins.rst
101
docs/plugins.rst
|
|
@ -9,24 +9,38 @@ features to Pelican without having to directly modify the Pelican core.
|
|||
How to use plugins
|
||||
==================
|
||||
|
||||
To load plugins, you have to specify them in your settings file. There are two
|
||||
ways to do so. The first method is to specify strings with the path to the
|
||||
callables::
|
||||
Starting with version 5.0, Pelican moved to a new plugin structure utilizing
|
||||
namespace packages. Plugins supporting this structure will install under the
|
||||
namespace package ``pelican.plugins`` and can be automatically discovered
|
||||
by Pelican.
|
||||
|
||||
PLUGINS = ['package.myplugin',]
|
||||
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will then
|
||||
collect the namespace plugins and register them. If on the other hand you
|
||||
specify a ``PLUGINS`` settings as a list of plugins, this autodiscovery will
|
||||
be disabled and only listed plugins will be registered and you will have to
|
||||
explicitly list the namespace plugins as well.
|
||||
|
||||
Alternatively, another method is to import them and add them to the list::
|
||||
If you are using ``PLUGINS`` setting, you can specify plugins in two ways.
|
||||
The first method specifies plugins as a list of strings. Namespace plugins can
|
||||
be specified either by their full names (``pelican.plugins.myplugin``) or by
|
||||
their short names (``myplugin``)::
|
||||
|
||||
PLUGINS = ['package.myplugin',
|
||||
'namespace_plugin1',
|
||||
'pelican.plugins.namespace_plugin2']
|
||||
|
||||
Alternatively, you can import them in your settings file and pass the modules::
|
||||
|
||||
from package import myplugin
|
||||
PLUGINS = [myplugin,]
|
||||
from pelican.plugins import namespace_plugin1, namespace_plugin2
|
||||
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]
|
||||
|
||||
.. note::
|
||||
|
||||
When experimenting with different plugins (especially the ones that
|
||||
deal with metadata and content) caching may interfere and the
|
||||
changes may not be visible. In such cases disable caching with
|
||||
``LOAD_CONTENT_CACHE = False`` or use the ``--ignore-cache``
|
||||
command-line switch.
|
||||
When experimenting with different plugins (especially the ones that deal
|
||||
with metadata and content) caching may interfere and the changes may not be
|
||||
visible. In such cases disable caching with ``LOAD_CONTENT_CACHE = False``
|
||||
or use the ``--ignore-cache`` command-line switch.
|
||||
|
||||
If your plugins are not in an importable path, you can specify a list of paths
|
||||
via the ``PLUGIN_PATHS`` setting. As shown in the following example, paths in
|
||||
|
|
@ -37,11 +51,13 @@ the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::
|
|||
|
||||
Where to find plugins
|
||||
=====================
|
||||
Namespace plugins can be found in the `pelican-plugins organization`_ as
|
||||
individual repositories. Legacy plugins are collected in the `pelican-plugins
|
||||
repository`_ and they will be slowly phased out in favor of the namespace
|
||||
versions.
|
||||
|
||||
We maintain a separate repository of plugins for people to share and use.
|
||||
Please visit the `pelican-plugins`_ repository for a list of available plugins.
|
||||
|
||||
.. _pelican-plugins: https://github.com/getpelican/pelican-plugins
|
||||
.. _pelican-plugins organization: https://github.com/pelican-plugins
|
||||
.. _pelican-plugins repository: https://github.com/getpelican/pelican-plugins
|
||||
|
||||
Please note that while we do our best to review and maintain these plugins,
|
||||
they are submitted by the Pelican community and thus may have varying levels of
|
||||
|
|
@ -60,7 +76,7 @@ which you map the signals to your plugin logic. Let's take a simple example::
|
|||
from pelican import signals
|
||||
|
||||
def test(sender):
|
||||
print "%s initialized !!" % sender
|
||||
print("{} initialized !!".format(sender))
|
||||
|
||||
def register():
|
||||
signals.initialized.connect(test)
|
||||
|
|
@ -71,6 +87,33 @@ which you map the signals to your plugin logic. Let's take a simple example::
|
|||
your ``register`` callable or they will be garbage-collected before the
|
||||
signal is emitted.
|
||||
|
||||
Namespace plugin structure
|
||||
--------------------------
|
||||
|
||||
Namespace plugins must adhere to a certain structure in order to function
|
||||
properly. They need to be installable (i.e. contain ``setup.py`` or equivalent)
|
||||
and have a folder structure as follows::
|
||||
|
||||
myplugin
|
||||
├── pelican
|
||||
│ └── plugins
|
||||
│ └── myplugin
|
||||
│ ├── __init__.py
|
||||
│ └── ...
|
||||
├── ...
|
||||
└── setup.py
|
||||
|
||||
It is crucial that ``pelican`` or ``pelican/plugins`` folder **not**
|
||||
contain an ``__init__.py`` file. In fact, it is best to have those folders
|
||||
empty besides the listed folders in the above structure and keep your
|
||||
plugin related files contained solely in the ``pelican/plugins/myplugin``
|
||||
folder to avoid any issues.
|
||||
|
||||
For easily setting up the proper structure, a `cookiecutter template for
|
||||
plugins`_ is provided. Refer to the README in the link for how to use it.
|
||||
|
||||
.. _cookiecutter template for plugins: https://github.com/getpelican/cookiecutter-pelican-plugin
|
||||
|
||||
List of signals
|
||||
===============
|
||||
|
||||
|
|
@ -108,6 +151,7 @@ page_generator_preread page_generator invoked befor
|
|||
use if code needs to do something before every page is parsed.
|
||||
page_generator_init page_generator invoked in the PagesGenerator.__init__
|
||||
page_generator_finalized page_generator invoked at the end of PagesGenerator.generate_context
|
||||
page_generator_write_page page_generator, content invoked before writing each page, the page is passed as content
|
||||
page_writer_finalized page_generator, writer invoked after all pages have been written, but before the page generator
|
||||
is closed.
|
||||
static_generator_context static_generator, metadata
|
||||
|
|
@ -125,17 +169,17 @@ feed_written path, context, feed invoked each
|
|||
|
||||
.. warning::
|
||||
|
||||
Avoid ``content_object_init`` signal if you intend to read ``summary``
|
||||
or ``content`` properties of the content object. That combination can
|
||||
result in unresolved links when :ref:`ref-linking-to-internal-content`
|
||||
(see `pelican-plugins bug #314`_). Use ``_summary`` and ``_content``
|
||||
properties instead, or, alternatively, run your plugin at a later
|
||||
stage (e.g. ``all_generators_finalized``).
|
||||
Avoid ``content_object_init`` signal if you intend to read ``summary`` or
|
||||
``content`` properties of the content object. That combination can result in
|
||||
unresolved links when :ref:`ref-linking-to-internal-content` (see
|
||||
`pelican-plugins bug #314`_). Use ``_summary`` and ``_content`` properties
|
||||
instead, or, alternatively, run your plugin at a later stage (e.g.
|
||||
``all_generators_finalized``).
|
||||
|
||||
.. note::
|
||||
|
||||
After Pelican 3.2, signal names were standardized. Older plugins
|
||||
may need to be updated to use the new names:
|
||||
After Pelican 3.2, signal names were standardized. Older plugins may need
|
||||
to be updated to use the new names:
|
||||
|
||||
========================== ===========================
|
||||
Old name New name
|
||||
|
|
@ -161,9 +205,9 @@ How to create a new reader
|
|||
--------------------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -215,6 +259,7 @@ Adding a new generator is also really easy. You might want to have a look at
|
|||
# define a new generator here if you need to
|
||||
return MyGenerator
|
||||
|
||||
signals.get_generators.connect(get_generators)
|
||||
def register():
|
||||
signals.get_generators.connect(get_generators)
|
||||
|
||||
.. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314
|
||||
|
|
|
|||
135
docs/publish.rst
135
docs/publish.rst
|
|
@ -25,14 +25,19 @@ argument, like so::
|
|||
pelican --write-selected output/posts/my-post-title.html
|
||||
|
||||
Note that you must specify the path to the generated *output* file — not the
|
||||
source content. To determine the output file path, use the ``--debug`` flag to
|
||||
determine the correct file name and location. If desired, ``--write-selected``
|
||||
can take a comma-separated list of paths or can be configured as a setting.
|
||||
(See: :ref:`writing_only_selected_content`)
|
||||
source content. To determine the output file name and location, use the
|
||||
``--debug`` flag. If desired, ``--write-selected`` can take a comma-separated
|
||||
list of paths or can be configured as a setting. (See:
|
||||
:ref:`writing_only_selected_content`)
|
||||
|
||||
You can also tell Pelican to watch for your modifications, instead of
|
||||
manually re-running it every time you want to see your changes. To enable this,
|
||||
run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
|
||||
You can also tell Pelican to watch for your modifications, instead of manually
|
||||
re-running it every time you want to see your changes. To enable this, run the
|
||||
``pelican`` command with the ``-r`` or ``--autoreload`` option. On non-Windows
|
||||
environments, this option can also be combined with the ``-l`` or ``--listen``
|
||||
option to simultaneously both auto-regenerate *and* serve the output at
|
||||
http://localhost:8000::
|
||||
|
||||
pelican --autoreload --listen
|
||||
|
||||
Pelican has other command-line switches available. Have a look at the help to
|
||||
see all the options you can use::
|
||||
|
|
@ -49,20 +54,12 @@ HTML files directly::
|
|||
firefox output/index.html
|
||||
|
||||
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.
|
||||
assets, running Pelican's simple built-in web server will often provide a more
|
||||
reliable previewing experience::
|
||||
|
||||
For Python 2, run::
|
||||
pelican --listen
|
||||
|
||||
cd output
|
||||
python -m SimpleHTTPServer
|
||||
|
||||
For Python 3, run::
|
||||
|
||||
cd output
|
||||
python -m http.server
|
||||
|
||||
Once the basic server has been started, you can preview your site at
|
||||
Once the web server has been started, you can preview your site at:
|
||||
http://localhost:8000/
|
||||
|
||||
Deployment
|
||||
|
|
@ -75,17 +72,17 @@ feeds, etc.) that you may have defined::
|
|||
|
||||
pelican content -s publishconf.py
|
||||
|
||||
To base your publish configuration on top of your ``pelicanconf.py``, you
|
||||
can import your ``pelicanconf`` settings by including the following line in
|
||||
your ``publishconf.py``::
|
||||
To base your publish configuration on top of your ``pelicanconf.py``, you can
|
||||
import your ``pelicanconf`` settings by including the following line in your
|
||||
``publishconf.py``::
|
||||
|
||||
from pelicanconf import *
|
||||
|
||||
If you have generated a ``publishconf.py`` using ``pelican-quickstart``,
|
||||
this line is included by default.
|
||||
If you have generated a ``publishconf.py`` using ``pelican-quickstart``, this
|
||||
line is included by default.
|
||||
|
||||
The steps for deploying your site will depend on where it will be hosted.
|
||||
If you have SSH access to a server running Nginx or Apache, you might use the
|
||||
The steps for deploying your site will depend on where it will be hosted. If
|
||||
you have SSH access to a server running Nginx or Apache, you might use the
|
||||
``rsync`` tool to transmit your site files::
|
||||
|
||||
rsync -avc --delete output/ host.example.com:/var/www/your-site/
|
||||
|
|
@ -98,81 +95,75 @@ Automation
|
|||
==========
|
||||
|
||||
While the ``pelican`` command is the canonical way to generate your site,
|
||||
automation tools can be used to streamline the generation and publication
|
||||
flow. One of the questions asked during the ``pelican-quickstart`` process
|
||||
pertains to whether you want to automate site generation and publication.
|
||||
If you answered "yes" to that question, a ``fabfile.py`` and
|
||||
``Makefile`` will be generated in the root of your project. These files,
|
||||
pre-populated with certain information gleaned from other answers provided
|
||||
during the ``pelican-quickstart`` process, are meant as a starting point and
|
||||
should be customized to fit your particular needs and usage patterns. If you
|
||||
find one or both of these automation tools to be of limited utility, these
|
||||
files can deleted at any time and will not affect usage of the canonical
|
||||
``pelican`` command.
|
||||
automation tools can be used to streamline the generation and publication flow.
|
||||
One of the questions asked during the ``pelican-quickstart`` process pertains
|
||||
to whether you want to automate site generation and publication. If you
|
||||
answered "yes" to that question, a ``tasks.py`` and ``Makefile`` will be
|
||||
generated in the root of your project. These files, pre-populated with certain
|
||||
information gleaned from other answers provided during the
|
||||
``pelican-quickstart`` process, are meant as a starting point and should be
|
||||
customized to fit your particular needs and usage patterns. If you find one or
|
||||
both of these automation tools to be of limited utility, these files can
|
||||
deleted at any time and will not affect usage of the canonical ``pelican``
|
||||
command.
|
||||
|
||||
Following are automation tools that "wrap" the ``pelican`` command and can
|
||||
simplify the process of generating, previewing, and uploading your site.
|
||||
|
||||
Fabric
|
||||
Invoke
|
||||
------
|
||||
|
||||
The advantage of Fabric_ is that it is written in Python and thus can be used
|
||||
The advantage of Invoke_ is that it is written in Python and thus can be used
|
||||
in a wide range of environments. The downside is that it must be installed
|
||||
separately. Use the following command to install Fabric, prefixing with
|
||||
separately. Use the following command to install Invoke, prefixing with
|
||||
``sudo`` if your environment requires it::
|
||||
|
||||
pip install Fabric
|
||||
pip install invoke
|
||||
|
||||
.. note:: Installing PyCrypto on Windows
|
||||
|
||||
Fabric depends upon PyCrypto_, which is tricky to install
|
||||
if your system doesn't have a C compiler.
|
||||
For Windows users, before installing Fabric, use
|
||||
``easy_install http://www.voidspace.org.uk/downloads/pycrypto26/pycrypto-2.6.win32-py2.7.exe``
|
||||
per this `StackOverflow suggestion <http://stackoverflow.com/a/11405769/6364>`_
|
||||
You're more likely to have success
|
||||
with the Win32 versions of Python 2.7 and PyCrypto,
|
||||
than with the Win64—\
|
||||
even if your operating system is a 64-bit version of Windows.
|
||||
|
||||
Take a moment to open the ``fabfile.py`` file that was generated in your
|
||||
project root. You will see a number of commands, any one of which can be
|
||||
renamed, removed, and/or customized to your liking. Using the out-of-the-box
|
||||
Take a moment to open the ``tasks.py`` file that was generated in your project
|
||||
root. You will see a number of commands, any one of which can be renamed,
|
||||
removed, and/or customized to your liking. Using the out-of-the-box
|
||||
configuration, you can generate your site via::
|
||||
|
||||
fab build
|
||||
invoke build
|
||||
|
||||
If you'd prefer to have Pelican automatically regenerate your site every time a
|
||||
change is detected (which is handy when testing locally), use the following
|
||||
command instead::
|
||||
|
||||
fab regenerate
|
||||
invoke regenerate
|
||||
|
||||
To serve the generated site so it can be previewed in your browser at
|
||||
http://localhost:8000/::
|
||||
|
||||
fab serve
|
||||
invoke serve
|
||||
|
||||
To serve the generated site with automatic browser reloading every time a
|
||||
change is detected, first ``pip install livereload``, then use the
|
||||
following command::
|
||||
|
||||
invoke livereload
|
||||
|
||||
If during the ``pelican-quickstart`` process you answered "yes" when asked
|
||||
whether you want to upload your site via SSH, you can use the following command
|
||||
to publish your site via rsync over SSH::
|
||||
|
||||
fab publish
|
||||
invoke publish
|
||||
|
||||
These are just a few of the commands available by default, so feel free to
|
||||
explore ``fabfile.py`` and see what other commands are available. More
|
||||
importantly, don't hesitate to customize ``fabfile.py`` to suit your specific
|
||||
explore ``tasks.py`` and see what other commands are available. More
|
||||
importantly, don't hesitate to customize ``tasks.py`` to suit your specific
|
||||
needs and preferences.
|
||||
|
||||
Make
|
||||
----
|
||||
|
||||
A ``Makefile`` is also automatically created for you when you say "yes" to
|
||||
the relevant question during the ``pelican-quickstart`` process. The advantage
|
||||
of this method is that the ``make`` command is built into most POSIX systems
|
||||
and thus doesn't require installing anything else in order to use it. The
|
||||
downside is that non-POSIX systems (e.g., Windows) do not include ``make``,
|
||||
and installing it on those systems can be a non-trivial task.
|
||||
A ``Makefile`` is also automatically created for you when you say "yes" to the
|
||||
relevant question during the ``pelican-quickstart`` process. The advantage of
|
||||
this method is that the ``make`` command is built into most POSIX systems and
|
||||
thus doesn't require installing anything else in order to use it. The downside
|
||||
is that non-POSIX systems (e.g., Windows) do not include ``make``, and
|
||||
installing it on those systems can be a non-trivial task.
|
||||
|
||||
If you want to use ``make`` to generate your site using the settings in
|
||||
``pelicanconf.py``, run::
|
||||
|
|
@ -201,10 +192,7 @@ separate terminal sessions, but you can run both at once via::
|
|||
make devserver
|
||||
|
||||
The above command will simultaneously run Pelican in regeneration mode as well
|
||||
as serve the output at http://localhost:8000. Once you are done testing your
|
||||
changes, you should stop the development server via::
|
||||
|
||||
./develop_server.sh stop
|
||||
as serve the output at http://localhost:8000.
|
||||
|
||||
When you're ready to publish your site, you can upload it via the method(s) you
|
||||
chose during the ``pelican-quickstart`` questionnaire. For this example, we'll
|
||||
|
|
@ -219,5 +207,4 @@ That's it! Your site should now be live.
|
|||
executables, such as ``python3``, you can set the ``PY`` and ``PELICAN``
|
||||
environment variables, respectively, to override the default executable names.)
|
||||
|
||||
.. _Fabric: http://fabfile.org/
|
||||
.. _PyCrypto: http://pycrypto.org
|
||||
.. _Invoke: https://www.pyinvoke.org/
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ Installation
|
|||
------------
|
||||
|
||||
Install Pelican (and optionally Markdown if you intend to use it) on Python
|
||||
2.7.x or Python 3.3+ by running the following command in your preferred
|
||||
2.7.x or Python 3.5+ by running the following command in your preferred
|
||||
terminal, prefixing with ``sudo`` if permissions warrant::
|
||||
|
||||
pip install pelican markdown
|
||||
pip install pelican[Markdown]
|
||||
|
||||
Create a project
|
||||
----------------
|
||||
|
|
@ -30,7 +30,7 @@ by asking some questions about your site::
|
|||
For questions that have default values denoted in brackets, feel free to use
|
||||
the Return key to accept those default values [#tzlocal_fn]_. When asked for
|
||||
your URL prefix, enter your domain name as indicated (e.g.,
|
||||
``http://example.com``).
|
||||
``https://example.com``).
|
||||
|
||||
Create an article
|
||||
-----------------
|
||||
|
|
@ -50,27 +50,27 @@ Given that this example article is in Markdown format, save it as
|
|||
Generate your site
|
||||
------------------
|
||||
|
||||
From your site directory, run the ``pelican`` command to generate your site::
|
||||
From your project root directory, run the ``pelican`` command to generate your site::
|
||||
|
||||
pelican content
|
||||
|
||||
Your site has now been generated inside the ``output`` directory. (You may see a
|
||||
warning related to feeds, but that is normal when developing locally and can be
|
||||
ignored for now.)
|
||||
Your site has now been generated inside the ``output/`` directory. (You may see
|
||||
a warning related to feeds, but that is normal when developing locally and can
|
||||
be ignored for now.)
|
||||
|
||||
Preview your site
|
||||
-----------------
|
||||
|
||||
Open a new terminal session and run the following commands to switch to your
|
||||
``output`` directory and launch Pelican's web server::
|
||||
Open a new terminal session, navigate to your project root directory, and
|
||||
run the following command to launch Pelican's web server::
|
||||
|
||||
cd ~/projects/yoursite/output
|
||||
python -m pelican.server
|
||||
pelican --listen
|
||||
|
||||
Preview your site by navigating to http://localhost:8000/ in your browser.
|
||||
|
||||
Continue reading the other documentation sections for more detail, and check out
|
||||
the Pelican wiki's Tutorials_ page for links to community-published tutorials.
|
||||
Continue reading the other documentation sections for more detail, and check
|
||||
out the Pelican wiki's Tutorials_ page for links to community-published
|
||||
tutorials.
|
||||
|
||||
.. _Tutorials: https://github.com/getpelican/pelican/wiki/Tutorials
|
||||
|
||||
|
|
@ -78,5 +78,5 @@ Footnotes
|
|||
---------
|
||||
|
||||
.. [#tzlocal_fn] You can help localize default fields by installing the
|
||||
optional `tzlocal <https://pypi.python.org/pypi/tzlocal>`_
|
||||
optional `tzlocal <https://pypi.org/project/tzlocal/>`_
|
||||
module.
|
||||
|
|
|
|||
117
docs/report.rst
117
docs/report.rst
|
|
@ -7,29 +7,27 @@ Some history about Pelican
|
|||
right after writing Pelican, in December 2010. The information may not be
|
||||
up-to-date.
|
||||
|
||||
Pelican is a simple static blog generator. It parses markup files
|
||||
(Markdown or reStructuredText for now) and generates an HTML folder
|
||||
with all the files in it.
|
||||
I've chosen to use Python to implement Pelican because it seemed to
|
||||
be simple and to fit to my needs. I did not wanted to define a class for
|
||||
each thing, but still wanted to keep my things loosely coupled.
|
||||
It turns out that it was exactly what I wanted. From time to time,
|
||||
thanks to the feedback of some users, it took me a very few time to
|
||||
provide fixes on it. So far, I've re-factored the Pelican code by two
|
||||
Pelican is a simple static blog generator. It parses markup files (Markdown or
|
||||
reStructuredText for now) and generates an HTML folder with all the files in
|
||||
it. I've chosen to use Python to implement Pelican because it seemed to be
|
||||
simple and to fit to my needs. I did not wanted to define a class for each
|
||||
thing, but still wanted to keep my things loosely coupled. It turns out that it
|
||||
was exactly what I wanted. From time to time, thanks to the feedback of some
|
||||
users, it took me a very few time to provide fixes on it. So far, I've
|
||||
re-factored the Pelican code by two
|
||||
times; each time took less than 30 minutes.
|
||||
|
||||
Use case
|
||||
========
|
||||
|
||||
I was previously using WordPress, a solution you can host on a web
|
||||
server to manage your blog. Most of the time, I prefer using markup
|
||||
languages such as Markdown or reStructuredText to type my articles.
|
||||
To do so, I use vim. I think it is important to let the people choose the
|
||||
tool they want to write the articles. In my opinion, a blog manager
|
||||
should just allow you to take any kind of input and transform it to a
|
||||
weblog. That's what Pelican does.
|
||||
You can write your articles using the tool you want, and the markup
|
||||
language you want, and then generate a static HTML weblog.
|
||||
I was previously using WordPress, a solution you can host on a web server to
|
||||
manage your blog. Most of the time, I prefer using markup languages such as
|
||||
Markdown or reStructuredText to type my articles. To do so, I use vim. I think
|
||||
it is important to let the people choose the tool they want to write the
|
||||
articles. In my opinion, a blog manager should just allow you to take any kind
|
||||
of input and transform it to a weblog. That's what Pelican does. You can write
|
||||
your articles using the tool you want, and the markup language you want, and
|
||||
then generate a static HTML weblog.
|
||||
|
||||
.. image:: _static/overall.png
|
||||
|
||||
|
|
@ -40,39 +38,36 @@ Design process
|
|||
==============
|
||||
|
||||
Pelican came from a need I have. I started by creating a single file
|
||||
application, and I have make it grow to support what it does by now.
|
||||
To start, I wrote a piece of documentation about what I wanted to do.
|
||||
Then, I created the content I wanted to parse (the reStructuredText files)
|
||||
and started experimenting with the code. Pelican was 200 lines long and
|
||||
contained almost ten functions and one class when it was first usable.
|
||||
application, and I have make it grow to support what it does by now. To start,
|
||||
I wrote a piece of documentation about what I wanted to do. Then, I created the
|
||||
content I wanted to parse (the reStructuredText files) and started
|
||||
experimenting with the code. Pelican was 200 lines long and contained almost
|
||||
ten functions and one class when it was first usable.
|
||||
|
||||
I have been facing different problems all over the time and wanted to
|
||||
add features to Pelican while using it. The first change I have done was
|
||||
to add the support of a settings file. It is possible to pass the options to
|
||||
the command line, but can be tedious if there is a lot of them.
|
||||
In the same way, I have added the support of different things over
|
||||
time: Atom feeds, multiple themes, multiple markup support, etc.
|
||||
At some point, it appears that the "only one file" mantra was not good
|
||||
enough for Pelican, so I decided to rework a bit all that, and split this in
|
||||
multiple different files.
|
||||
I have been facing different problems all over the time and wanted to add
|
||||
features to Pelican while using it. The first change I have done was to add the
|
||||
support of a settings file. It is possible to pass the options to the command
|
||||
line, but can be tedious if there is a lot of them. In the same way, I have
|
||||
added the support of different things over time: Atom feeds, multiple themes,
|
||||
multiple markup support, etc. At some point, it appears that the "only one
|
||||
file" mantra was not good enough for Pelican, so I decided to rework a bit all
|
||||
that, and split this in multiple different files.
|
||||
|
||||
I’ve separated the logic in different classes and concepts:
|
||||
|
||||
* *writers* are responsible of all the writing process of the files.
|
||||
They are responsible of writing .html files, RSS feeds and so on.
|
||||
Since those operations are commonly used, the object is created
|
||||
once, and then passed to the generators.
|
||||
They are responsible of writing .html files, RSS feeds and so on. Since those
|
||||
operations are commonly used, the object is created once, and then passed to
|
||||
the generators.
|
||||
|
||||
* *readers* are used to read from various formats (Markdown and
|
||||
reStructuredText for now, but the system is extensible). Given a
|
||||
file, they return metadata (author, tags, category, etc) and
|
||||
content (HTML formatted).
|
||||
reStructuredText for now, but the system is extensible). Given a file, they
|
||||
return metadata (author, tags, category, etc) and content (HTML formatted).
|
||||
|
||||
* *generators* generate the different outputs. For instance, Pelican
|
||||
comes with an ArticlesGenerator and PagesGenerator, into
|
||||
others. Given a configuration, they can do whatever you want
|
||||
them to do. Most of the time it's generating files from inputs
|
||||
(user inputs and files).
|
||||
comes with an ArticlesGenerator and PagesGenerator, into others. Given a
|
||||
configuration, they can do whatever you want them to do. Most of the time
|
||||
it's generating files from inputs (user inputs and files).
|
||||
|
||||
I also deal with contents objects. They can be ``Articles``, ``Pages``,
|
||||
``Quotes``, or whatever you want. They are defined in the ``contents.py``
|
||||
|
|
@ -90,32 +85,30 @@ whole picture. I do use duck typing and not interfaces.
|
|||
|
||||
Internally, the following process is followed:
|
||||
|
||||
* First of all, the command line is parsed, and some content from
|
||||
the user is used to initialize the different generator objects.
|
||||
* First of all, the command line is parsed, and some content from the user is
|
||||
used to initialize the different generator objects.
|
||||
|
||||
* A ``context`` is created. It contains the settings from the command
|
||||
line and a settings file if provided.
|
||||
* A ``context`` is created. It contains the settings from the command line and
|
||||
a settings file if provided.
|
||||
* The ``generate_context`` method of each generator is called, updating
|
||||
the context.
|
||||
* The writer is created and given to the ``generate_output`` method of each
|
||||
generator.
|
||||
|
||||
* The writer is created and given to the ``generate_output`` method of
|
||||
each generator.
|
||||
|
||||
I make two calls because it is important that when the output is
|
||||
generated by the generators, the context will not change. In other
|
||||
words, the first method ``generate_context`` should modify the context,
|
||||
whereas the second ``generate_output`` method should not.
|
||||
I make two calls because it is important that when the output is generated by
|
||||
the generators, the context will not change. In other words, the first method
|
||||
``generate_context`` should modify the context, whereas the second
|
||||
``generate_output`` method should not.
|
||||
|
||||
Then, it is up to the generators to do what the want, in the
|
||||
``generate_context`` and ``generate_content`` method.
|
||||
Taking the ``ArticlesGenerator`` class will help to understand some others
|
||||
concepts. Here is what happens when calling the ``generate_context``
|
||||
method:
|
||||
``generate_context`` and ``generate_content`` method. Taking the
|
||||
``ArticlesGenerator`` class will help to understand some others concepts. Here
|
||||
is what happens when calling the ``generate_context`` method:
|
||||
|
||||
* Read the folder “path”, looking for restructured text files, load
|
||||
each of them, and construct a content object (``Article``) with it. To do so,
|
||||
use ``Reader`` objects.
|
||||
* Read the folder “path”, looking for restructured text files, load each of
|
||||
them, and construct a content object (``Article``) with it. To do so, use
|
||||
``Reader`` objects.
|
||||
* Update the ``context`` with all those articles.
|
||||
|
||||
Then, the ``generate_content`` method uses the ``context`` and the ``writer`` to
|
||||
generate the wanted output.
|
||||
Then, the ``generate_content`` method uses the ``context`` and the ``writer``
|
||||
to generate the wanted output.
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
182
docs/themes.rst
182
docs/themes.rst
|
|
@ -3,13 +3,14 @@
|
|||
Creating themes
|
||||
###############
|
||||
|
||||
To generate its HTML output, Pelican uses the `Jinja <http://jinja.pocoo.org/>`_
|
||||
templating engine due to its flexibility and straightforward syntax. If you want
|
||||
to create your own theme, feel free to take inspiration from the `"simple" theme
|
||||
To generate its HTML output, Pelican uses the `Jinja
|
||||
<https://palletsprojects.com/p/jinja/>`_ templating engine due to its flexibility and
|
||||
straightforward syntax. If you want to create your own theme, feel free to take
|
||||
inspiration from the `"simple" theme
|
||||
<https://github.com/getpelican/pelican/tree/master/pelican/themes/simple/templates>`_.
|
||||
|
||||
To generate your site using a theme you have created (or downloaded manually and
|
||||
then modified), you can specify that theme via the ``-t`` flag::
|
||||
To generate your site using a theme you have created (or downloaded manually
|
||||
and then modified), you can specify that theme via the ``-t`` flag::
|
||||
|
||||
pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme
|
||||
|
||||
|
|
@ -42,9 +43,9 @@ To make your own theme, you must follow the following structure::
|
|||
`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.
|
||||
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` contains all the templates that will be used to generate the
|
||||
content. 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-variables:
|
||||
|
|
@ -74,51 +75,53 @@ output_file The name of the file currently being generated. For
|
|||
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
|
||||
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.
|
||||
drafts The list of draft articles
|
||||
tags A list of (tag, articles) tuples, containing all
|
||||
the tags.
|
||||
authors A list of (author, articles) tuples, containing all
|
||||
the authors and corresponding articles (values)
|
||||
categories A list of (category, articles) tuples, containing
|
||||
all the categories and corresponding articles (values)
|
||||
tags A list of (tag, articles) tuples, containing all
|
||||
the tags and corresponding articles (values)
|
||||
pages The list of pages
|
||||
hidden_pages The list of hidden pages
|
||||
draft_pages The list of draft pages
|
||||
============= ===================================================
|
||||
|
||||
|
||||
Sorting
|
||||
-------
|
||||
|
||||
URL wrappers (currently categories, tags, and authors), have
|
||||
comparison methods that allow them to be easily sorted by name::
|
||||
URL wrappers (currently categories, tags, and authors), have comparison methods
|
||||
that allow them to be easily sorted by name::
|
||||
|
||||
{% for tag, articles in tags|sort %}
|
||||
|
||||
If you want to sort based on different criteria, `Jinja's sort
|
||||
command`__ has a number of options.
|
||||
If you want to sort based on different criteria, `Jinja's sort command`__ has a
|
||||
number of options.
|
||||
|
||||
__ http://jinja.pocoo.org/docs/templates/#sort
|
||||
__ https://jinja.palletsprojects.com/en/master/templates/#sort
|
||||
|
||||
|
||||
Date Formatting
|
||||
---------------
|
||||
|
||||
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, 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,
|
||||
but the filter will do the right thing and format your date according
|
||||
to the locale given in your settings::
|
||||
(``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a ``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, but the filter will do the right thing and format
|
||||
your date according to the locale given in your settings::
|
||||
|
||||
{{ article.date|strftime('%d %B %Y') }}
|
||||
|
||||
.. _datetime: http://docs.python.org/2/library/datetime.html#datetime-objects
|
||||
.. _strftime: http://docs.python.org/2/library/datetime.html#strftime-strptime-behavior
|
||||
.. _datetime: https://docs.python.org/3/library/datetime.html#datetime-objects
|
||||
.. _strftime: https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior
|
||||
|
||||
|
||||
index.html
|
||||
|
|
@ -126,7 +129,8 @@ index.html
|
|||
|
||||
This is the home page or index of your blog, generated at ``index.html``.
|
||||
|
||||
If pagination is active, subsequent pages will reside in ``index{number}.html``.
|
||||
If pagination is active, subsequent pages will reside in
|
||||
``index{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -152,10 +156,10 @@ page_name 'index' -- useful for pagination links
|
|||
author.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each of the existing authors, with
|
||||
output generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
|
||||
``author/{author_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``author/{author_name}{number}.html``.
|
||||
This template will be processed for each of the existing authors, with output
|
||||
generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
|
||||
``author/{slug}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``author/{slug}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -188,8 +192,8 @@ category.html
|
|||
|
||||
This template will be processed for each of the existing categories, with
|
||||
output generated according to the ``CATEGORY_SAVE_AS`` setting (`Default:`
|
||||
``category/{category_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``category/{category_name}{number}.html``.
|
||||
``category/{slug}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``category/{slug}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -220,10 +224,9 @@ page_name CATEGORY_URL where everything after `{slug}` is
|
|||
article.html
|
||||
-------------
|
||||
|
||||
This template will be processed for each article, with
|
||||
output generated according to the ``ARTICLE_SAVE_AS`` setting (`Default:`
|
||||
``{article_name}.html``). The following variables are available when
|
||||
rendering.
|
||||
This template will be processed for each article, with output generated
|
||||
according to the ``ARTICLE_SAVE_AS`` setting (`Default:` ``{slug}.html``). The
|
||||
following variables are available when rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -232,9 +235,9 @@ article The article object to be displayed
|
|||
category The name of the category for the current article
|
||||
============= ===================================================
|
||||
|
||||
Any metadata that you put in the header of the article source file
|
||||
will be available as fields on the ``article`` object. The field name will be
|
||||
the same as the name of the metadata field, except in all-lowercase characters.
|
||||
Any metadata that you put in the header of the article source file will be
|
||||
available as fields on the ``article`` object. The field name will be the same
|
||||
as the name of the metadata field, except in all-lowercase characters.
|
||||
|
||||
For example, you could add a field called `FacebookImage` to your article
|
||||
metadata, as shown below:
|
||||
|
|
@ -250,8 +253,8 @@ metadata, as shown below:
|
|||
FacebookImage: http://franciscabrel.com/images/pythonlove.png
|
||||
|
||||
This new metadata will be made available as `article.facebookimage` in your
|
||||
`article.html` template. This would allow you, for example, to specify an
|
||||
image for the Facebook open graph tags that will change for each article:
|
||||
`article.html` template. This would allow you, for example, to specify an image
|
||||
for the Facebook open graph tags that will change for each article:
|
||||
|
||||
.. code-block:: html+jinja
|
||||
|
||||
|
|
@ -261,10 +264,9 @@ image for the Facebook open graph tags that will change for each article:
|
|||
page.html
|
||||
---------
|
||||
|
||||
This template will be processed for each page, with
|
||||
output generated according to the ``PAGE_SAVE_AS`` setting (`Default:`
|
||||
``pages/{page_name}.html``). The following variables are available when
|
||||
rendering.
|
||||
This template will be processed for each page, with output generated according
|
||||
to the ``PAGE_SAVE_AS`` setting (`Default:` ``pages/{slug}.html``). The
|
||||
following variables are available when rendering.
|
||||
|
||||
============= ===================================================
|
||||
Variable Description
|
||||
|
|
@ -277,10 +279,10 @@ page The page object to be displayed. You can access its
|
|||
tag.html
|
||||
--------
|
||||
|
||||
This template will be processed for each tag, with
|
||||
output generated according to the ``TAG_SAVE_AS`` setting (`Default:`
|
||||
``tag/{tag_name}.html``). If pagination is active, subsequent pages will by
|
||||
default reside at ``tag/{tag_name}{number}.html``.
|
||||
This template will be processed for each tag, with output generated according
|
||||
to the ``TAG_SAVE_AS`` setting (`Default:` ``tag/{slug}.html``). If pagination
|
||||
is active, subsequent pages will by default reside at
|
||||
``tag/{slug}{number}.html``.
|
||||
|
||||
====================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -311,9 +313,9 @@ page_name TAG_URL where everything after `{slug}` is removed
|
|||
period_archives.html
|
||||
--------------------
|
||||
|
||||
This template will be processed for each year of your posts if a path
|
||||
for ``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS``
|
||||
is defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
|
||||
This template will be processed for each year of your posts if a path for
|
||||
``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS`` is
|
||||
defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
|
||||
|
||||
=================== ===================================================
|
||||
Variable Description
|
||||
|
|
@ -347,9 +349,9 @@ Article
|
|||
|
||||
The string representation of an Article is the `source_path` attribute.
|
||||
|
||||
=================== ===================================================
|
||||
====================== ===================================================
|
||||
Attribute Description
|
||||
=================== ===================================================
|
||||
====================== ===================================================
|
||||
author The :ref:`Author <object-author_cat_tag>` of
|
||||
this article.
|
||||
authors A list of :ref:`Authors <object-author_cat_tag>`
|
||||
|
|
@ -368,6 +370,7 @@ metadata Article header metadata `dict`.
|
|||
save_as Location to save the article page.
|
||||
slug Page slug.
|
||||
source_path Full system path of the article source file.
|
||||
relative_source_path Relative path from PATH_ to the article source file.
|
||||
status The article status, can be any of 'published' or
|
||||
'draft'.
|
||||
summary Rendered summary content.
|
||||
|
|
@ -378,7 +381,10 @@ title Title of the article.
|
|||
translations List of translations
|
||||
:ref:`Article <object-article>` objects.
|
||||
url URL to the article page.
|
||||
=================== ===================================================
|
||||
====================== ===================================================
|
||||
|
||||
.. _PATH: settings.html#PATH
|
||||
|
||||
|
||||
.. _object-author_cat_tag:
|
||||
|
||||
|
|
@ -406,34 +412,38 @@ Page
|
|||
|
||||
The string representation of a Page is the `source_path` attribute.
|
||||
|
||||
=================== ===================================================
|
||||
Attribute Description
|
||||
=================== ===================================================
|
||||
author The :ref:`Author <object-author_cat_tag>` of
|
||||
this page.
|
||||
content The rendered content of the page.
|
||||
date Datetime object representing the page date.
|
||||
date_format Either default date format or locale date format.
|
||||
default_template Default template name.
|
||||
in_default_lang Boolean representing if the article is written
|
||||
in the default language.
|
||||
lang Language of the article.
|
||||
locale_date Date formatted by the `date_format`.
|
||||
metadata Page header metadata `dict`.
|
||||
save_as Location to save the page.
|
||||
slug Page slug.
|
||||
source_path Full system path of the page source file.
|
||||
status The page status, can be any of 'published' or
|
||||
'draft'.
|
||||
summary Rendered summary content.
|
||||
tags List of :ref:`Tag <object-author_cat_tag>`
|
||||
objects.
|
||||
template Template name to use for rendering.
|
||||
title Title of the page.
|
||||
translations List of translations
|
||||
:ref:`Article <object-article>` objects.
|
||||
url URL to the page.
|
||||
=================== ===================================================
|
||||
===================== ===================================================
|
||||
Attribute Description
|
||||
===================== ===================================================
|
||||
author The :ref:`Author <object-author_cat_tag>` of
|
||||
this page.
|
||||
content The rendered content of the page.
|
||||
date Datetime object representing the page date.
|
||||
date_format Either default date format or locale date format.
|
||||
default_template Default template name.
|
||||
in_default_lang Boolean representing if the article is written
|
||||
in the default language.
|
||||
lang Language of the article.
|
||||
locale_date Date formatted by the `date_format`.
|
||||
metadata Page header metadata `dict`.
|
||||
save_as Location to save the page.
|
||||
slug Page slug.
|
||||
source_path Full system path of the page source file.
|
||||
relative_source_path Relative path from PATH_ to the page source file.
|
||||
status The page status, can be any of 'published', 'hidden' or
|
||||
'draft'.
|
||||
summary Rendered summary content.
|
||||
tags List of :ref:`Tag <object-author_cat_tag>`
|
||||
objects.
|
||||
template Template name to use for rendering.
|
||||
title Title of the page.
|
||||
translations List of translations
|
||||
:ref:`Article <object-article>` objects.
|
||||
url URL to the page.
|
||||
===================== ===================================================
|
||||
|
||||
.. _PATH: settings.html#PATH
|
||||
|
||||
|
||||
Feeds
|
||||
=====
|
||||
|
|
@ -463,9 +473,9 @@ Since version 3.0, Pelican supports inheritance from the ``simple`` theme, so
|
|||
you can re-use the ``simple`` theme templates in your own themes.
|
||||
|
||||
If one of the mandatory files in the ``templates/`` directory of your theme is
|
||||
missing, it will be replaced by the matching template from the ``simple`` theme.
|
||||
So if the HTML structure of a template in the ``simple`` theme is right for you,
|
||||
you don't have to write a new template from scratch.
|
||||
missing, it will be replaced by the matching template from the ``simple``
|
||||
theme. So if the HTML structure of a template in the ``simple`` theme is right
|
||||
for you, you don't have to write a new template from scratch.
|
||||
|
||||
You can also extend templates from the ``simple`` theme in your own themes by
|
||||
using the ``{% extends %}`` directive as in the following example:
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ Custom 404 Pages
|
|||
|
||||
When a browser requests a resource that the web server cannot find, the web
|
||||
server usually displays a generic "File not found" (404) error page that can be
|
||||
stark and unsightly. One way to provide an error page that matches the theme
|
||||
of your site is to create a custom 404 page (*not* an article), such as this
|
||||
stark and unsightly. One way to provide an error page that matches the theme of
|
||||
your site is to create a custom 404 page (*not* an article), such as this
|
||||
Markdown-formatted example stored in ``content/pages/404.md``::
|
||||
|
||||
Title: Not Found
|
||||
|
|
@ -29,8 +29,8 @@ For Apache::
|
|||
|
||||
ErrorDocument 404 /404.html
|
||||
|
||||
For Amazon S3, first navigate to the ``Static Site Hosting`` menu in the
|
||||
bucket settings on your AWS cosole. From there::
|
||||
For Amazon S3, first navigate to the ``Static Site Hosting`` menu in the bucket
|
||||
settings on your AWS cosole. From there::
|
||||
|
||||
Error Document: 404.html
|
||||
|
||||
|
|
@ -58,7 +58,7 @@ 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
|
||||
$ ghp-import output -b gh-pages
|
||||
$ git push origin gh-pages
|
||||
|
||||
The ``ghp-import output`` command updates the local ``gh-pages`` branch with
|
||||
|
|
@ -67,15 +67,10 @@ already exist). The ``git push origin gh-pages`` command updates the remote
|
|||
``gh-pages`` branch, effectively publishing the Pelican site.
|
||||
|
||||
.. note::
|
||||
The ``github`` target of the Makefile (and the ``gh_pages`` task of the Fabfile)
|
||||
created by the ``pelican-quickstart`` command
|
||||
publishes the Pelican site as Project Pages, as described above.
|
||||
|
||||
.. note:: ghp-import on Windows
|
||||
|
||||
Until `ghp-import Pull Request #25 <https://github.com/davisp/ghp-import/pull/25>`_
|
||||
is accepted, you will need to install a custom build of ghp-import:
|
||||
``pip install https://github.com/chevah/ghp-import/archive/win-support.zip``
|
||||
The ``github`` target of the Makefile (and the ``gh_pages`` task of
|
||||
``tasks.py``) created by the ``pelican-quickstart`` command publishes the
|
||||
Pelican site as Project Pages, as described above.
|
||||
|
||||
User Pages
|
||||
----------
|
||||
|
|
@ -87,7 +82,7 @@ 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
|
||||
$ ghp-import output -b gh-pages
|
||||
$ 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
|
||||
|
|
@ -98,6 +93,22 @@ by the ``ghp-import`` command) to the ``elemoine.github.io`` repository's
|
|||
|
||||
To publish your Pelican site as User Pages, feel free to adjust the
|
||||
``github`` target of the Makefile.
|
||||
|
||||
Another option for publishing to User Pages is to generate the output files in
|
||||
the root directory of the project.
|
||||
|
||||
For example, your main project folder is ``<username>.github.io`` and you can
|
||||
create the Pelican project in a subdirectory called ``Pelican``. Then from
|
||||
inside the ``Pelican`` folder you can run::
|
||||
|
||||
$ pelican content -o .. -s pelicanconf.py
|
||||
|
||||
Now you can push the whole project ``<username>.github.io`` to the master
|
||||
branch of your GitHub repository::
|
||||
|
||||
$ git push origin master
|
||||
|
||||
(assuming origin is set to your remote repository).
|
||||
|
||||
Custom 404 Pages
|
||||
----------------
|
||||
|
|
@ -108,8 +119,8 @@ relevant `GitHub docs <https://help.github.com/articles/custom-404-pages/>`_.
|
|||
Update your site on each commit
|
||||
-------------------------------
|
||||
|
||||
To automatically update your Pelican site on each commit, you can create
|
||||
a post-commit hook. For example, you can add the following to
|
||||
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 content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
|
||||
|
|
@ -130,8 +141,8 @@ output directory. For example::
|
|||
|
||||
Note: use forward slashes, ``/``, even on Windows.
|
||||
|
||||
You can also use the ``EXTRA_PATH_METADATA`` mechanism
|
||||
to place a ``favicon.ico`` or ``robots.txt`` at the root of any site.
|
||||
You can also use the ``EXTRA_PATH_METADATA`` mechanism to place a
|
||||
``favicon.ico`` or ``robots.txt`` at the root of any site.
|
||||
|
||||
How to add YouTube or Vimeo Videos
|
||||
==================================
|
||||
|
|
@ -147,3 +158,25 @@ embed videos in the markup. You can use `reST video directive
|
|||
<https://gist.github.com/dbrgn/2922648>`_ for reST or `mdx_video plugin
|
||||
<https://github.com/italomaia/mdx-video>`_ for Markdown.
|
||||
|
||||
|
||||
Develop Locally Using SSL
|
||||
==================================
|
||||
|
||||
Here's how you can set up your local pelican server to support SSL.
|
||||
|
||||
First, create a self-signed certificate and key using ``openssl`` (this creates ``cert.pem`` and ``key.pem``)::
|
||||
|
||||
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
|
||||
|
||||
And use this command to launch the server (the server starts within your ``output`` directory)::
|
||||
|
||||
python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem
|
||||
|
||||
If you are using ``develop-server.sh``, add this to the top::
|
||||
|
||||
CERT="$BASEDIR/cert.pem"
|
||||
KEY="$BASEDIR/key.pem"
|
||||
|
||||
and modify the ``pelican.server`` line as follows::
|
||||
|
||||
$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &
|
||||
Loading…
Add table
Add a link
Reference in a new issue