Imported Upstream version 7.7.3upstream/7.7.3

12 files changed, 415 insertions, 27 deletions

diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt
index 0891753..c12439d 100644
--- a/docs/creating-a-site.txt
+++ b/docs/creating-a-site.txt
@@ -4,6 +4,7 @@
 .. link:
 .. description:
 .. title: Creating a Site (Not a Blog) with Nikola
+.. author: The Nikola Team
 
 Creating a Site (Not a Blog) with Nikola
 ========================================
diff --git a/docs/extending.txt b/docs/extending.txt
index bb94003..9e5dfbc 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -4,11 +4,12 @@
 .. tags:
 .. link:
 .. description:
+.. author: The Nikola Team
 
 Extending Nikola
 ================
 
-:Version: 7.6.4
+:Version: 7.7.3
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -122,7 +123,7 @@ For your own plugin, just change the values in a sensible way. The
                 'long': 'port',
                 'default': 8000,
                 'type': int,
-                'help': 'Port nummber (default: 8000)',
+                'help': 'Port number (default: 8000)',
             },
             {
                 'name': 'address',
@@ -157,7 +158,7 @@ As mentioned above, a plugin can have options, which the user can see by doing
     Usage:   nikola serve [options]
 
     Options:
-    -p ARG, --port=ARG        Port nummber (default: 8000)
+    -p ARG, --port=ARG        Port number (default: 8000)
     -a ARG, ----address=ARG   Address to bind (default: 127.0.0.1)
 
     $ nikola serve -p 9000
diff --git a/docs/internals.txt b/docs/internals.txt
index 448a6f7..4fbac76 100644
--- a/docs/internals.txt
+++ b/docs/internals.txt
@@ -4,6 +4,7 @@
 .. tags:
 .. link:
 .. description:
+.. author: The Nikola Team
 
 Nikola Internals
 ================
diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz
index db17fa8..15ca75d 100644
--- a/docs/man/nikola.1.gz
+++ b/docs/man/nikola.1.gz
diff --git a/docs/man/nikola.rst b/docs/man/nikola.rst
index 633cb33..977e72e 100644
--- a/docs/man/nikola.rst
+++ b/docs/man/nikola.rst
@@ -6,7 +6,7 @@ Nikola
 A Static Site and Blog Generator
 --------------------------------
 
-:Version: Nikola v7.6.4
+:Version: Nikola v7.7.3
 :Manual section: 1
 :Manual group: User Commands
 
diff --git a/docs/manual.txt b/docs/manual.txt
index 09f428a..be68fd2 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -4,11 +4,12 @@
 .. link:
 .. description:
 .. tags: mathjax
+.. author: The Nikola Team
 
 The Nikola Handbook
 ===================
 
-:Version: 7.6.4
+:Version: 7.7.3
 
 .. class:: alert alert-info pull-right
 
@@ -121,7 +122,7 @@ Security
 
     A smaller software stack implies less security risk.
 
-Obsolescense
+Obsolescence
     If you create a site using (for example) WordPress, what happens when WordPress
     releases a new version? You have to update your WordPress. That is not optional,
     because of security and support issues. If I release a new version of Nikola, and
@@ -169,6 +170,7 @@ Nikola provides the following features:
   * Indexes
   * RSS and Atom feeds
   * Tags and categories, with pages and feeds
+  * Author pages and feeds (not generated if ``ENABLE_AUTHOR_PAGES`` is set to ``False`` or there is only one author)
   * Archives with custom granularity (yearly or monthly)
   * `Comments`_
   * Client-side tag clouds (needs manual configuration)
@@ -205,6 +207,15 @@ To set Nikola up and create your first site, read the `Getting Started Guide <ht
 Creating a Blog Post
 --------------------
 
+.. sidebar:: Magic Links
+
+   You will want to do things like "link from one post to another" or "link to an image gallery",
+   etc. Sure, you can just figure out the URLs for each thing and use that. Or you can use
+   Nikola's special link URLs. Those are done using the syntax ``link://kind/name`` and
+   a full list of the included ones is `here <link://slug/path-handlers>`__ (BTW, I linked
+   to that using ``link://slug/path-handlers``)
+
+
 To create a new post, the easiest way is to run ``nikola new_post``. You  will
 be asked for a title for your post, and it will tell you where the post's file
 is located.
@@ -302,6 +313,10 @@ to your configuration:
       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:
 
@@ -439,6 +454,14 @@ and ``PAGES`` configuration options:
         ("stories/*.rst", "stories", "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,
+   ``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``.
+
 ``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
@@ -492,8 +515,8 @@ 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
-page should display the whole contents or only teasers. ``RSS_TEASERS``
-works the same way for your RSS feeds.
+page should display the whole contents or only teasers. ``FEED_TEASERS``
+works the same way for your Atom and RSS feeds.
 
 By default, teasers will include a "read more" link at the end. If you want to
 change that text, you can use a custom teaser:
@@ -506,7 +529,7 @@ You can override the default value for ``TEASER_END`` in ``conf.py`` — for
 example, the following example will work for ``.. more``, and will be
 compatible with both WordPress and Nikola posts:
 
-..code:: python
+.. code:: python
 
     import re
     TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END)(:(.+))?\s*-->', re.IGNORECASE)
@@ -635,6 +658,9 @@ Categories and tags use simple lists by default that show only titles and
 dates; however, you can switch them to full indexes by using
 ``CATEGORY_PAGES_ARE_INDEXES`` and ``TAG_PAGES_ARE_INDEXES``, respectively.
 
+Something similar happens with authors. To use full indexes in authors, set
+``AUTHOR_PAGES_ARE_INDEXES`` to ``True``.
+
 Static indexes
 ``````````````
 
@@ -732,6 +758,9 @@ config option:
 
     MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra']
 
+Nikola comes with some Markdown Extensions built-in and enabled by default,
+namely a gist directive, a podcast directive, and ``~~strikethrough~~`` support.
+
 IPython Notebook/Jupyter
 ````````````````````````
 
@@ -889,7 +918,7 @@ Navigation Links
 
        3. If you link to directories, make sure to follow ``STRIP_INDEXES``.  If
           it’s set to ``True``, end your links with a ``/``, otherwise end them
-          with ``/index.html`` — or else they won’t be hilighted when active.
+          with ``/index.html`` — or else they won’t be highlighted when active.
 
     The ``SEARCH_FORM`` option contains the HTML code for a search form based on
     duckduckgo.com which should always work, but feel free to change it to
@@ -1026,13 +1055,13 @@ to create a custom theme by downloading free CSS files from http://bootswatch.co
 
 .. code:: console
 
-    $ nikola bootswatch_theme -n custom_theme -s spruce -p bootstrap3
+    $ nikola bootswatch_theme -n custom_theme -s flatly -p bootstrap3
     [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme
-    from 'spruce' and 'bootstrap3'
+    from 'flatly' and 'bootstrap3'
     [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading:
-    http://bootswatch.com//spruce/bootstrap.min.css
+    http://bootswatch.com//flatly/bootstrap.min.css
     [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading:
-    http://bootswatch.com//spruce/bootstrap.css
+    http://bootswatch.com//flatly/bootstrap.css
     [2013-10-12T16:46:59Z] NOTICE: bootswatch_theme: Theme created. Change the THEME setting to "custom_theme" to use it.
 
 You can even try what different swatches do on an existing site using
@@ -1122,8 +1151,7 @@ to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus",
    * In IntenseDebate it's the **IntenseDebate site acct**
    * In LiveFyre it's the **siteId**
    * In Moot it's your **username**
-   * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set, but you must
-     `verify your authorship <https://plus.google.com/authorship>`_
+   * 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!)
      and get an **App ID**
@@ -1334,6 +1362,10 @@ typogrify_sans_widont
 minify_lines
    **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing.
 
+normalize_html
+   Pass HTML through LXML to normalize it. For example, it will resolve ``&quot;`` to actual
+   quotes. Usually not needed.
+
 yui_compressor
    Compress CSS/JavaScript using `YUI compressor <http://yui.github.io/yuicompressor/>`_
 
@@ -1346,6 +1378,17 @@ optipng
 jpegoptim
    Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_
 
+cssminify
+   Minify CSS using http://cssminifier.com/ (requires Internet access)
+
+jsminify
+   Minify JS using http://javascript-minifier.com/ (requires Internet access)
+
+jsonminify
+   Minify JSON files (strip whitespace and use minimal separators).
+
+xmlminify
+   Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds.
 
 You can apply filters to specific posts or pages by using the ``filters`` metadata field:
 
@@ -1392,8 +1435,10 @@ Math
 ----
 
 Nikola supports math input via MathJax.  It is activated via the math roles and
-directives of reStructuredText and the usual LaTeX delimiters (``\(inline\)``
-and ``\[display\]``) for other input formats.
+directives of reStructuredText and the usual LaTeX delimiters
+(backslash-parentheses, backslash-brackets) for other input formats.
+
+To use mathematics in a post, you must add the ``mathjax`` tag.
 
 We **DO NOT** support the old, deprecated and error-prone ``$inline$``
 delimiters by default. If you want to use them, please add them manually,
@@ -1417,7 +1462,8 @@ like this:
     </script>
     """
 
-Inline mathematics are produced using the reST `math` **role** or the ``\(…\)`` delimiters:
+Inline mathematics are produced using the reST `math` **role** or the LaTeX
+backslash-parentheses delimiters:
 
 Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
 
@@ -1433,7 +1479,8 @@ In other input formats:
 
     Euler’s formula: \(e^{ix} = \cos x + i\sin x\)
 
-Display mathematics are produced using the reST `math` **directive** or the ``\[…\]`` delimiters:
+Display mathematics are produced using the reST `math` **directive** or the
+LaTeX backslash-brackets delimiters:
 
 .. math::
 
@@ -1881,7 +1928,7 @@ Using Twitter Cards
 Nikola supports Twitter Card summaries, but they are disabled by default.
 
 Twitter Cards enable you to show additional information in Tweets that link
-to you content.
+to your content.
 Nikola supports `Twitter Cards <https://dev.twitter.com/docs/cards>`_.
 They are implemented to use *Open Graph* tags whenever possible.
 
diff --git a/docs/path_handlers.txt b/docs/path_handlers.txt
new file mode 100644
index 0000000..258f5a9
--- /dev/null
+++ b/docs/path_handlers.txt
@@ -0,0 +1,241 @@
+.. title: Path Handlers for Nikola
+.. slug: path-handlers
+.. author: The Nikola Team
+
+Nikola supports special links with the syntax ``link://kind/name``. Here is
+the description for all the supported kinds.
+
+.. class:: dl-horizontal
+
+archive
+    Link to archive path, name is the year.
+    
+    Example:
+    
+    link://archive/2013 => /archives/2013/index.html
+    
+
+archive_atom
+    Link to atom archive path, name is the year.
+    
+    Example:
+    
+    link://archive_atom/2013 => /archives/2013/index.atom
+    
+
+author
+    Link to an author's page.
+    
+    Example:
+    
+    link://author/joe => /authors/joe.html
+    
+
+author_atom
+    Link to an author's Atom feed.
+    
+    Example:
+    
+    link://author_atom/joe => /authors/joe.atom
+    
+
+author_index
+    Link to the author's index.
+    
+    Example:
+    
+    link://authors/ => /authors/index.html
+    
+
+author_rss
+    Link to an author's RSS feed.
+    
+    Example:
+    
+    link://author_rss/joe => /authors/joe.rss
+    
+
+category
+    A link to a category.
+    
+    Example:
+    
+    link://category/dogs => /categories/dogs.html
+    
+
+category_atom
+    A link to a category's Atom feed.
+    
+    Example:
+    
+    link://category_atom/dogs => /categories/dogs.atom
+    
+
+category_index
+    A link to the category index.
+    
+    Example:
+    
+    link://category_index => /categories/index.html
+    
+
+category_rss
+    A link to a category's RSS feed.
+    
+    Example:
+    
+    link://category_rss/dogs => /categories/dogs.xml
+    
+
+filename
+    Link to post or story by source filename.
+    
+    Example:
+    
+    link://filename/manual.txt => /docs/handbook.html
+    
+
+gallery
+    Link to an image gallery's path.
+    
+    It will try to find a gallery with that name if it's not ambiguous
+    or with that path. For example:
+    
+    link://gallery/london => /galleries/trips/london/index.html
+    
+    link://gallery/trips/london => /galleries/trips/london/index.html
+    
+
+gallery_global
+    Link to the global gallery path, which contains all the images in galleries.
+    
+    There is only one copy of an image on multilingual blogs, in the site root.
+    
+    link://gallery_global/london => /galleries/trips/london/index.html
+    
+    link://gallery_global/trips/london => /galleries/trips/london/index.html
+    
+    (a ``gallery`` link could lead to eg. /en/galleries/trips/london/index.html)
+    
+
+gallery_rss
+    Link to an image gallery's RSS feed.
+    
+    It will try to find a gallery with that name if it's not ambiguous
+    or with that path. For example:
+    
+    link://gallery_rss/london => /galleries/trips/london/rss.xml
+    
+    link://gallery_rss/trips/london => /galleries/trips/london/rss.xml
+    
+
+index
+    Link to a numbered index.
+    
+    Example:
+    
+    link://index/3 => /index-3.html
+    
+
+index_atom
+    Link to a numbered Atom index.
+    
+    Example:
+    
+    link://index_atom/3 => /index-3.atom
+    
+
+listing
+    A link to a listing.
+    
+    It will try to use the file name if it's not ambiguous, or the file path.
+    
+    Example:
+    
+    link://listing/hello.py => /listings/tutorial/hello.py.html
+    
+    link://listing/tutorial/hello.py => /listings/tutorial/hello.py.html
+    
+
+post_path
+    Link to the destination of an element in the POSTS/PAGES settings.
+    
+    Example:
+    
+    link://post_path/posts => /blog
+    
+
+root
+    Link to the current language's root.
+    
+    Example:
+    
+    link://root_path => /
+    
+    link://root_path => /translations/spanish/
+    
+
+rss
+    A link to the RSS feed path.
+    
+    Example:
+    
+    link://rss => /blog/rss.xml
+    
+
+section_index
+    Link to the index for a section.
+    
+    Example:
+    
+    link://section_index/cars => /cars/index.html
+    
+
+section_index_atom
+    Link to the Atom index for a section.
+    
+    Example:
+    
+    link://section_index_atom/cars => /cars/index.atom
+    
+
+slug
+    A link to a post with given slug, if not ambiguous.
+    
+    Example:
+    
+    links://slug/yellow-camaro => /posts/cars/awful/yellow-camaro/index.html
+    
+
+tag
+    A link to a tag's page.
+    
+    Example:
+    
+    link://tag/cats => /tags/cats.html
+    
+
+tag_atom
+    A link to a tag's Atom feed.
+    
+    Example:
+    
+    link://tag_atom/cats => /tags/cats.atom
+    
+
+tag_index
+    A link to the tag index.
+    
+    Example:
+    
+    link://tag_index => /tags/index.html
+    
+
+tag_rss
+    A link to a tag's RSS feed.
+    
+    Example:
+    
+    link://tag_rss/cats => /tags/cats.xml
+    
+
diff --git a/docs/social_buttons.txt b/docs/social_buttons.txt
index 151c906..61d788a 100644
--- a/docs/social_buttons.txt
+++ b/docs/social_buttons.txt
@@ -4,11 +4,12 @@
 .. tags:
 .. link:
 .. description:
+.. author: The Nikola Team
 
 Using Alternative Social Buttons with Nikola
 ============================================
 
-:Version: 7.6.4
+:Version: 7.7.3
 
 .. class:: alert alert-info pull-right
 
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 3cd48af..cc0c8b7 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -54,9 +54,9 @@ copyright = '2012-2015, The Nikola Contributors'
 # built documents.
 #
 # The short X.Y version.
-version = '7.6.4'
+version = '7.7.3'
 # The full version, including alpha/beta/rc tags.
-release = '7.6.4'
+release = '7.7.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/sphinx/path_handlers.txt b/docs/sphinx/path_handlers.txt
new file mode 120000
index 0000000..f097a70
--- /dev/null
+++ b/docs/sphinx/path_handlers.txt
@@ -0,0 +1 @@
+../path_handlers.txt
\ No newline at end of file
diff --git a/docs/support.rst b/docs/support.rst
index bfcc24d..750d61c 100644
--- a/docs/support.rst
+++ b/docs/support.rst
@@ -2,6 +2,7 @@
 .. slug: contact
 .. date: 1970-01-01 15:00:00
 .. description: Get help using Nikola, or contact us.
+.. author: The Nikola Team
 
 :Version: 7.5.1
 
diff --git a/docs/theming.txt b/docs/theming.txt
index 4b6b4a7..f84f966 100644
--- a/docs/theming.txt
+++ b/docs/theming.txt
@@ -4,11 +4,12 @@
 .. tags:
 .. link:
 .. description:
+.. author: The Nikola Team
 
 Theming Nikola
 ==============
 
-:Version: 7.6.4
+:Version: 7.7.3
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -35,7 +36,7 @@ assets
 
     The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_
     and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets,
-    along with CSS files for syntax highligting and reStructuredText, and a
+    along with CSS files for syntax highlighting and reStructuredText, and a
     minified copy of jQuery.
 
     If you want to base your theme on other frameworks (or on no framework at all)
@@ -118,7 +119,7 @@ These are the templates that come with the included themes:
 
     It has some separate pieces defined in ``base_helper.tmpl``,
     ``base_header.tmpl`` and ``base_footer.tmpl`` so they can be
-    easily overriden.
+    easily overridden.
 
 ``index.tmpl``
     Template used to render the multipost indexes. The posts are in a ``posts`` variable.
@@ -193,6 +194,99 @@ require whatever data you want.
 Also, you can specify a custom template to be used by a post or page via the ``template`` metadata,
 and custom templates can be added in the ``templates/`` folder of your site.
 
+Customizing themes to user color preference and section colors
+--------------------------------------------------------------
+
+The user’s preference for theme color is exposed in templates as
+``theme_color`` set in the ``THEME_COLOR`` option.
+
+Each section has an assigned color that is either set by the user or auto
+selected by adjusting the hue of the user’s ``THEME_COLOR``. The color is
+exposed in templates through ``post.section_color(lang)``. The function that
+generates the colors from strings and any given color (by section name and
+theme color for sections) is exposed through the
+``colorize_str_from_base_color(string, hex_color)`` function
+
+Hex color values, like that returned by the theme or section color can be
+altered in the HSL colorspace through the function
+``color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)``.
+Adjustments are given in values between 1.0 and -1.0. For example, the theme
+color can be made lighter using:
+
+.. code:: html+mako
+
+    <span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}">
+
+Identifying and customizing different kinds of pages with a shared template
+---------------------------------------------------------------------------
+
+Nikola provides a `pagekind` in each template contexts that can be used to
+modify shared templates based on the context it’s being used. For example,
+the ``base_helper.tmpl`` is used in all pages, ``indexes.tmpl`` is used in
+many contexts and you may want to add or remove something from only one of
+these contexts.
+
+Example of conditionally loading different resources on all index pages
+(archives, author pages, and tag pages), and others again o the front page
+and in every post pages:
+
+.. code:: html+mako
+
+    <head>
+        …
+        % if 'index' in pagekind:
+            <link href="/assets/css/multicolumn.css" rel="stylesheet">
+        % endif
+        % if 'front_page' in pagekind:
+            <link href="/assets/css/fancy_homepage.css" rel="stylesheet">
+            <script src="/assets/js/post_carousel.js"></script>
+        % endif
+        % if 'post_page' in pagekind:
+            <link href="/assets/css/article.css" rel="stylesheet">
+            <script src="/assets/js/comment_system.js"></script>
+        % endif
+    </head>
+
+Promoting visits to the front page when visiting other filtered
+``index.tmpl`` page variants such as author pages and tag pages. This
+could have been included in ``index.tmpl`` or maybe in ``base.tmpl``
+depending on what you want to achieve.
+
+.. code:: html+mako
+
+    % if 'index' in pagekind:
+        % if 'author_page' in postkind:
+            <p>These posts were written by ${author}. See posts by all
+               authors on the <a href="/">front page</a>.</p>
+        % elif 'tag_page' in postkind:
+            <p>This is a filtered selection of posts tagged “${tag}”, visit
+               the <a href="/">front page</a> to see all posts.</p>
+        % endif
+    % endif
+
+
+List of page kinds provided by default plugins:
+
+* front_page
+* index
+* index, archive_page
+* index, author_page
+* index, main_index
+* index, section_page
+* index, tag_page
+* list
+* list, archive_page
+* list, author_page
+* list, section_page
+* list, tag_page
+* list, tags_page
+* post_page
+* story_page
+* listing
+* generic_page
+* gallery_front
+* gallery_page
+
 Messages and Translations
 -------------------------