Varia's website, varia.zone or vvvvvvaria.org
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
mb@mb 04c2824180 adding the 2 submodules again 7 years ago
..
ReadMe.rst adding the 2 submodules again 7 years ago
__init__.py adding the 2 submodules again 7 years ago
show_source.py adding the 2 submodules again 7 years ago

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:

.. 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) %}
<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:

.. code-block:: HTML

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

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