pelican-plugins/show_source

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:

.. code-block:: reStructuredText

:show_source: True

or, in Markdown syntax

.. code-block:: Markdown

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:

.. code-block:: HTML

{% if SHOW_SOURCE_ON_SIDEBAR %}
{% if (article and article.show_source_url) or (page and page.show_source_url) %}

This Page

• 
  {% if article %}
  Show source
  {% elif page %}
  Show source
  {% endif %}
  

{% endif %}
{% endif %}

Article Footer Display
**********************

Here's some code (yes, `pelican-bootstrap3`_ again) to enable a souce link at
the bottom of an article:

.. code-block:: HTML

{% if SHOW_SOURCE_IN_SECTION %}
{% if article and article.show_source_url %}

This Page

Show source

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

.. code-block:: python

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

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

.. code-block:: Text

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:

.. code-block:: python

SHOW_SOURCE_FILENAME = 'my_source_file.txt'

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

.. code-block:: Text

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.

.. _`Sphinx`: http://www.sphinx-doc.org/
.. _`pelican-bootstrap3`: https://github.com/getpelican/pelican-themes/tree/master/pelican-bootstrap3