Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Nikola v7.7.5
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed Feb 11, 2016
1 parent 8ad6615 commit dec4da4
Show file tree
Hide file tree
Showing 10 changed files with 323 additions and 125 deletions.
14 changes: 12 additions & 2 deletions listings/conf.py
Expand Up @@ -49,6 +49,7 @@
# fa Persian
# fi Finnish
# fr French
# gl Galician
# hi Hindi
# hr Croatian
# hu Hungarian
Expand Down Expand Up @@ -169,10 +170,12 @@
POSTS = (
("posts/*.rst", "posts", "post.tmpl"),
("posts/*.txt", "posts", "post.tmpl"),
("posts/*.html", "posts", "post.tmpl"),
)
PAGES = (
("stories/*.rst", "stories", "story.tmpl"),
("stories/*.txt", "stories", "story.tmpl"),
("stories/*.html", "stories", "story.tmpl"),
)


Expand Down Expand Up @@ -226,8 +229,8 @@
# FILES_FOLDERS = {'files': ''}
# Which means copy 'files' into 'output'

# One or more folders containing listings to be processed and stored into
# the output. The format is a dictionary of {source: relative destination}.
# One or more folders containing code listings to be processed and published on
# the site. The format is a dictionary of {source: relative destination}.
# Default is:
# LISTINGS_FOLDERS = {'listings': 'listings'}
# Which means process listings from 'listings' into 'output/listings'
Expand Down Expand Up @@ -532,6 +535,9 @@
# ]
# }

# github_deploy configuration
# For more details, read the manual:
# https://getnikola.com/handbook.html#deploying-to-github
# For user.github.io OR organization.github.io pages, the DEPLOY branch
# MUST be 'master', and 'gh-pages' for other repositories.
# GITHUB_SOURCE_BRANCH = 'master'
Expand All @@ -540,6 +546,10 @@
# The name of the remote where you wish to push to, using github_deploy.
# GITHUB_REMOTE_NAME = 'origin'

# Whether or not github_deploy should commit to the source branch automatically
# before deploying.
GITHUB_COMMIT_SOURCE = True

# Where the output site should be located
# If you don't use an absolute path, it will be considered as relative
# to the location of conf.py
Expand Down
69 changes: 69 additions & 0 deletions posts/nikola-v775-is-out.txt
@@ -0,0 +1,69 @@
.. title: Nikola v7.7.5 is out!
.. slug: nikola-v775-is-out
.. date: 2016-02-11 17:55:45 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.5. It fixes some bugs and adds 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.5
__ https://pypi.python.org/pypi/Nikola/7.7.5

Changes
=======

Features
--------

