Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
ReadMe.rst
__init__.py
show_source.py

ReadMe.rst

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.

Plugin Activation

To activate the plugin ensure that you have SHOW_SOURCE_ON_SIDEBAR = True or SHOW_SOURCE_IN_SECTION = True your settings file.

Making 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.

Show Source in the Templates

To get the show source links on the article or page you will have to modify your theme, either as a sidebar display or at the foot of an article.

Article or Page Sidebar Display

How to get the source link to appear in the sidebar 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 %}

Article Footer Display

Here's some code (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 %}

Overriding Default Plugin Behaviour

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 :py:`SHOW_SOURCE_ALL_POSTS = True` 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.

Unless overridden, each document is saved as the article or page slug attribute with a .txt extension.

So for example, if your configuration 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.