The Show Source Pelican Plugin

Rationale

#

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 ReadMe.rst file included as part of the plugin.

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](#Make Source Available for Posts)

Add to the Plugins List

#

Add an entry to the PLUGINS list of show_source.

PLUGINS = ['show_source', ... ]

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):

SHOW_SOURCE_ON_SIDEBAR = True
SHOW_SOURCE_IN_SECTION = True

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 SHOW_SOURCE_ON_SIDEBAR = True to your settings file and modify your theme HTML. The example here is using the pelican-bootstrap3 theme:

{% 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:

Article Section Links

#

Add 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 source link at the bottom of an article:

{% 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:

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.

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:

:show_source: True

or, in Markdown syntax

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:

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:

ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%m}/{slug}/index.html'

Your static HTML post and source text document will be like the following:

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:

SHOW_SOURCE_FILENAME = 'my_source_file.txt'

So with the ARTICLE_SAVE_AS configured as above, the files would be saved thus:

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.