Skip to content
Permalink
Browse files
added a sc role so shortcodes are useful in reSt
  • Loading branch information
ralsina committed Jun 4, 2016
1 parent 2570291 commit 1f8f869d16bfec454dec4bdab2ae1fad89943c7d
Showing with 28 additions and 9 deletions.
  1. +1 −0 CHANGES.txt
  2. +18 −9 docs/manual.txt
  3. +9 −0 nikola/plugins/compile/rest/__init__.py
@@ -4,6 +4,7 @@ New in master
Features
--------

* New ``sc`` or ``html`` reSt role, which passes content unaltered (Issue #1854)
* Point the user to our users site after 1st successful deploy (Issue #2096)
* Option to disable color output using ``NIKOLA_MONO`` environment
variable (Issue #2360)
@@ -813,7 +813,7 @@ To use them from plugins, please see `Extending Nikola <https://getnikola.com/ex
Using a shortcode
~~~~~~~~~~~~~~~~~

In your content files, a shortcode can be called by using the {{% raw %}}{{% name parameters %}}{{% /raw %}} form. Shortcode parameters are space delimited. Parameters with spaces can be quoted (or backslash escaped).
In your content files, a shortcode can be called by using the :sc:`{{% name parameters %}}` form. Shortcode parameters are space delimited. Parameters with spaces can be quoted (or backslash escaped).

The first word is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional or both. The format for named parameters models that of HTML with the format name="value".

@@ -823,6 +823,19 @@ Example of a paired shortcode (note that we don't have a highlight shortcode yet

{{% raw %}}{{% highlight python %}} A bunch of code here {{% /highlight %}}{{% /raw %}}

.. note:: Shortcodes and reStructuredText

In reStructuredText shortcodes may fail because docutils turns URL into links and everything breaks.
For some shortcodes there are alternative docutils directives (example, you can use the media
**directive** instead of the media shortcode.

Also, you can use the shortcode **role**::

:sc:`{{% shortcode here %}}`

That role passes text unaltered, so shortcodes behave correctly.


Built-in shortcodes
~~~~~~~~~~~~~~~~~~~

@@ -832,24 +845,20 @@ post-list
media
Display media embedded from a URL, for example, this will embed a youtube video::

{{% raw %}}{{% media url="https://www.youtube.com/watch?v=Nck6BZga7TQ" %}}{{% /raw %}}
{{% media url="https://www.youtube.com/watch?v=Nck6BZga7TQ" %}}

In reStructuredText this shortcode will fail because docutils turns that URL to a link and everything breaks, use the `media directive <#media>`__ instead.

chart
Create charts via PyGal. This is similar to the `chart directive <#chart>`__ except the syntax is adapted to
shortcodes. This is an example::

{{% raw %}}{{% chart Bar title='Browser usage evolution (in %)' %}}
{{% chart Bar title='Browser usage evolution (in %)' %}}
x_labels='["2002","2003","2004","2005","2006","2007","2008","2009","2010","2011","2012"]'%}}
'Firefox', [None, None, 0, 16.6, 25, 31]
'Chrome', [None, None, None, None, None, None]
'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6]
'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4]
{{% /chart %}}{{% /raw %}}

In reStructuredText the quoting needed to pass arguments gets insane really fast, use the chart directive
instead (the syntax is nicer anyway)
{{% /chart %}}

Community shortcodes
~~~~~~~~~~~~~~~~~~~~
@@ -876,7 +885,7 @@ For example, if your ``shortcodes/foo.tmpl`` contains this::

And your post contains this::

{{% raw %}}{{% foo bar=bla %}}{{% /raw %}}
{{% foo bar=bla %}}

Then the output file will contain::

@@ -37,6 +37,7 @@
import docutils.readers.standalone
import docutils.writers.html4css1
import docutils.parsers.rst.directives
from docutils.parsers.rst import roles

from nikola.plugin_categories import PageCompiler
from nikola.utils import unicode_str, get_logger, makedirs, write_metadata, STDERR_HANDLER
@@ -192,6 +193,14 @@ def new_document(self):
document.reporter.attach_observer(get_observer(self.l_settings))
return document

def shortcode_role(name, rawtext, text, lineno, inliner,
options={}, content=[]):
return [docutils.nodes.raw('', text, format='html')], []

roles.register_canonical_role('raw-html', shortcode_role)
roles.register_canonical_role('html', shortcode_role)
roles.register_canonical_role('sc', shortcode_role)


def add_node(node, visit_function=None, depart_function=None):
"""Register a Docutils node class.

0 comments on commit 1f8f869

Please sign in to comment.