Skip to content
Permalink
Browse files
Nikola v7.7.8
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed Apr 29, 2016
1 parent 73a4831 commit 9baf569c8d9b34bac3faeb7269bfbc5dd74604dc
Showing 9 changed files with 175 additions and 37 deletions.
@@ -0,0 +1,56 @@
.. title: Nikola v7.7.8 is out!
.. slug: nikola-v778-is-out
.. date: 2016-04-29 12:22:56 UTC
.. tags: nikola, planet, python, programming, release
.. category:
.. link:
.. description:
.. type: text
.. author: Chris Warrick

On behalf of the Nikola team, I am pleased to announce the immediate
availability of Nikola v7.7.8. It fixes some bugs and adds (minor) new
features.

What is Nikola?
===============

Nikola is a static site and blog generator, written in Python.
It can use Mako and Jinja2 templates, and input in many popular markup
formats, such as reStructuredText and Markdown — and can even turn
Jupyter (IPython) Notebooks into blog posts! It also supports image
galleries, and is multilingual. Nikola is flexible, and page builds
are extremely fast, courtesy of doit (which is rebuilding only what
has been changed).

Find out more at the website: https://getnikola.com/

Downloads
=========

Install using ``pip install Nikola`` or download tarballs on `GitHub`__ and `PyPI`__.

__ https://github.com/getnikola/nikola/releases/tag/v7.7.8
__ https://pypi.python.org/pypi/Nikola/7.7.8

Changes
=======

Features
--------