* Add ``nikola theme --new`` command for creating new themes (Issue #2231)
* Add ``nikola theme --copy-template`` command for copying templates
to customize them (Issue #2231)
* Add ``nikola theme --uninstall`` command for deleting themes (Issue #2231)
* Replace ``nikola install_theme`` with more capable ``nikola theme``
command (Issue #2231)
* Allow for customizing ``github_deploy`` commit messages with ``-m``
(Issue #2198)
* Commit to source branch automatically in ``github_deploy``
if ``GITHUB_COMMIT_SOURCE`` is set to True (Issue #2186)
* Hugo-like shortcodes (Issue #1707)
* New Galician translation
* New facilities for data persistence and data caching (Issues #2209 and #2009)
* (internal) allow ``scripts/jinjify.py`` usage with scripts (Issue #2240)

Bugfixes
--------

* Fix some rebuilds with indexes and galleries
* Make state files work on Python 3
* Don’t attempt to create redirects for URLs with query strings in
WordPress imports if the site is in a subdirectory (Issue #2224)
* Avoid some random file rebuilds (Issue #2220)
* Honor ``MATHJAX_CONFIG`` setting
* Display tags and archives in a unified format, with the date on the
left, instead of a misplaced dash in tags (Issue #2212)
* Decide ``is_mathjax`` based on current language tags (Issue #2205)
* Don't duplicate images in flowr when resizing page (Issue #2202)
37 changes: 37 additions & 0 deletions stories/CHANGES.txt
@@ -1,3 +1,38 @@
New in v7.7.5
=============

Features
--------

* Add ``nikola theme --new`` command for creating new themes (Issue #2231)
* Add ``nikola theme --copy-template`` command for copying templates
to customize them (Issue #2231)
* Add ``nikola theme --uninstall`` command for deleting themes (Issue #2231)
* Replace ``nikola install_theme`` with more capable ``nikola theme``
command (Issue #2231)
* Allow for customizing ``github_deploy`` commit messages with ``-m``
(Issue #2198)
* Commit to source branch automatically in ``github_deploy``
if ``GITHUB_COMMIT_SOURCE`` is set to True (Issue #2186)
* Hugo-like shortcodes (Issue #1707)
* New Galician translation
* New facilities for data persistence and data caching (Issues #2209 and #2009)
* (internal) allow ``scripts/jinjify.py`` usage with scripts (Issue #2240)

Bugfixes
--------

* Fix some rebuilds with indexes and galleries
* Make state files work on Python 3
* Don’t attempt to create redirects for URLs with query strings in
WordPress imports if the site is in a subdirectory (Issue #2224)
* Avoid some random file rebuilds (Issue #2220)
* Honor ``MATHJAX_CONFIG`` setting
* Display tags and archives in a unified format, with the date on the
left, instead of a misplaced dash in tags (Issue #2212)
* Decide ``is_mathjax`` based on current language tags (Issue #2205)
* Don't duplicate images in flowr when resizing page (Issue #2202)

New in v7.7.4
=============

Expand Down Expand Up @@ -1682,3 +1717,5 @@ Bugfixes
* Colorbox support in restructured text figures
* Fix for content displaying too wide
* Changelog

vim: tw=70 syntax=rst
4 changes: 2 additions & 2 deletions stories/conf.txt
@@ -1,10 +1,10 @@
.. title: Nikola v7.7.4 configuration file
.. title: Nikola v7.7.5 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.4 is reproduced below.
The default config file for Nikola v7.7.5 is reproduced below.

.. listing:: conf.py python
101 changes: 85 additions & 16 deletions stories/extending.txt
Expand Up @@ -9,7 +9,7 @@
Extending Nikola
================

:Version: 7.7.4
:Version: 7.7.5
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>

.. class:: alert alert-info pull-right
Expand Down Expand Up @@ -63,13 +63,13 @@ When you run ``nikola --help`` you will see something like this:
nikola import_feed import a RSS/Atom dump
nikola import_wordpress import a WordPress dump
nikola init create a Nikola site in the specified folder
nikola install_theme install theme into current site
nikola list list tasks from dodo file
nikola mincss apply mincss to the generated site
nikola new_post create a new blog post or site page
nikola run run tasks
nikola serve start the test webserver
nikola strace use strace to list file_deps and targets
nikola theme manage themes
nikola version print the Nikola version number

nikola help show help / reference
Expand Down Expand Up @@ -172,8 +172,8 @@ TemplateSystem Plugins
----------------------

Nikola supports Mako and Jinja2. If you prefer some other templating
system, then you will have to write a TemplateSystem plugin. Here's how they work.
First, you have to create a .plugin file. Here's the one for the Mako plugin:
system, then you will have to write a ``TemplateSystem`` plugin. Here's how they work.
First, you have to create a ``.plugin`` file. Here's the one for the Mako plugin:

.. code-block:: ini

Expand Down Expand Up @@ -253,10 +253,10 @@ Task Plugins
------------

If you want to do something that depends on the data in your site, you
probably want to do a Task plugin, which will make it be part of the
``nikola build`` command. There are the currently available tasks, all
probably want to do a ``Task`` plugin, which will make it be part of the
``nikola build`` command. These are the currently available tasks, all
provided by plugins:
T

.. sidebar:: Other Tasks

There are also ``LateTask`` plugins, which are executed later,
Expand Down Expand Up @@ -380,7 +380,7 @@ They must provide:
If the compiler produces something other than HTML files, it should also implement ``extension`` which
returns the preferred extension for the output file.

These plugins can also be used to extract metadata from file. To do so, the
These plugins can also be used to extract metadata from a file. To do so, the
plugin may implement ``read_metadata`` that will return a dict containing the
metadata contained in the file.

Expand All @@ -389,25 +389,27 @@ RestExtension Plugins

Implement directives for reStructuredText, see `media.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/media.py>`__ for a simple example.

If your output depends on a config value, you need to make your post record a dependency on a pseudo-path, like this:
If your output depends on a config value, you need to make your post record a
dependency on a pseudo-path, like this:

.. code-block:: text

####MAGIC####CONFIG:OPTIONNAME

Then, whenever the ``OPTIONNAME`` option is changed in conf.py, the file will be rebuilt.

If your directive depends or may depend on the whole timeline (like the post-list directive, where adding new posts
to the site could make it stale), you should record a dependency on the
pseudo-path ``####MAGIC####TIMELINE``.
If your directive depends or may depend on the whole timeline (like the
``post-list`` directive, where adding new posts to the site could make it
stale), you should record a dependency on the pseudo-path
``####MAGIC####TIMELINE``.

MarkdownExtension Plugins
-------------------------

Implement Markdown extensions, see `mdx_nikola.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/markdown/mdx_nikola.py>`__ for a simple example.

Note that python markdown extensions are often also available as separate packages. This is only meant to ship extensions
along with Nikola.
Note that Python markdown extensions are often also available as separate
packages. This is only meant to ship extensions along with Nikola.

SignalHandler Plugins
---------------------
Expand Down Expand Up @@ -477,7 +479,7 @@ Path/Link Resolution Mechanism

Any plugin can register a function using ``Nikola.register_path_handler`` to
allow resolution of paths and links. These are useful for templates, which
can access them via _link.
can access them via ``_link``.

For example, you can always get a link to the path for the feed of the "foo" tag
by using ``_link('tag_rss', 'foo')`` or the ``link://tag_rss/foo`` URL.
Expand Down Expand Up @@ -529,7 +531,7 @@ HTML:


The second argument to ``append()`` is used to determine whether the function
needs access to the current template context and the site. If it it set to
needs access to the current template context and the site. If it is set to
``True``, the function will also receive ``site`` and ``context`` keyword
arguments. Example use:

Expand All @@ -549,3 +551,70 @@ arguments. Example use:
endswith=endswith) + t

site.template_hooks['page_header'].append(greeting, True, u'Nikola Tesla', endswith=u'!')

Shortcodes
==========

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:
A function that will handle the shortcode

The shortcode handler should take *at least* the following named 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.

So, for example::

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

Will cause a call like this::

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

State and Cache
===============

Sometimes your plugins will need to cache things to speed up further actions. Here are the conventions for that:

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

On the other hand, sometimes you want to save something that is **not** a throwaway. These are things that may
change the output, so the user should not delete them. We call that **state**. To save state:

* If it's a file, put it somewhere in the working directory. Try not to do that please.
* If it's a value, use ```self.site.state.set(key, value)``` to set it and ```self.state.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 ```cache``` and ```state``` objects are rather simplistic, and that's intentional. They have no default values: if
the key is not there, you will get ```None``` and like it. They are meant to be both threadsafe, but hey, who can
guarantee that sort of thing?

There are no sections, and no access protection, so let's not use it to store passwords and such. Use responsibly.

0 comments on commit dec4da4

Please sign in to comment.