github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'master' into pathdocs

Browse source
This commit is contained in:
Justin Mayer 2020-04-15 09:20:03 +02:00 • committed by GitHub
commit e9f81d3f9c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
389 changed files with 10281 additions and 4330 deletions
Download patch file Download diff file Expand all files Collapse all files

212
docs/content.rst
View file

@ -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::
![Alt Text]({filename}/images/han.jpg)
[Our Menu]({filename}/pdfs/menu.pdf)
``pelicanconf.py`` would include::
STATIC_PATHS = ['images', 'pdfs']
![Alt Text]({static}/images/han.jpg)
[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