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) %}
            <li class="list-group-item"><h4><i class="fa fa-tags fa-file-text"></i><span class="icon-label">This Page</span></h4>
                <ul class="list-group">
                    <li class="list-group-item">
                        {% if article %}
                        <a href="{{ SITEURL }}/{{ article.show_source_url }}">Show source</a>
                        {% elif page %}
                        <a href="{{ SITEURL }}/{{ page.show_source_url }}">Show source</a>
                        {% endif %}
                    </li>
                </ul>
            </li>
        {% 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 %}
        <section class="well" id="show-source">
            <h4>This Page</h4>
            <ul>
                <a href="{{ SITEURL }}/{{ article.show_source_url }}">Show source</a>
            </ul>
        </section>
        {% 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