Contents
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:
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 souce 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.
Comments
comments powered by Disqus