Skip to content

Latest commit

 

History

History
160 lines (112 loc) · 5.79 KB

README.md

File metadata and controls

160 lines (112 loc) · 5.79 KB
Raw

Show Source: A Plugin for Pelican

Build Status PyPI Version License

This Pelican plugin allows you to place a link to your posts’ source content files in the same way that Sphinx does. It works for both pages and articles.

Installation

This plugin can be installed via:

python -m pip install pelican-show-source

For more detailed plugin installation instructions, please refer to the Pelican Plugin Documentation.

Configuration

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

SHOW_SOURCE_ALL_POSTS = True will show the source for all posts, instead of only posts with the source explicitly made available (see below.) By default, this is False.

The option SHOW_SOURCE_AUTOEXT (False by default) controls the extension of the output source file. If True, the file will have the same extension as the real source document (.rst, .md, etc). Otherwise, it will be a plain-text .txt file.

Making Source Available for Posts

In order to mark posts so that their source may be seen, use the following metadata fields (unless overridden) for reStructuredText documents:

:show_source: True

Alternatively, for 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 to display in 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

Following is some code (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 %}

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 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 as well.

Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.

To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.

Testing

The testing is done using pytest (from the clone/checkout directory).

Linux/Mac:

PYTHONPATH=. py.test -vvs pelican/plugins/test/test_show_source.py

Windows:

SET PYTHONPATH=%CD%
py.test -vvs pelican\plugins\test\test_show_source.py

NOTE: If your python environment has installed pelican-show-source you need to uninstall it first.

License

This project is licensed under the AGPL-3.0 license.