Skip to content
Permalink
Browse files

make the manual build

  • Loading branch information
ralsina committed Feb 14, 2016
1 parent c759429 commit bb507ab0e36148ea05c4f4a95df0ec9b4ecaa605
Showing with 12 additions and 12 deletions.
  1. +6 −6 docs/manual.txt
  2. +3 −3 nikola/plugins/compile/rest/chart.py
  3. +3 −3 nikola/plugins/compile/rest/media.py
@@ -813,15 +813,15 @@ 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 ``{{% name parameters %}}`` 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 {{% raw %}}{{% name parameters %}}{{% /raw %}} 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".

Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing shortcodes match (name only), the closing being prepended with a slash.

Example of a paired shortcode (note that we don't have a highlight shortcode yet ;-)::

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

Built-in shortcodes
~~~~~~~~~~~~~~~~~~~
@@ -832,21 +832,21 @@ post-list
media
Display media embedded from a URL, for example, this will embed a youtube video::

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

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

{{% chart Bar title='Browser usage evolution (in %)'
{{% raw %}}{{% 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 %}}
{{% /chart %}}{{% /raw %}}

In reStructuredText the quoting needed to pass arguments gets insane really fast, use the chart directive
instead (the syntax is nicer anyway)
@@ -867,7 +867,7 @@ For example, if your ``shortcodes/foo.tmpl`` contains this::

And your post contains this::

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

Then the output file will contain::

@@ -52,7 +52,7 @@ def set_site(self, site):
global _site
_site = self.site = site
directives.register_directive('chart', Chart)
self.site.register_shortcode('chart', _gen_html)
self.site.register_shortcode('chart', _gen_chart)
return super(Plugin, self).set_site(site)


@@ -136,11 +136,11 @@ class Chart(Directive):
def run(self):
"""Run the directive."""
self.options['site'] = None
html = _gen_html(self.arguments[0], data='\n'.join(self.content), **self.options)
html = _gen_chart(self.arguments[0], data='\n'.join(self.content), **self.options)
return [nodes.raw('', html, format='html')]


def _gen_html(chart_type, **_options):
def _gen_chart(chart_type, **_options):
if pygal is None:
msg = req_missing(['pygal'], 'use the Chart directive', optional=True)
return '<div class="text-error">{0}</div>'.format(msg)
@@ -48,7 +48,7 @@ def set_site(self, site):
"""Set Nikola site."""
self.site = site
directives.register_directive('media', Media)
self.site.register_shortcode('media', _gen_html)
self.site.register_shortcode('media', _gen_media_embed)
return super(Plugin, self).set_site(site)


@@ -61,10 +61,10 @@ class Media(Directive):

def run(self):
"""Run media directive."""
html = _gen_html(" ".join(self.arguments))
html = _gen_media_embed(" ".join(self.arguments))
return [nodes.raw('', html, format='html')]

def _gen_html(url, *q, **kw):
def _gen_media_embed(url, *q, **kw):
if micawber is None:
msg = req_missing(['micawber'], 'use the media directive', optional=True)
return '<div class="text-error">{0}</div>'.format(msg)

0 comments on commit bb507ab

Please sign in to comment.