New upstream version 7.8.1upstream/7.8.1

1 files changed, 668 insertions, 150 deletions

diff --git a/docs/manual.txt b/docs/manual.txt
index be68fd2..8b8544b 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -9,7 +9,7 @@
 The Nikola Handbook
 ===================
 
-:Version: 7.7.3
+:Version: 7.8.1
 
 .. class:: alert alert-info pull-right
 
@@ -131,7 +131,7 @@ Obsolescence
 
     Also, in the longer term, the very foundations of dynamic sites shift. Can you
     still deploy a blog software based on Django 0.96? What happens when your
-    host stops supporting the php version you rely on? And so on.
+    host stops supporting the PHP version you rely on? And so on.
 
     You may say those are long term issues, or that they won't matter for years. Well,
     I believe things should work forever, or as close to it as we can make them.
@@ -148,7 +148,7 @@ Cost and Performance
 
     On a static site, the highly optimized HTTP server reads the file from disk
     (or, if it's a popular file, from disk cache), and sends it to the user. You could
-    probably serve a bazillion (technical term) pageviews from a phone using
+    probably serve a bazillion (technical term) page views from a phone using
     static sites.
 
 Lock-in
@@ -233,9 +233,9 @@ and more via plugins — for more details, read the `input format documentation
 <#multiple-input-formats>`__.
 You can learn reStructuredText syntax with the `reST quickstart <https://getnikola.com/quickstart.html>`__.
 
-Please note that Nikola does not guarantee support for encodings other than
-UTF-8. We recommend converting your input files to that encoding.  It will
-prevent bugs, and Nikola will write UTF-8 output anyway.
+Please note that Nikola does not support encodings other than UTF-8. Make sure
+to convert your input files to that encoding to avoid issues.  It will prevent
+bugs, and Nikola will write UTF-8 output anyway.
 
 You can control what markup compiler is used for each file extension with the ``COMPILERS``
 option. The default configuration expects them to be placed in ``posts`` but that can be
@@ -267,94 +267,146 @@ The content of that file is as follows:
 
     Write your post here.
 
-The ``slug`` is the page name. Since often titles will have
-characters that look bad on URLs, it's generated as a "clean" version of the title.
-The third line is the post's date, and is set to "now".
+You can edit these files with your favorite text editor, and once you are happy
+with the contents, generate the pages using ``nikola build``.
 
-The other lines are optional. Tags are comma-separated. The ``link`` is an original
-source for the content, and ``description`` is mostly useful for SEO.
-``type`` is the post type, whatever you set here (prepended with ``post-``)
-will become a CSS class of the ``<article>`` element for this post.  Defaults to
-``text`` (resulting in a ``post-text`` class)
+The post page is generated by default using the ``post.tmpl`` template, which you can use
+to customize the output. You can also customize paths and the template filename
+itself — see `How does Nikola decide where posts should go?`
 
-You can add your own metadata fields in the same manner, if you use a theme that
-supports them (for example: ``.. author: John Doe``)
 
-To add these metadata fields to all new posts by default, you can set the
-variable ``ADDITIONAL_METADATA`` in your configuration.  For example, you can
-add the author metadata to all new posts by default, by adding the following
-to your configuration:
+Metadata fields
+~~~~~~~~~~~~~~~
 
-.. code:: python
+Nikola supports many metadata fields in posts. All of them are
+translatable and almost all are optional. The meta field format is:
 
-    ADDITIONAL_METADATA = {
-        'author': 'John Doe'
-    }
+.. code:: text
 
-.. sidebar:: Other Metadata Fields
+   .. name: value
 
-   Nikola will also use other metadata fields:
+You can add your own metadata fields in the same manner. If you are not using
+reStructuredText, make sure the fields are in a HTML comment in output.
 
-   author
-      Author of the post, will be used in the RSS feed and possibly in the post
-      display (theme-dependent)
+Basic
+`````
 
-   annotations / noannotations
-      Override the value of the ``ANNOTATIONS`` option for this specific post or page.
+title
+    Title of the post. (required)
 
-   category
-      Like tags, except each post can have only one, and they usually have
-      more descriptive names.
+slug
+    Slug of the post. Used as the last component of the page URL.  We recommend
+    and default to using a restricted character set (``a-z0-9-_``) because
+    other symbols may cause issues in URLs. (required)
 
-   filters
-      See the `Post Processing Filters`_ section.
+date
+    Date of the post, defaults to now. Multiple date formats are accepted.
+    Adding a timezone is recommended. (required for posts)
 
-   hidetitle
-      Set "True" if you do not want to see the **page** title as a
-      heading of the output html file (does not work for posts).
+tags
+    Comma-separated tags of the post. Some tags have special meaning, including
+    ``draft``, ``private``, ``mathjax``
 
-   hyphenate
-      Set "True" if you want this document to be hyphenated even if you have
-      hyphenation disabled by default.
+category
+    Like tags, except each post can have only one, and they usually have
+    more descriptive names.
 
-   nocomments
-      Set to "True" to disable comments. Example:
+link
+    Link to original source for content. May be displayed by some themes.
 
-      .. code:: restructuredtext
+description
+    Description of the post. Used in ``<meta>`` tags for SEO.
 
-          .. nocomments: True
+type
+    Type of the post. See `Post Types`_ for details.  Whatever you set here
+    (prepended with ``post-``) will become a CSS class of the ``<article>``
+    element for this post.  Defaults to ``text`` (resulting in a ``post-text``
+    class)
 
-   password
-      The post will be encrypted and invisible until the reader enters the password.
-      Also, the post's sourcecode will not be available.
+Extra
+`````
 
-      WARNING: **DO NOT** use for real confidential data.  The algorithm used (RC4) is insecure.  The implementation may also be easily brute-forced.  Please consider using something else if you need *real* encryption!
+author
+    Author of the post, will be used in the RSS feed and possibly in the post
+    display (theme-dependent)
 
-      More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_
+annotations / noannotations
+    Override the value of the ``ANNOTATIONS`` option for this specific post or page.
 
-   previewimage
-      Designate a preview or other representative image path relative to BASE_URL
-      for use with Open Graph for posts. Adds the image when sharing on social
-      media and many other uses.
+enclosure
+    Add an enclosure to this post when it's used in RSS. See `more information about enclosures <http://en.wikipedia.org/wiki/RSS_enclosure>`__
 
-      .. code:: restructuredtext
+data
+    Path to an external data file (JSON/YAML/TOML dictionary), relative to ``conf.py``.
+    Its keys are available for templates as ``post.data('key')``.
 
-          .. previewimage: images/looks_great_on_facebook.png
+    Translated posts can have different values for this field, and the correct one will be
+    used.
 
-      The image can be of any size and dimension (services will crop and adapt)
-      but should less than 1 MB and be larger than 300x300 (ideally 600x600).
+    See `The Global Context and Data files`_ for more details.  This is
+    especially useful used in combination with `shortcodes`_.
 
-   template
-      Change the template used to render this page/post specific page. That
-      template needs to either be part of the theme, or be placed in a
-      ``templates/`` folder inside your site.
+filters
+    See the `Post Processing Filters`_ section.
 
-      .. code:: restructuredtext
+hidetitle
+    Set "True" if you do not want to see the **page** title as a
+    heading of the output html file (does not work for posts).
+
+hyphenate
+    Set "True" if you want this document to be hyphenated even if you have
+    hyphenation disabled by default.
+
+nocomments
+    Set to "True" to disable comments. Example:
+
+password
+    The post will be encrypted and invisible until the reader enters the password.
+    Also, the post's source code will not be available.
+
+    WARNING: **DO NOT** use for real confidential data.  The algorithm used (RC4) is insecure.  The implementation may also be easily brute-forced.  Please consider using something else if you need *real* encryption!
+
+    More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_
+
+pretty_url
+    Set to "False" to disable pretty URL for this page. Example:
+
+previewimage
+    Designate a preview or other representative image path relative to BASE_URL
+    for use with Open Graph for posts. Adds the image when sharing on social
+    media and many other uses.
+
+    .. code:: restructuredtext
+
+       .. previewimage: /images/looks_great_on_facebook.png
+
+    The image can be of any size and dimension (services will crop and adapt)
+    but should less than 1 MB and be larger than 300x300 (ideally 600x600).
+
+section
+    Section for the post (instead of inferring from output path; requires
+    ``POSTS_SECTION_FROM_META`` setting)
+
+template
+    Change the template used to render this page/post specific page. That
+    template needs to either be part of the theme, or be placed in a
+    ``templates/`` folder inside your site.
+
+    .. code:: restructuredtext
+
+       .. template: story.tmpl
+
+To add these metadata fields to all new posts by default, you can set the
+variable ``ADDITIONAL_METADATA`` in your configuration.  For example, you can
+add the author metadata to all new posts by default, by adding the following
+to your configuration:
 
-          .. template: story.tmpl
+.. code:: python
+
+    ADDITIONAL_METADATA = {
+        'author': 'John Doe'
+    }
 
-   enclosure
-       Add an enclosure to this post when it's used in RSS. See `more information about enclosures <http://en.wikipedia.org/wiki/RSS_enclosure>`__
 
 .. note:: The Two-File Format
 
@@ -382,6 +434,9 @@ to your configuration:
    Both file formats are supported; however, the new format is preferred, if
    possible.
 
+Multilingual posts
+~~~~~~~~~~~~~~~~~~
+
 If you are writing a multilingual site, you can also create a per-language
 post file (for example: ``how-to-make-money.es.txt`` with the default TRANSLATIONS_PATTERN, see below).
 This one can replace metadata of the default language, for example:
@@ -406,28 +461,28 @@ default set to:
     Nikola will only look for translation of input files for languages
     specified in the TRANSLATIONS variable.
 
-You can edit these files with your favourite text editor, and once you are happy
-with the contents, generate the pages using ``nikola build``.
-
-Nikola supports multiple languages for a post (we have almost 40 translations!). If you wish to
+Nikola supports multiple languages for a post (we have almost 50 translations!). If you wish to
 add support for more languages, check out `the Transifex page for Nikola <https://www.transifex.com/projects/p/nikola/>`_
 
-The post page is generated using the ``post.tmpl`` template, which you can use
-to customize the output.
+How does Nikola decide where posts should go?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The place where the post will be placed by ``new_post`` is based on the ``POSTS``
-and ``PAGES`` configuration options:
+The place where the post will be placed by ``new_post`` (the first one that
+matches the given format) and the final post destination (the first one that
+matches a given file) is based on the ``POSTS`` and ``PAGES`` configuration
+options. The exact mechanism is explained above the config options in the
+``conf.py`` file, and also reproduced below:
 
 .. code:: python
 
     # POSTS and PAGES contains (wildcard, destination, template) tuples.
     #
-    # The wildcard is used to generate a list of reSt source files
-    # (whatever/thing.txt).
+    # The wildcard is used to generate a list of post source files
+    # (whatever/thing.rst, for example).
     #
     # That fragment could have an associated metadata file (whatever/thing.meta),
     # and optionally translated files (example for Spanish, with code "es"):
-    #     whatever/thing.es.txt and whatever/thing.es.meta
+    #     whatever/thing.es.rst and whatever/thing.es.meta
     #
     #     This assumes you use the default TRANSLATIONS_PATTERN.
     #
@@ -436,32 +491,39 @@ and ``PAGES`` configuration options:
     #
     # These files are combined with the template to produce rendered
     # pages, which will be placed at
-    # output / TRANSLATIONS[lang] / destination / pagename.html
+    # output/TRANSLATIONS[lang]/destination/pagename.html
     #
     # where "pagename" is the "slug" specified in the metadata file.
+    # The page might also be placed in /destination/pagename/index.html
+    # if PRETTY_URLS are enabled.
     #
     # The difference between POSTS and PAGES is that POSTS are added
-    # to feeds and are considered part of a blog, while PAGES are
-    # just independent HTML pages.
+    # to feeds, indexes, tag lists and archives and are considered part
+    # of a blog, while PAGES are just independent HTML pages.
     #
 
     POSTS = (
-        ("posts/*.txt", "posts", "post.tmpl"),
         ("posts/*.rst", "posts", "post.tmpl"),
+        ("posts/*.txt", "posts", "post.tmpl"),
+        ("posts/*.html", "posts", "post.tmpl"),
     )
     PAGES = (
-        ("stories/*.txt", "stories", "story.tmpl"),
-        ("stories/*.rst", "stories", "story.tmpl"),
+        ("pages/*.rst", "pages", "story.tmpl"),
+        ("pages/*.txt", "pages", "story.tmpl"),
+        ("pages/*.html", "pages", "story.tmpl"),
     )
 
 .. note:: POSTS and PAGES are not flat!
 
    Even if the syntax may suggest you can't, you can create any directory structure you want
-   inside ``posts/`` or ``stories/`` and it will be reflected in the output. For example,
+   inside ``posts/`` or ``pages/`` and it will be reflected in the output. For example,
    ``posts/foo/bar.txt`` would produce  ``output/posts/foo/bar.html``, assuming the slug is also ``bar``.
 
    If you have ``PRETTY_URLS`` enabled, that would be ``output/posts/foo/bar/index.html``.
 
+The ``new_post`` command
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 ``new_post`` will use the *first* path in ``POSTS`` (or ``PAGES`` if ``-p`` is
 supplied) that ends with the extension of your desired markup format (as
 defined in ``COMPILERS`` in ``conf.py``) as the directory that the new post will be
@@ -488,7 +550,7 @@ The ``new_post`` command supports some options:
       -s                        Schedule the post based on recurrence rule
       -i ARG, --import=ARG      Import an existing file instead of creating a placeholder
 
-The optional ``path`` parameter tells nikola exactly where to put it instead of guessing from your config.
+The optional ``path`` parameter tells Nikola exactly where to put it instead of guessing from your config.
 So, if you do ``nikola new_post posts/random/foo.txt`` you will have a post in that path, with
 "foo" as its slug.
 
@@ -514,7 +576,7 @@ In Markdown (or basically, the resulting HTML of any format):
 
 By default all your RSS feeds will be shortened (they'll contain only teasers)
 whereas your index page will still show complete posts. You can change
-this behaviour with your ``conf.py``: ``INDEX_TEASERS`` defines whether index
+this behavior with your ``conf.py``: ``INDEX_TEASERS`` defines whether index
 page should display the whole contents or only teasers. ``FEED_TEASERS``
 works the same way for your Atom and RSS feeds.
 
@@ -546,7 +608,6 @@ Or you can completely customize the link using the ``READ_MORE_LINK`` option.
     # }}            A literal } (U+007D RIGHT CURLY BRACKET)
     # READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>'
 
-
 Drafts
 ~~~~~~
 
@@ -594,6 +655,9 @@ Monday, Wednesday and Friday at 7am, add the following
 
 For more details on how to specify a recurrence rule, look at the
 `iCal specification <http://www.kanzaki.com/docs/ical/rrule.html>`_.
+Or if you are scared of this format, many calendaring applications (eg. Google
+Calendar) offer iCal exports, so you can copy-paste the repeat rule from a
+generated iCal (``.ics``) file (which is a human-readable text file).
 
 Say, you get a free Sunday, and want to write a flurry of new posts,
 or at least posts for the rest of the week, you would run the
@@ -680,6 +744,77 @@ posts.  This is how many blog engines and CMSes behave.  Note that this will
 lead to rebuilding all index pages, which might be a problem for larger blogs
 (with a lot of index pages).
 
+
+Post taxonomy
+~~~~~~~~~~~~~
+
+There are three taxonomy systems in Nikola, or three ways to organize posts. Those are:
+
+* tags
+* categories
+* sections
+
+Tags and categories are visible on the *Tags and Categories* page, by default available at ``/categories/``. Each tag/category/section has an index page and feeds.
+
+Tags
+````
+
+Tags are the smallest and most basic of the taxonomy items. A post can have multiple tags, specified using the ``tags`` metadata entry (comma-separated). You should provide many tags to help your readers, and perhaps search engines, find content on your site.
+
+Please note that tags are case-sensitive and that you cannot have two tags that differ only in case/punctuation (eg. using ``nikola`` in one post and ``Nikola`` in another will lead to a crash):
+
+.. code:: text
+
+   ERROR: Nikola: You have tags that are too similar: Nikola and nikola
+   ERROR: Nikola: Tag Nikola is used in: posts/second-post.rst
+   ERROR: Nikola: Tag nikola is used in: posts/1.rst
+
+Nikola uses some tags to mark a post as “special” — those are ``draft``, ``private``, ``mathjax`` (for math support).
+
+You can also generate a tag cloud with the `tx3_tag_cloud <https://plugins.getnikola.com/#tx3_tag_cloud>`_ plugin.
+
+Categories
+``````````
+
+The next unit for organizing your content are categories. A post can have only one category, specified with the ``category`` meta tag. Those are *deprecated* and replaced by sections. They are displayed alongside tags. You can have categories and tags with the same name (categories’ RSS and HTML files are prefixed with ``cat_`` by default).
+
+Sections
+````````
+
+Sections are the newest feature for taxonomy, and are not supported in themes by default. There are two ways to assign a section to a post:
+
+* through the directory structure (first directory is the section name, eg. ``/code/my-project/`` is in the `code` category) — your POSTS should have those directories as the second element, eg.
+
+  .. code:: python
+
+     POSTS = (
+         ('posts/code/*.rst', 'code', 'posts'),
+     )
+
+* through the ``section`` meta field (requires ``POSTS_SECTION_FROM_META`` setting; recommended especially for existing sites which should not change the directory hierarchy)
+
+Sections are meant to be used to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, you should ideally have less than 10 sections (though it depends on what your blog needs; there is no hard limit).
+
+With sections, you can also use some custom styling — if you install ``husl``, you can use ``post.section_color()`` from within templates to get a distinct color for the section of a post, which you can then use in some inline CSS for the section name.
+
+You can find some examples and more information in the `original announcement
+<https://getnikola.com/blog/new-feature-in-nikola-sections.html>`_
+
+Configuring tags, categories and sections
+`````````````````````````````````````````
+
+There are multiple configuration variables dedicated to each of the three taxonomies. You can set:
+
+* ``TAG_PATH``, ``TAGS_INDEX_PATH``, ``CATEGORY_PATH``, ``CATEGORY_PREFIX`` to configure paths used for tags and categories
+* ``POST_SECTION_NAME``, ``POST_SECTION_TITLE`, `TAG_PAGES_TITLES``, ``CATEGORY_PAGES_TITLES`` to set friendly section names and titles for index pages
+* ``POST_SECTION_DESCRIPTIONS``, `TAG_PAGES_DESCRIPTIONS``, ``CATEGORY_PAGES_DESCRIPTIONS`` to set descriptions for each of the items
+* ``POST_SECTION_COLORS`` to customize colors for each section
+* ``CATEGORY_ALLOW_HIERARCHIES`` and ``CATEGORY_OUTPUT_FLAT_HIERARCHIES`` to allow hierarchical categories
+* ``TAG_PAGES_ARE_INDEXES`` and ``CATEGORY_PAGES_ARE_INDEXES`` to display full-size indexes instead of simple post lists
+* ``WRITE_TAG_CLOUDS`` to enable/disable generating tag cloud files
+* ``HIDDEN_TAGS``. ``HIDDEN_CATEGORIES`` to make some tags/categories invisible in lists
+* ``POSTS_SECTION_FROM_META`` to use ``.. section:`` in posts instead of inferring paths from paths
+
 Creating a Page
 ---------------
 
@@ -690,12 +825,16 @@ Pages are the same as posts, except that:
 * They use the ``story.tmpl`` template instead of ``post.tmpl`` by default
 
 The default configuration expects the page's metadata and text files to be on the
-``stories`` folder, but that can be changed (see ``PAGES`` option above).
+``pages`` folder, but that can be changed (see ``PAGES`` option above).
 
 You can create the page's files manually or use the ``new_post`` command
 with the ``-p`` option, which will place the files in the folder that
 has ``use_in_feed`` set to False.
 
+In some places (including default directories and templates), pages are called
+*stories* for historic reasons. Both are synonyms for the same thing: pages
+that are not blog posts.
+
 Supported input formats
 -----------------------
 
@@ -800,6 +939,168 @@ Using Pandoc for reStructuredText, Markdown and other input formats that have a
 standalone Nikola plugin is **not recommended** as it disables plugins and
 extensions that are usually provided by Nikola.
 
+Shortcodes
+----------
+
+This feature is "inspired" (copied wholesale) from `Hugo <https://gohugo.io/extras/shortcodes/>`__ so I will
+steal part of their docs too.
+
+A shortcode is a simple snippet inside a content file that Nikola will render using a predefined template or
+custom code from a plugin.
+
+To use them from plugins, please see `Extending Nikola <https://getnikola.com/extending.html#shortcodes>`__
+
+Using a shortcode
+~~~~~~~~~~~~~~~~~
+
+In your content files, a shortcode can be called by using this form::
+
+    {{% raw %}}{{% name parameters %}}{{% /raw %}}
+
+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 ;-)::
+
+    {{% 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:`{{% raw %}}{{% shortcode here %}}{{% /raw %}}`
+
+    That role passes text unaltered, so shortcodes behave correctly.
+
+
+Built-in shortcodes
+~~~~~~~~~~~~~~~~~~~
+
+doc
+    Will link to a document in the page, see `Doc directive for details
+    <#doc>`__. Example:
+
+    .. code:: restructuredtext
+
+       {{% raw %}}Take a look at {{% doc %}}my other post <creating-a-theme>{{% /doc %}} about theme creating.{{% /raw %}}
+
+post-list
+    Will show a list of posts, see the `Post List directive for details <#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 %}}
+
+
+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 %)' %}}
+        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 %}}
+
+gist
+    Show GitHub gists. If you know the gist's ID, this will show it in your site:
+
+    {{% raw %}}{{% gist 2395294 %}} {{% /raw %}}
+
+
+raw
+    Passes the content along, mostly used so I can write this damn section and you can see the shortcodes instead
+    of them being munged into shortcode **output**. I can't show an example because Inception.
+
+
+Community shortcodes
+~~~~~~~~~~~~~~~~~~~~
+
+Shortcodes created by the community are available in `the shortcodes repository on GitHub <https://github.com/getnikola/shortcodes>`_.
+
+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. Non-keyword
+options will be passed in a tuple variable named ``_args``.
+
+The post in which the shortcode is being used is available as the ``post``
+variable, so you can access the title as ``post.title``, and data loaded
+via the ``data`` field in the metadata using ``post.data(key)``.
+
+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 :-)
+
+See :doc:`extending` for detailed information.
+
+For example, if your ``shortcodes/foo.tmpl`` contains this::
+
+    This uses the bar variable: ${bar}
+
+And your post contains this::
+
+    {{% raw %}}{{% foo bar=bla %}}{{% /raw %}}
+
+Then the output file will contain::
+
+    This uses the bar variable: bla
+
+Finally, you can use a template shortcode without a file, by inserting the template in the shortcode itself::
+
+    {{% raw %}}
+    {{% template %}}
+    % for foo in bar:
+        <li> ${foo}
+    % endfor
+    {{% /template %}}
+    {{% /raw %}}
+
+In that case, the template engine used will be your theme's and the arguments you pass,
+as well as the global context from your ``conf.py``, are available to the template you
+are creating.
+
+The Global Context and Data files
+---------------------------------
+
+There is a ``GLOBAL_CONTEXT`` field in your ``conf.py`` where you can
+put things you want to make available to your templates.
+
+It will also contain things you put in a ``data/`` directory within your
+site. You can use JSON, YAML or TOML files (with the appropriate file
+extensions: json/js, yaml/yml, toml/tml) that decode to Python dictionaries.
+For example, if you create ``data/foo.json`` containing this:
+
+.. code:: json
+
+   {"bar": "baz"}
+
+Then your templates can use things like ``${data['foo']['bar']}`` and
+it will be replaced by "baz".
+
+Individual posts can also have a data file. Those are specified using the
+``data`` meta field (path relative to ``conf.py``, can be different in
+different languages). Those are accessible as eg.
+``${post.meta('data')['bar']`` in templates. `Template-based shortcodes`_ are a
+good idea in this case.
+
+Data files can be useful for eg. auto-generated sites, where users provide
+JSON/YAML/TOML files and Nikola generates a large page with data from all data
+files. (This is especially useful with some automatic rebuild feature, like
+those documented in `Deployment`_)
+
 Redirections
 ------------
 
@@ -842,7 +1143,7 @@ You surely want to edit these options:
     BLOG_EMAIL = "joe@demo.site"
     BLOG_DESCRIPTION = "This is a demo site for Nikola."  # (translatable)
 
-Some options are demarked with a (translatable) comment above or right next to
+Some options are marked with a (translatable) comment above or right next to
 them.  For those options, two types of values can be provided:
 
 * a string, which will be used for all languages
@@ -878,11 +1179,10 @@ CSS tweaking
 .. _LESS: http://lesscss.org/
 .. _Sass: http://sass-lang.com/
 
-Template tweaking
+Template tweaking and creating themes
     If you really want to change the pages radically, you will want to do a
     `custom theme <theming.html>`__.
 
-
 Navigation Links
     The ``NAVIGATION_LINKS`` option lets you define what links go in a sidebar or menu
     (depending on your theme) so you can link to important pages, or to other sites.
@@ -1019,17 +1319,28 @@ change the FILES_FOLDERS option:
     # FILES_FOLDERS = {'files': '' }
     # Which means copy 'files' into 'output'
 
-Getting More Themes
--------------------
+Custom Themes
+-------------
+
+If you prefer to have a custom appearance for your site, and modifying CSS
+files and settings (see `Customizing Your Site`_ for details) is not enough,
+you can create your own theme. See the :doc:`theming` and
+:doc:`creating-a-theme` for more details. You can put them in a ``themes/``
+folder and set ``THEME`` to the directory name.  You can also put them in
+directories listed in the ``EXTRA_THEMES_DIRS`` configuration variable.
+
+Getting Extra Themes
+--------------------
 
 There are a few themes for Nikola. They are available at
 the `Themes Index <https://themes.getnikola.com/>`_.
-Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command:
+Nikola has a built-in theme download/install mechanism to install those themes
+— the ``theme`` command:
 
 
 .. code:: console
 
-    $ nikola install_theme -l
+    $ nikola theme -l
     Themes:
     -------
     blogtxt
@@ -1037,10 +1348,10 @@ Nikola has a built-in theme download/install mechanism to install those themes �
     ⋮
     ⋮
 
-    $ nikola install_theme blogtxt
-    [2013-10-12T16:46:13Z] NOTICE: install_theme: Downloading:
+    $ nikola theme -i blogtxt
+    [2013-10-12T16:46:13Z] NOTICE: theme: Downloading:
     https://themes.getnikola.com/v6/blogtxt.zip
-    [2013-10-12T16:46:15Z] NOTICE: install_theme: Extracting: blogtxt into themes
+    [2013-10-12T16:46:15Z] NOTICE: theme: Extracting: blogtxt into themes
 
 And there you are, you now have themes/blogtxt installed. It's very
 rudimentary, but it should work in most cases.
@@ -1073,9 +1384,8 @@ Play with it, there's cool stuff there. This feature was suggested by
 Deployment
 ----------
 
-Nikola doesn't really have a concept of deployment. However, if you can specify your
-deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS``
-option, and run them with ``nikola deploy``.
+If you can specify your deployment procedure as a series of commands, you can
+put them in the ``DEPLOY_COMMANDS`` option, and run them with ``nikola deploy``.
 
 You can have multiple deployment presets.  If you run ``nikola deploy``, the
 ``default`` preset is executed.  You can also specify the names of presets
@@ -1102,25 +1412,68 @@ Deploying to GitHub
 ~~~~~~~~~~~~~~~~~~~
 
 Nikola provides a separate command ``github_deploy`` to deploy your site to
-GitHub pages.  The command builds the site, commits the output to a gh-pages
+GitHub Pages.  The command builds the site, commits the output to a gh-pages
 branch and pushes the output to GitHub.  Nikola uses the `ghp-import command
 <https://github.com/davisp/ghp-import>`_ for this.
 
-The branch to use for committing the sources can be changed using the
-``GITHUB_DEPLOY_BRANCH`` option in your config.  For a
-user.github.io/organization.github.io, this MUST be set to ``master``,
-and the branch containing the sources must be changed to something
-else, like ``deploy``, using the ``GITHUB_SOURCE_BRANCH`` option.  The
-remote name to which the changes are pushed is ``origin`` by default,
-and can be changed using the ``GITHUB_REMOTE_NAME`` option.  You also,
-obviously, need to have ``git`` on your PATH, and should be able to
-push to the repository specified as the remote.
+In order to use this feature, you need to configure a few things first.  Make
+sure you have ``nikola`` and ``git`` installed on your PATH.
+
+1. Initialize a Nikola site, if you haven’t already.
+2. Initialize a git repository in your Nikola source directory by running:
+
+   .. code:: text
+
+      git init .
+      git remote add origin git@github.com:user/repository.git
+
+3. Setup branches and remotes in ``conf.py``:
+
+   * ``GITHUB_DEPLOY_BRANCH`` is the branch where Nikola-generated HTML files
+     will be deployed. It should be ``gh-pages`` for project pages and
+     ``master`` for user pages (user.github.io).
+   * ``GITHUB_SOURCE_BRANCH`` is the branch where your Nikola site source will be
+     deployed. We default to ``master``, but user pages should use ``src`` or
+     something else.
+   * ``GITHUB_REMOTE_NAME`` is the remote to which changes are pushed.
+   * ``GITHUB_COMMIT_SOURCE`` controls whether or not the source branch is
+     automatically committed to and pushed. We recommend setting it to
+     ``True``.
+
+4. Create a ``.gitignore`` file. We recommend adding at least the following entries:
+
+   .. code:: text
+
+      cache
+      .doit.db
+      __pycache__
+      output
+
+5. If you set ``GITHUB_COMMIT_SOURCE`` to False, you must switch to your source
+   branch and commit to it.  Otherwise, this is done for you.
+6. Run ``nikola github_deploy``.  This will build the site, commit the output
+   folder to your deploy branch, and push to GitHub.  Your website should be up
+   and running within a few minutes.
+
+If you want to use a custom domain, create your ``CNAME`` file in
+``files/CNAME`` on the source branch. Nikola will copy it to the
+output directory. To add a custom commit message, use the ``-m`` option,
+followed by your message.
+
+Automated rebuilds with Travis CI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want automated rebuilds and GitHub Pages deployment, allowing you to
+blog from anywhere in the world, follow this guide:
+`Automating Nikola rebuilds with Travis CI
+<https://getnikola.com/blog/automating-nikola-rebuilds-with-travis-ci.html>`_.
 
-This command performs the following actions, when it is run:
+Automated rebuilds with GitLab
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Builds the site
-2. Commit the output folder to the ``GITHUB_DEPLOY_BRANCH`` to this branch.
-3. Push the branch to the remote specified in ``GITHUB_REMOTE_NAME``!
+GitLab also offers rebuild automation if you want to use Nikola with GitLab
+Pages. Check out the example `Nikola site on GitLab
+<https://gitlab.com/pages/nikola>`_.
 
 Comments and Annotations
 ------------------------
@@ -1153,7 +1506,7 @@ to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus",
    * In Moot it's your **username**
    * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set. WARNING: this will not work correctly in the test server, needs to be deployed to a real server/URL.
    * For Facebook, you need to `create an app
-     <https://developers.facebook.com/apps>` (turn off sandbox mode!)
+     <https://developers.facebook.com/apps>`_ (turn off sandbox mode!)
      and get an **App ID**
    * For isso, it is the URL of isso (must be world-accessible, encoded with
      Punycode (if using Internationalized Domain Names) and **have a trailing slash**,
@@ -1211,7 +1564,7 @@ if you want feedback on specific parts of your writing.
 You can enable or disable annotations for specific posts or pages using the
 ``annotations`` and ``noannotations`` metadata.
 
-Annotations require JQuery and are therefore not supported in the base theme.
+Annotations require jQuery and are therefore not supported in the base theme.
 You can check bootstrap theme's ``base.html`` for details on how to handle them in
 custom themes.
 
@@ -1224,7 +1577,9 @@ and put images there. Nikola will take care of creating thumbnails, index page,
 If you click on images on a gallery, or on images with links in post, you will
 see a bigger image, thanks to the excellent `colorbox
 <http://www.jacklmoore.com/colorbox>`_.  If don’t want this behavior, add an
-``.islink`` class to your image or link.
+``.islink`` class to your image or link. (The behavior is caused by
+``<a class="image-reference">`` if you need to use it outside of galleries and reST
+thumbnails.)
 
 The gallery pages are generated using the ``gallery.tmpl`` template, and you can
 customize it there (you could switch to another lightbox instead of colorbox, change
@@ -1255,16 +1610,19 @@ The ``conf.py`` options affecting images and gallery pages are these:
     # If set to False, it will sort by filename instead. Defaults to True
     GALLERY_SORT_BY_DATE = True
 
-    # Folders containing images to be used in normal posts or pages. Images will be
-    # scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE options, but
-    # will have to be referenced manually to be visible on the site
-    # (the thumbnail has ``.thumbnail`` added before the file extension).
-    # The format is a dictionary of {source: relative destination}.
-
+    # Folders containing images to be used in normal posts or pages.
+    # IMAGE_FOLDERS is a dictionary of the form {"source": "destination"},
+    # where "source" is the folder containing the images to be published, and
+    # "destination" is the folder under OUTPUT_PATH containing the images copied
+    # to the site. Thumbnail images will be created there as well.
     IMAGE_FOLDERS = {'images': 'images'}
+
+    # Images will be scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE
+    # options, but will have to be referenced manually to be visible on the site
+    # (the thumbnail has ``.thumbnail`` added before the file extension).
     IMAGE_THUMBNAIL_SIZE = 400
 
-If you add a file in ``galleries/gallery_name/index.txt`` its contents will be
+If you add a reST file in ``galleries/gallery_name/index.txt`` its contents will be
 converted to HTML and inserted above the images in the gallery page. The
 format is the same as for posts.
 
@@ -1278,6 +1636,107 @@ be stripped. For example ``03_an_amazing_sunrise.jpg`` will be render as *An ama
 Here is a `demo gallery </galleries/demo>`_ of historic, public domain Nikola
 Tesla pictures taken from `this site <http://kerryr.net/pioneers/gallery/tesla.htm>`_.
 
+Embedding Images
+~~~~~~~~~~~~~~~~
+
+Assuming that you have your pictures stored in a folder called ``images`` (as configured above),
+you can embed the same in your posts with the following reST directive:
+
+.. code:: rest
+
+    ..image:: /images/tesla.jpg
+
+Which is equivalent to the following HTML code:
+
+.. code:: html
+
+   <img src="/images/tesla.jpg">
+
+Please take note of the leading forward-slash ``/`` which refers to the root
+output directory. (Make sure to use this even if you’re not deploying to
+web server root.)
+
+You can also use thumbnails with the ``.. thumbnail::`` reST directive. For
+more details, and equivalent HTML code, see `Thumbnails`_.
+
+Handling EXIF Data
+------------------
+
+Your images contain a certain amount of extra data besides the image itself,
+called the `EXIF metadata. <https://en.wikipedia.org/wiki/Exchangeable_image_file_format>`__
+It contains information about the camera you used to take the picture, when it was taken,
+and maybe even the location where it was taken.
+
+This is both useful, because you can use it in some apps to locate all the pictures taken
+in a certain place, or with a certain camera, but also, since the pictures Nikola
+publishes are visible to anyone on the Internet, a privacy risk worth considering
+(Imagine if you post pictures taken at home with GPS info, you are publishing your
+home address!)
+
+Nikola has some support for managing it, so let's go through a few scenarios to
+see which one you prefer.
+
+Strip all EXIF data
+~~~~~~~~~~~~~~~~~~~
+
+Do this if you want to be absolutely sure that no sensitive information should ever leak::
+
+    PRESERVE_EXIF_DATA = False
+    EXIF_WHITELIST = {}
+
+Preserve all EXIF data
+~~~~~~~~~~~~~~~~~~~~~~
+
+Do this if you really don't mind people knowing where pictures were taken, or camera settings.
+
+    PRESERVE_EXIF_DATA = True
+    EXIF_WHITELIST = {'*': '*'}
+
+Preserve some EXIF data
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Do this if you really know what you are doing. EXIF data comes separated in a few IFD blocks.
+The most common ones are:
+
+0th
+   Information about the image itself
+
+Exif
+   Information about the camera and the image
+
+1st
+   Information about embedded thumbnails (usually nothing)
+
+thumbnail
+   An embedded thumbnail, in JPEG format (usually nothing)
+
+GPS
+   Geolocation information about the image
+
+Interop
+   Not too interesting at this point.
+
+Each IFD in turn contains a number of tags. For example, 0th contains a ImageWidth tag.
+You can tell Nikola exactly which IFDs to keep, and within each IFD, which tags to keep,
+using the EXIF_WHITELIST option.
+
+Let's see an example::
+
+    PRESERVE_EXIF_DATA = True
+    EXIF_WHITELIST = {
+        "0th": ["Orientation", "ImageWidth", "ImageLength"],
+        "Interop": "*",
+    }
+
+So, we preserve EXIF data, and the whitelisted IFDs are "0th" and "Interop". That means
+GPS, for example, will be totally deleted.
+
+Then, for the Interop IFD, we keep everything, and for the 0th IFD we only keep three tags,
+listed there.
+
+There is a huge number of EXIF tags, described in `the standard <http://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf>`__
+
+
 Post Processing Filters
 -----------------------
 
@@ -1307,13 +1766,14 @@ The currently available filters are:
 .. sidebar:: Creating your own filters
 
    You can use any program name that works in place as a filter, like ``sed -i``
-   and you can use arbitrary python functions as filters, too.
+   and you can use arbitrary Python functions as filters, too.
 
-   If your program doesn't run in-place, then you can use Nikola's runinplace function.
+   If your program doesn't run in-place, then you can use Nikola's ``runinplace`` function (from the ``filters`` module).
    For example, this is how the yui_compressor filter is implemented:
 
    .. code-block:: python
 
+      from nikola.filters import runinplace
       def yui_compressor(infile):
           return runinplace(r'yui-compressor --nomunge %1 -o %2', infile)
 
@@ -1396,8 +1856,6 @@ You can apply filters to specific posts or pages by using the ``filters`` metada
 
     .. filters: filters.html_tidy_nowrap, "sed s/foo/bar"
 
-
-
 Optimizing Your Website
 -----------------------
 
@@ -1405,30 +1863,30 @@ One of the main goals of Nikola is to make your site fast and light. So here are
 tips we have found when setting up Nikola with Apache. If you have more, or
 different ones, or about other web servers, please share!
 
-#. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and
+1. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and
    it's probably a good idea to use more than one.
 
-#. Enable compression in Apache:
+2. Enable compression in Apache:
 
    .. code:: apache
 
       AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript
 
-#. If even after you did the previous step the CSS files are not sent compressed:
+3. If even after you did the previous step the CSS files are not sent compressed:
 
    .. code:: apache
 
       AddType text/css .css
 
-#. Optionally you can create static compressed copies and save some CPU on your server
+4. Optionally you can create static compressed copies and save some CPU on your server
    with the GZIP_FILES option in Nikola.
 
-#. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches.
+5. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches.
 
-#. Through the filters feature, you can run your files through arbitrary commands, so that images
+6. Through the filters feature, you can run your files through arbitrary commands, so that images
    are recompressed, JavaScript is minimized, etc.
 
-#. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not
+7. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not
    downloaded from your server.
 
 Math
@@ -1473,12 +1931,16 @@ In reST:
 
     Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
 
-In other input formats:
+In HTML and other input formats:
 
 .. code:: text
 
     Euler’s formula: \(e^{ix} = \cos x + i\sin x\)
 
+Note that some input formats (including Markdown) require using **double
+backslashes** in the delimiters (``\\(inline math\\)``). Please check your
+output first before reporting bugs.
+
 Display mathematics are produced using the reST `math` **directive** or the
 LaTeX backslash-brackets delimiters:
 
@@ -1495,12 +1957,17 @@ In reST:
 
       \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C
 
-In other input formats:
+In HTML and other input formats:
 
 .. code:: text
 
     \[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\]
 
+Note that some input formats (including Markdown) require using **double
+backslashes** in the delimiters (``\\[display math\\]``). Please check your
+output first before reporting bugs.
+
+
 reStructuredText Extensions
 ---------------------------
 
@@ -1541,6 +2008,14 @@ 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. Example:
+
+.. code:: restructuredtext
+
+    .. youtube:: 8N_tupPBtWQ
+       :align: center
+
 Vimeo
 ~~~~~
 
@@ -1563,6 +2038,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
 ~~~~~~~~~~
 
@@ -1584,6 +2062,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
 ~~~~
 
@@ -1657,9 +2138,7 @@ To include an image placed in the ``images`` folder (or other folders defined in
 
 .. code:: restructuredtext
 
-    .. thumbnail:: ../tesla.jpg
-
-(make sure to check the file paths!)
+    .. thumbnail:: /images/tesla.jpg
 
 The small thumbnail will be placed in the page, and it will be linked to the bigger
 version of the image when clicked, using
@@ -1672,10 +2151,17 @@ directive instead:
 
 .. code:: restructuredtext
 
-    .. thumbnail:: ../tesla.jpg
+    .. thumbnail:: /images/tesla.jpg
 
        Nikola Tesla, the man that invented the 20th century.
 
+If you want to include a thumbnail in a non-reST post, you need to produce at
+least this basic HTML:
+
+.. code:: html
+
+   <a class="image-reference" href="images/tesla.jpg"><img src="images/tesla.thumbnail.jpg"></a>
+
 Slideshows
 ~~~~~~~~~~
 
@@ -1774,6 +2260,13 @@ with the tag ``nikola``:
    .. post-list::
       :tags: nikola
 
+Using shortcode syntax (for other compilers):
+
+.. code:: text
+
+   {{% raw %}}{{% post-list stop=5 %}}{{% /post-list %}}{{% /raw %}}
+
+
 The following options are recognized:
 
 * ``start`` : integer
@@ -1796,6 +2289,15 @@ The following options are recognized:
       Sort post list by one of each post's attributes, usually ``title`` or a
       custom ``priority``.  Defaults to None (chronological sorting).
 
+* ``date``: string
+      Show posts that match date range specified by this option. Format:
+
+      * comma-separated clauses (AND)
+      * clause: attribute comparison_operator value (spaces optional)
+          * attribute: year, month, day, hour, month, second, weekday, isoweekday; or empty for full datetime
+          * comparison_operator: == != <= >= < >
+          * value: integer or dateutil-compatible date input
+
 * ``tags`` : string [, string...]
       Filter posts to show only posts having at least one of the ``tags``.
       Defaults to None.
@@ -1804,13 +2306,21 @@ The following options are recognized:
       Filter posts to show only posts having one of the ``categories``.
       Defaults to None.
 
+* ``sections`` : string [, string...]
+      Filter posts to show only posts having one of the ``sections``.
+      Defaults to None.
+
 * ``slugs`` : string [, string...]
       Filter posts to show only posts having at least one of the ``slugs``.
       Defaults to None.
 
+* ``post_type`` (or ``type``) : string
+      Show only ``posts``, ``pages`` or ``all``.
+      Replaces ``all``. Defaults to ``posts``.
+
 * ``all`` : flag
-      Shows all posts and pages in the post list.
-      Defaults to show only posts with set *use_in_feeds*.
+      (deprecated, use ``post_type`` instead)
+      Shows all posts and pages in the post list.  Defaults to show only posts.
 
 * ``lang`` : string
       The language of post *titles* and *links*.
@@ -1832,9 +2342,12 @@ the template file in Nikola's base theme for an example of how this works.
 The list may fail to update in some cases, please run ``nikola build -a`` with
 the appropriate path if this happens.
 
-We recommend using stories with dates in the past (1970-01-01) to avoid
+We recommend using pages with dates in the past (1970-01-01) to avoid
 dependency issues.
 
+If you are using this as a shortcode, flags (``reverse``, ``all``) are meant to be used
+with a ``True`` argument, eg. ``all=True``.
+
 Importing your WordPress site into Nikola
 -----------------------------------------
 
@@ -2066,7 +2579,12 @@ Nikola is released under the `MIT license <https://getnikola.com/license.html>`_
 components shipped along with Nikola, or required by it are released under
 other licenses.
 
-If you are not familiar with free software licensing: In general, you should be able to
-do pretty much anything you want, unless you modify Nikola. If you modify it, and share
-it with someone else, that someone else should get all your modifications under the same
-license you got it.
+If you are not familiar with free software licensing, here is a brief
+explanation (this is NOT legal advice): In general, you can do pretty much
+anything you want — including modifying Nikola, using and redistributing the
+original version or the your modified version. However, if you redistribute
+Nikola to someone else, either a modified version or the original version, the
+full copyright notice and license text must be included in your distribution.
+Nikola is provided “as is”, and the Nikola contributors are not liable for any
+damage caused by the software. Read the `full license text
+<https://getnikola.com/license.html>`_ for details.