* Template-based shortcodes now receive positional arguments too (Issue #2319)

Bugfixes
--------

* Use state files in ``nikola github_deploy`` and ``nikola status``
(Issue #2317)
* Add ``align`` options for ``youtube``, ``vimeo``, ``soundcloud``
reST directives (Issue #2304)
* Update ``FILE_METADATA_REGEXP`` example in docs (Issue #2296)
* Show “tags too similar” error instead of cryptic doit crash (Issue #2325)
* Fix crashes when tag appears multiple times in a post (Issue #2315)
* Use binary I/O for ``.svg`` files in galleries
* Accept ``.svgz`` extension by default
* Don't randomly load plugins when Nikola is called with no arguments (Issue #2297)
@@ -0,0 +1,3 @@
{
"last_deploy": "2016-02-11T18:03:22.825787"
}
@@ -15,6 +15,7 @@
* `Casey M. Bessette <https://github.com/caseybessette>`_
* `Chris Lee <https://github.com/clee>`_
* `Chris Warrick <https://github.com/Kwpolska>`_
* `Christopher Arndt <https:/github.com/SpotlightKid>`_
* `Claudio Canepa <https://github.com/ccanepa>`_
* `Damien Tournoud <https://github.com/damz>`_
* `Damián Avila <https://github.com/damianavila>`_
@@ -1,3 +1,25 @@
New in v7.7.8
=============

Features
--------

* Template-based shortcodes now receive positional arguments too (Issue #2319)

Bugfixes
--------

* Use state files in ``nikola github_deploy`` and ``nikola status``
(Issue #2317)
* Add ``align`` options for ``youtube``, ``vimeo``, ``soundcloud``
reST directives (Issue #2304)
* Update ``FILE_METADATA_REGEXP`` example in docs (Issue #2296)
* Show “tags too similar” error instead of cryptic doit crash (Issue #2325)
* Fix crashes when tag appears multiple times in a post (Issue #2315)
* Use binary I/O for ``.svg`` files in galleries
* Accept ``.svgz`` extension by default
* Don't randomly load plugins when Nikola is called with no arguments (Issue #2297)

New in v7.7.7
=============

@@ -1,10 +1,10 @@
.. title: Nikola v7.7.7 configuration file
.. title: Nikola v7.7.8 configuration file
.. slug: conf
.. date: 2014-11-08 18:51:30 UTC
.. description: The Nikola configuration file.
.. type: text
.. author: The Nikola Team

The default config file for Nikola v7.7.6 is reproduced below.
The default config file for Nikola v7.7.8 is reproduced below.

.. listing:: conf.py python
@@ -9,7 +9,7 @@
Extending Nikola
================

:Version: 7.7.7
:Version: 7.7.8
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>

.. class:: alert alert-info pull-right
@@ -560,38 +560,76 @@ Some (hopefully all) markup compilers support shortcodes in these forms::
{{% foo %}} # No arguments
{{% foo bar %}} # One argument, containing "bar"
{{% foo bar baz=bat %}} # Two arguments, one containing "bar", one called "baz" containing "bat"

{{% foo %}}Some text{{% /foo %}} # one argument called "data" containing "Some text"

So, if you are creating a plugin that generates markup, it may be a good idea to register it as a shortcode
in addition of a restructured text directive or markdown extension, thus making it available to all markups.

To implement your own shortcodes from a plugin, you can call ``Nikola.register_shortcode(name, f)`` with the following
arguments:

name:
name of the shortcode (foo in the examples above)
f:

{{% foo %}}Some text{{% /foo %}} # one argument called "data" containing "Some text"

So, if you are creating a plugin that generates markup, it may be a good idea
to register it as a shortcode in addition of to restructured text directive or
markdown extension, thus making it available to all markup formats.

To implement your own shortcodes from a plugin, you can call
``Nikola.register_shortcode(name, func)`` with the following arguments:

``name``:
Name of the shortcode ("foo" in the examples above)
``func``:
A function that will handle the shortcode

The shortcode handler should take *at least* the following named arguments:

site:
The shortcode handler **must** accept the following named arguments (or
variable keyword arguments):

``site``:
An instance of the Nikola class, to access site state

data:
If the shortcut is used as opening/closing tags, it will be the text between them, otherwise None

If the shortcode tag has arguments of the form "foo=bar" they will be passed as named arguments. Everything else
will be passed as positional arguments in the function call.

``data``:
If the shortcut is used as opening/closing tags, it will be the text
between them, otherwise ``None``.

If the shortcode tag has arguments of the form ``foo=bar`` they will be
passed as named arguments. Everything else will be passed as positional
arguments in the function call.

So, for example::

{{% foo bar baz=bat beep %}}Some text{{% /foo %}}

Will cause a call like this::
{{% raw %}}{{% foo bar baz=bat beep %}}Some text{{% /foo %}}{{% /raw %}}

Assuming you registered ``foo_handler`` as the handler function for the
shortcode named ``foo``, this will result in the following call when the above
shortcode is encountered::

foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)

Template-based Shortcodes
-------------------------

Another way to define a new shortcode is to add a template file to the
``shortcodes`` directory of your site. The template file must have the
shortcode name as the basename and the extension ``.tmpl``. For example, if you
want to add a new shortcode named ``foo``, create the template file as
``shortcodes/foo.tmpl``.

When the shortcode is encountered, the matching template will be rendered with
its context provided by the arguments given in the shortcode. Keyword arguments
are passed directly, i.e. the key becomes the variable name in the template
namespace with a matching string value. Non-keyword arguments are passed as
string values in a tuple named ``_args``. As for normal shortcodes with a
handler function, ``site`` and ``data`` will be added to the keyword arguments.

Example:

The following shortcode::

{{% raw %}}{{% foo bar="baz" spam %}}{{% /raw %}}

With a template in ``shortcodes/foo.tmpl`` with this content (using Jinja2
syntax in this example)::

<div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div>

Will result in this output::

<div class="spam">baz</div>

foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)

State and Cache
===============
@@ -601,7 +639,7 @@ Sometimes your plugins will need to cache things to speed up further actions. He
* If it's a file, put it somewhere in ```self.site.config['CACHE_FOLDER']``` (defaults to ```cache/```.
* If it's a value, use ```self.site.cache.set(key, value)``` to set it and ```self.site.cache.get(key)``` to get it.
The key should be a string, the value should be json-encodable (so, be careful with datetime objects)

The values and files you store there can **and will** be deleted sometimes by the user. They should always be
things you can reconstruct without lossage. They are throwaways.

@@ -9,7 +9,7 @@
The Nikola Handbook
===================

:Version: 7.7.7
:Version: 7.7.8

.. class:: alert alert-info pull-right

@@ -851,15 +851,24 @@ chart
In reStructuredText the quoting needed to pass arguments gets insane really fast, use the chart directive
instead (the syntax is nicer anyway)

Community shortcodes
~~~~~~~~~~~~~~~~~~~~

** `audio <https://gist.github.com/SpotlightKid/70f3ccdfacd9cfb091941a91f349924f>`_ by `SpotlightKid <https://github.com/SpotlightKid>`_ — embed a HTML5 audio player and download links

Template-based shortcodes
~~~~~~~~~~~~~~~~~~~~~~~~~

If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola will create a shortcode
called ``mycode`` you can use. Any options you pass to the shortcode will be available as variables
for that template. If you use the shortcode as paired, then the contents between the paired tags will
be available in the ``data`` variable.
If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola
will create a shortcode called ``mycode`` you can use. Any options you pass to
the shortcode will be available as variables for that template. Non-keyword
options will be passed in a tuple varaible named ``_args``.

If you use the shortcode as paired, then the contents between the paired tags
will be available in the ``data`` variable. If you want to access the Nikola
object, it will be available as ``site``. Use with care :-)

If you want to access the Nikola object, it will be available as ``site``. Use with care :-)
See :doc:`extending` for detailed information.

For example, if your ``shortcodes/foo.tmpl`` contains this::

@@ -1653,6 +1662,9 @@ Once you have that, all you need to do is:

.. youtube:: 8N_tupPBtWQ

Supported options: ``height``, ``width``, ``align`` (one of ``left``,
``center``, ``right``) — all are optional.

Vimeo
~~~~~

@@ -1675,6 +1687,9 @@ You can override this if you wish:
:height: 240
:width: 320

Supported options: ``height``, ``width``, ``align`` (one of ``left``,
``center``, ``right``) — all are optional.

Soundcloud
~~~~~~~~~~

@@ -1696,6 +1711,9 @@ You can also embed playlists, via the `soundcloud_playlist` directive which work

.. soundcloud_playlist:: 9411706

Supported options: ``height``, ``width``, ``align`` (one of ``left``,
``center``, ``right``) — all are optional.

Code
~~~~

@@ -9,7 +9,7 @@
Using Alternative Social Buttons with Nikola
============================================

:Version: 7.7.7
:Version: 7.7.8

.. class:: alert alert-info pull-right

@@ -9,7 +9,7 @@
Theming Nikola
==============

:Version: 7.7.7
:Version: 7.7.8
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>

.. class:: alert alert-info pull-right

0 comments on commit 9baf569

Please sign in to comment.