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.

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


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.

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

    {% if article and article.show_source_url %}
    <section class="well" id="show-source">
        <h4>This Page</h4>
            <a href="{{ SITEURL }}/{{ article.show_source_url }}">Show source</a>
    {% endif %}
{% endif %}

With the theme and settings ready, any enabled article or post will have a section link looking like the following:


Show source link underneath post


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:


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:


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:


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.


comments powered by Disqus