The Show Source Pelican Plugin
##############################
:title: The Show Source Pelican Plugin
:date: 2016-11-06
:modified: 2020-01-12
:category: Software
:tags: programming, pelican, python
:slug: the-show-source-pelican-plugin
:series: Pelican Plugins
:author: Chris Ramsay
:status: published
:language: en
:show_source: True
.. role:: bash(code)
:language: bash
.. role:: py(code)
:language: python
.. |nbsp| unicode:: 0xA0
:trim:
.. contents::
Rationale
---------
.. PELICAN_BEGIN_SUMMARY
I have always been a fan of the `Sphinx`_ Python documentation generator and it
has, I think, a nice feature where you can check out the raw source of a
generated piece of documentation - a *Show Source* link. I decided that
developing a `Pelican plugin`_ to imitate that feature would be a great way of
getting a little deeper into the Pelican code itself.
This second post of the series explains the use of the Show Source plugin that I
developed from the learning in the `previous post`_. The following article has
been, in some part, reproduced in the :bash:`ReadMe.rst` file included as part
of the plugin.
.. PELICAN_END_SUMMARY
The Show Source plugin
----------------------
The plugin allows you to place a link to the source text of your posts in the
same way that `Sphinx`_ does. It works for both pages and articles, reading the
source file and then placing a copy next to your published HTML version ready
to be served when requested.
I have designed the plugin to show source links on two different parts of a
Pelican site: a link in the section below a post, and a link in the sidebar to
the left or right of a post depending on your theme.
Plugin Activation
~~~~~~~~~~~~~~~~~
There are four things you have to do to get the plugin working:
1. `Add to the Plugins List`_
2. `Add a Config Setting or Two`_
3. `Prepare the Theme`_
4. `Make Source Available for Posts`_
.. _`Add to the Plugins List`:
Add to the Plugins List
~~~~~~~~~~~~~~~~~~~~~~~
Add an entry to the :py:`PLUGINS` list of :py:`show_source`.
.. code-block:: Python
PLUGINS = ['show_source', ... ]
.. _`Add a Config Setting or Two`:
Add a Config Setting or Two
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Depending on where you would like the links to appear, add a config setting (or
both if you want):
.. code-block:: Python
SHOW_SOURCE_ON_SIDEBAR = True
SHOW_SOURCE_IN_SECTION = True
.. _`Prepare the Theme`:
Prepare the Theme
~~~~~~~~~~~~~~~~~
To get the show source links on the article or page you will have to modify your
theme, either as a sidebar display or in a section underneath an article.
Sidebar Links
*************
Add :py:`SHOW_SOURCE_ON_SIDEBAR = True` to your settings file and modify your
theme HTML. The example here is using the `pelican-bootstrap3`_ theme:
.. code-block:: HTML
{% if SHOW_SOURCE_ON_SIDEBAR %}
{% if (article and article.show_source_url) or (page and page.show_source_url) %}
This Page
{% endif %}
{% endif %}
With the theme and settings ready, any enabled article or post will have a
sidebar link like this:
|nbsp|
.. image:: https://live.staticflickr.com/65535/49372384921_3c1089a064_o.png
:width: 277
:height: 131
:scale: 100
:alt: Show source link in sidebar
|nbsp|
Article Section Links
*********************
Add :py:`SHOW_SOURCE_IN_SECTION = True` to your settings file, and modify your
theme's article template, here is an example of HTML (yes,
`pelican-bootstrap3`_ again) to enable a souce link at the bottom of an article:
.. code-block:: HTML
{% if SHOW_SOURCE_IN_SECTION %}
{% if article and article.show_source_url %}
{% endif %}
{% endif %}
With the theme and settings ready, any enabled article or post will have a
section link looking like the following:
|nbsp|
.. image:: https://live.staticflickr.com/65535/49372588802_b809bb4392_o.png
:width: 640
:height: 96
:scale: 100
:alt: Show source link underneath post
|nbsp|
For the theme I use I created a separate include with the code in and imported
it into the article HTML with `Jinja2's`_ ``include`` directive.
.. _`Make Source Available for Posts`:
Mark Source Available for Posts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to mark posts so that their source may be seen use the following
metadata values (unless overridden)- for reStructuredText documents:
.. code-block:: reStructuredText
:show_source: True
or, in Markdown syntax
.. code-block:: Markdown
Show_source: True
The plugin will render your source document URL to a corresponding
``article.show_source_url`` (or ``page.show_source_url``) attribute which is
then accessible in the site templates.
Overriding Default Plugin Behaviour
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are, currently, two override options to the default behaviour of the
plugin.
Show Source for All Posts
*************************
The default behaviour of the plugin is that revealing source is enabled on a
case by case basis. This can be changed by the use of the following in the
settings file:
.. code-block:: Python
SHOW_SOURCE_ALL_POSTS = True
This does mean that the plugin will publish all source documents no matter
whether ``show_source`` is set in the metadata or not.
Source File Output Name
***********************
Unless overridden, each document is saved as the article or page slug attribute
with a ``.txt`` extension.
So for example, if your settings file had ``ARTICLE_SAVE_AS`` configured like
so:
.. code-block:: python
ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%m}/{slug}/index.html'
Your static HTML post and source text document will be like the following:
.. code-block:: Text
posts/2016/10/welcome-to-my-article/index.html
posts/2016/10/welcome-to-my-article/welcome-to-my-article.txt
You can add the ``SHOW_SOURCE_FILENAME`` variable in your settings file to
override the source file name, so you could set the following:
.. code-block:: python
SHOW_SOURCE_FILENAME = 'my_source_file.txt'
So with the ``ARTICLE_SAVE_AS`` configured as above, the files would be saved
thus:
.. code-block:: Text
posts/2016/10/welcome-to-my-article/index.html
posts/2016/10/welcome-to-my-article/my_source_file.txt
This is the same behaviour for pages also.
Plugin Availability
~~~~~~~~~~~~~~~~~~~
Currently this plugin is awaiting a pull request with the developers at
`getpelican/pelican-plugins`_, so for now it's available from my repo here on a
`feature/show_source`_ branch, until further notice.
.. footnotes
.. links
.. _`Sphinx`: http://www.sphinx-doc.org/
.. _`previous post`: {filename}/software/2016-11-04_basic-notes-on-pelican-plugin-architecture.rst
.. _`Pelican plugin`: https://github.com/getpelican/pelican-plugins
.. _`pelican-bootstrap3`: https://github.com/getpelican/pelican-themes/tree/master/pelican-bootstrap3
.. _`Jinja2's`: http://jinja.pocoo.org/
.. _`getpelican/pelican-plugins`: https://github.com/getpelican/pelican-plugins
.. _`feature/show_source`: https://github.com/chrisramsay/pelican-plugins/tree/feature/show_source/show_source