Skip to content

Commit 95e411e

Browse files
KwpolskaKwpolska
committedMay 5, 2018
Nikola v8 beta 1
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
1 parent b882579 commit 95e411e

18 files changed

+1036
-396
lines changed
 

‎listings/conf.py

+115-149
Large diffs are not rendered by default.

‎posts/nikola-v7815-and-v800b1-are-out.txt

+231
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
.. title: Nikola v7.8.15 and v8.0.0b1 are out!
2+
.. slug: nikola-v7815-and-v800b1-are-out
3+
.. date: 2018-05-05 19:15:31 UTC
4+
.. tags: nikola, planet, python, programming, release
5+
.. category:
6+
.. link:
7+
.. description:
8+
.. type: text
9+
.. author: Chris Warrick
10+
11+
On behalf of the Nikola team, I am pleased to announce the immediate
12+
availability of Nikola v7.8.15 and v8.0.0b1.
13+
14+
Nikola v7.8.15 is the last v7 maintenance release with a few more bug fixes.
15+
16+
Nikola v8.0.0b1 (Beta 1) is the first test release of the v8 series. The v8 series adds a ton of
17+
new features and fixes bugs, while also breaking backwards compatibility.
18+
19+
What is Nikola?
20+
===============
21+
22+
Nikola is a static site and blog generator, written in Python.
23+
It can use Mako and Jinja2 templates, and input in many popular markup
24+
formats, such as reStructuredText and Markdown — and can even turn
25+
Jupyter (IPython) Notebooks into blog posts! It also supports image
26+
galleries, and is multilingual. Nikola is flexible, and page builds
27+
are extremely fast, courtesy of doit (which is rebuilding only what
28+
has been changed).
29+
30+
Find out more at the website: https://getnikola.com/
31+
32+
Downloads
33+
=========
34+
35+
Install using ``pip install Nikola==7.8.15`` or ``pip install Nikola==8.0.0.beta1``.
36+
37+
Before upgrading to Nikola v8, `make sure to read the “Upgrading” document`__.
38+
39+
__ https://getnikola.com/blog/upgrading-to-nikola-v8.html
40+
41+
Changes in v7.8.15
42+
==================
43+
44+
* Fix behavior for posts not available in default language
45+
(Issues #2956 and #3073)
46+
* Fix behavior of RSS_PATH to do what the documentation
47+
says it does (Issue #3024)
48+
* Use documented dateutil API for time zone list (Issue #3006)
49+
50+
Changes in v8.0.0b1
51+
===================
52+
53+
Important compatibility changes
54+
-------------------------------
55+
56+
* Rename ``crumbs.tmpl`` to ``ui_helper.tmpl`` and the breadcrumbs
57+
``bar`` function to ``breadcrumbs`` (your templates may need
58+
changing as well)
59+
* Rename ``post.is_mathjax`` to ``post.has_math``. Themes using
60+
``post.is_mathjax`` must be updated; it is recommended that they are
61+
changed to use ``math_helper.tmpl``.
62+
* Reading reST docinfo metadata, including first heading as title,
63+
requires ``USE_REST_DOCINFO_METADATA`` now (Issue #2987)
64+
* RSS feeds might have changed their places due to ``RSS_PATH``
65+
behavior changes (you may need to change ``RSS_PATH``,
66+
``RSS_FILENAME_BASE``)
67+
* Atom feeds for archives and Atom pagination are no longer supported
68+
(Issue #3016)
69+
* Sections are replaced by categories (Issue #2833)
70+
71+
Features
72+
--------
73+
74+
* Support hackerthemes.com themes and renamed bootswatch_theme command subtheme (Issue #3049)
75+
* Add ``DISABLE_MAIN_ATOM_FEED`` setting (Issue #3016, Issue #3039)
76+
* Add ``ATOM_FILENAME_BASE`` setting (defaults to ``index`` for
77+
existing sites, but ``feed`` for new sites) (Issue #3016)
78+
* Add ``CATEGORY_DESTPATH_AS_DEFAULT``, ``CATEGORY_DESTPATH_TRIM_PREFIX``,
79+
``CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY`` settings, as part of
80+
replacing sections with categories (Issue #2833)
81+
* Tags ``draft``, ``private`` and ``mathjax`` are no longer treated
82+
special if ``USE_TAG_METADATA`` is set to ``False`` (default for
83+
new sites) (Issue #2761)
84+
* Replace ``draft`` and ``private`` tags with a ``status`` meta field
85+
(supports ``published``, ``featured``, ``draft``, ``private``)
86+
and ``mathjax`` with ``.. has_math: yes`` (Issue #2761)
87+
* Rename ``TAG_PAGES_TITLES`` → ``TAG_TITLES``,
88+
``TAG_PAGES_DESCRIPTIONS`` → ``TAG_DESCRIPTIONS``.
89+
* Rename ``CATEGORY_PAGES_TITLES`` → ``CATEGORY_TITLES``,
90+
``CATEGORY_PAGES_DESCRIPTIONS`` → ``CATEGORY_DESCRIPTIONS``.
91+
* Produce a better error message when a template referenced in another
92+
template is missing (Issue #3055)
93+
* Support captioned images and image ordering in galleries, as well as
94+
arbitrary metadata through a new ``metadata.yml`` file (Issue #3017,
95+
Issue #3050, Issue #2837)
96+
* New ``ATOM_PATH`` setting (Issue #2971)
97+
* Make ``crumbs`` available to all pages
98+
* Allowing to customize RSS and Atom feed extensions with
99+
``RSS_EXTENSION``, ``ATOM_EXTENSION`` settings (Issue #3041)
100+
* Allowing to customize filename base appended to RSS_PATH
101+
with ``RSS_FILENAME_BASE`` setting (Issue #3041)
102+
* Use basic ipynb template by default for slightly better appearance
103+
and behavior
104+
* Fixing behavior of RSS_PATH to do what the documentation
105+
says it does (Issue #3024)
106+
* Add support for fragments in path handlers (Issue #3032)
107+
* New ``METADATA_VALUE_MAPPING`` setting to allow for flexible global
108+
modification of metadata (Issue #3025)
109+
* New ``smartjoin`` template function/filter that joins lists and
110+
leaves strings as-is (Issue #3025)
111+
* Explain index.html conflicts better (Issue #3022)
112+
* Recognize both TEASER_END and (new) END_TEASER (Issue #3010)
113+
(warning: if you perform manual splits, the regex change means new
114+
indexes must be used)
115+
* New MARKDOWN_EXTENSION_CONFIGS setting (Issue #2970)
116+
* Replace ``flowr.js`` with ``justified-layout.js`` by Flickr
117+
(does not require jQuery!)
118+
* ``bootblog4`` is the new default theme (Issue #2964)
119+
* New ``bootstrap4`` and ``bootblog4`` themes (Issue #2964)
120+
* New Thai translation by Narumol Hankrotha and Jean Jordaan
121+
* Support for Commento comment system (Issue #2773)
122+
* New PRESERVE_ICC_PROFILES option to control whether ICC profiles are
123+
preserved when copying images.
124+
* Use baguetteBox in Bootstrap theme (part of Issue #2777)
125+
* New default-config command to generate a clean configuration.
126+
* New ``thumbnail`` shortcode similar to the reStructuredText
127+
``thumbnail`` directive (via Issue #2809)
128+
* Rewrite ``nikola auto`` with asyncio and aiohttp (Issue #2850)
129+
* New ``listings`` shortcode similar to the reStructuredText listings
130+
directive (Issue #2868)
131+
* Switch to reStructuredText’s new HTML 5 renderer (Issue #2874)
132+
* Deprecate ``html4css1.css`` in favor of ``rst_base.css`` (Issue
133+
#2874)
134+
* Add support for ``MetadataExtractor`` plugins that allow custom,
135+
extensible metadata extraction from posts (Issue #2830)
136+
* Support YAML and TOML metadata in 2-file posts (via Issue #2830)
137+
* Renamed ``UNSLUGIFY_TITLES`` → ``FILE_METADATA_UNSLUGIFY_TITLES``
138+
(Issue #2840)
139+
* Add ``NIKOLA_SHOW_TRACEBACKS`` environment variable that shows
140+
full tracebacks instead of one-line summaries
141+
* Use ``PRETTY_URLS`` by default on all sites (Issue #1838)
142+
* Feed link generation is completely refactored (Issue #2844)
143+
* Let path handlers return absolute URLs (Issue #2876)
144+
* Add ``BLOG_EMAIL`` to global context to make it available for
145+
templates (Issue #2968)
146+
147+
Bugfixes
148+
--------
149+
150+
* Fixes behavior for posts not available in default language
151+
(Issues #2956 and #3073)
152+
* Always follow ``FEED_LENGTH`` for Atom feeds
153+
* Apply filters to all Atom feeds
154+
* Read file metadata if compiler metadata exists and prefer it over
155+
compiler metadata (Issue #3008)
156+
* Rename ``DISABLE_INDEXES_PLUGIN_INDEX_AND_ATOM_FEED`` to ``DISABLE_INDEXES``
157+
and ``DISABLE_INDEXES_PLUGIN_RSS_FEED`` to ``DISABLE_MAIN_RSS_FEED`` (Issue #3039)
158+
* Make chart shortcode its own plugin and make the reST directive
159+
depend on it.
160+
* Put post_list shortcode in its own plugin and make the reST
161+
directive depend on it.
162+
* Don’t silence syntax errors and other exceptions that occur while
163+
reading metadata
164+
* Use documented dateutil API for time zone list (Issue #3006)
165+
* Handle trailing slash redirects with query strings correctly in
166+
``nikola serve`` (Issue #3000)
167+
* Fix w3c validation errors for itemscope entries in default themes
168+
* Hide “Incomplete language” message for overrides of complete
169+
languages
170+
* Handle '/' and other absolute paths better in POSTS / PAGES / TRANSLATIONS
171+
(Issue #2982)
172+
* Fix loading non-default languages
173+
* Support KaTeX for reST display math (Issue #2888)
174+
* Use npm for asset management instead of bower, which was deprecated
175+
(Issue #2790)
176+
* Properly handle ``SHOW_INDEX_PAGE_NAVIGATION`` with Jinja templates
177+
(Issue #2960)
178+
* Prevent crashes due to Windows-specific code in ``auto`` running on
179+
all platforms (Issue #2940)
180+
* Don’t run hyphenate on ``<pre>`` blocks (Issue #2939)
181+
* Make errors in reST display in logs again
182+
* Unquote paths given to ``link://`` magic URLs (Issue #2934)
183+
* Specify UTF-8 input encoding for Mako as default (Issue #2930)
184+
* Don't trigger rebuilds in auto mode for files it's safe to ignore
185+
(Issue #2906)
186+
* Fix padding for Jupyter code blocks (Issue #2927)
187+
* Apply ``SCHEDULE_ALL`` to posts only (Issue #2921)
188+
* Restore version number to Bootswatch URLs (Issue #2916)
189+
* Do not strip trailing slash in ``slug`` magic links
190+
* Ignore empty tags in HTML metadata reader (Issue #2890)
191+
* Do not remove doctype if ``add_header_permalinks`` or
192+
``deduplicate_ids`` are used
193+
* Handle empty slug metadata (Issue #2887)
194+
* Fix crash when compiling empty ``.html`` posts (Issue #2851)
195+
* Make failures to get source commit hash non-fatal in
196+
``github_deploy`` (Issue #2847)
197+
* Less cryptic error when guessing format from extension in ``new_post``
198+
fails
199+
* Use Jupyter name more consistently in docs
200+
* Support CODE_COLOR_SCHEME in Jupyter notebooks (Issue #2093)
201+
* Language was not passed to title and link generation for page indexes
202+
* Addressed issue with snaps not allowing certain functions to work properly.
203+
204+
Removed conf.py settings
205+
------------------------
206+
207+
The following settings have been removed. Nikola will now always
208+
behave as if the value was what is displayed afer the setting name.
209+
210+
* ``FEED_PREVIEWIMAGE = True``
211+
* ``SITEMAP_INCLUDE_FILELESS_DIRS = True``
212+
* ``USE_OPEN_GRAPH = True``
213+
* ``USE_BASE_TAG = False``
214+
215+
Removed features
216+
----------------
217+
218+
* Removed Colorbox, baguetteBox is used instead (Issue #2777)
219+
* Removed ``googleplus`` comments (no longer supported) (Issue #635)
220+
* Removed the slides directive for docutils, it will now be a separate plugin.
221+
* Dropped Python 2 and Python 3.3 support (oldest supported version is 3.4)
222+
* Removed ``nikola install_theme`` — use ``nikola theme`` instead
223+
* Droppped insecure post “encryption” feature
224+
* Stopped supporting all deprecated config options
225+
* Dropped annotations support (annotateit.org closed down in March 2017)
226+
* Removed taxonomy option ``also_create_classifications_from_other_languages``
227+
(Issue #2785) and ``generate_atom_feeds_for_post_lists`` (Issue
228+
#3016)
229+
* Removed old 7-line metadata format (Issue #2839)
230+
* Atom feeds are now limited to one page (Issue #3016)
231+
* Removed sections (replaced by improved categories) (Issue #2833)

‎posts/upgrading-to-nikola-v8.txt

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
.. title: Upgrading to Nikola v8
2+
.. slug: upgrading-to-nikola-v8
3+
.. date: 2018-05-05 18:55:43 UTC
4+
.. tags: nikola, documentation
5+
.. category:
6+
.. link:
7+
.. description:
8+
.. type: text
9+
.. author: Chris Warrick
10+
11+
.. class:: lead
12+
13+
Nikola v8 is a huge release with lots of new features and fixed bugs. However,
14+
a few manual changes are required to upgrade.
15+
16+
.. contents::
17+
18+
How to upgrade
19+
==============
20+
21+
1. Upgrade to the latest v7 version: ``pip install Nikola==7.8.15`` and make sure
22+
there are no outstanding warnings.
23+
2. Upgrade to v8: ``pip install -U --upgrade-strategy=eager Nikola==8.0.0b1``
24+
3. Read the upgrade notes below and `the full changelog`__
25+
4. Upgrade all third-party plugins and themes. (``nikola plugin --upgrade``,
26+
``nikola theme --upgrade``)
27+
5. Run ``nikola status`` and fix all warnings.
28+
6. When all warnings are fixed, run ``nikola build``.
29+
7. Run ``nikola check -l`` and ``nikola check -f``. If there are broken links
30+
or orphaned files, take care of them.
31+
32+
__ https://getnikola.com/changes.html
33+
34+
Upgrading post metadata
35+
=======================
36+
37+
There are a few changes in post metadata you should make:
38+
39+
* ``draft`` and ``private`` tags are now ``status`` metadata values (eg. ``..
40+
status: draft``)
41+
* ``mathjax`` tag is now a ``has_math`` metadata key (eg. ``.. has_math: yes``)
42+
43+
Both changes can be applied by using the `upgrade_metadata_v8`__ plugin.
44+
45+
__ https://plugins.getnikola.com/v8/upgrade_metadata_v8/
46+
47+
Changes to themes and templates
48+
===============================
49+
50+
The default theme for Nikola was changed to ``bootblog4``, which has a modern,
51+
clean look. There’s also ``bootstrap4`` with the classic look. The
52+
``bootstrap3`` theme is not included by default, but can still be installed
53+
(``nikola theme -i bootstrap3``)
54+
55+
.. TODO: bootblog4 featured posts
56+
57+
Moreover, there are a few changes to templates that you must reflect in your
58+
templates:
59+
60+
* Rename ``crumbs.tmpl`` to ``ui_helper.tmpl`` and the breadcrumbs
61+
``bar`` function to ``breadcrumbs`` (your templates may need
62+
changing as well)
63+
* Rename ``post.is_mathjax`` to ``post.has_math``. Themes using
64+
``post.is_mathjax`` must be updated; it is recommended that they are
65+
changed to use ``math_helper.tmpl``.
66+
* For galeries and images, colorbox was replaced by baguetteBox.
67+
68+
Backwards incompatible changes
69+
==============================
70+
71+
The following changes may cause issues with blog appearance and links. Please
72+
73+
* Sections are replaced by categories (Issue #2833) — *see below*
74+
* Reading reST docinfo metadata, including first heading as title,
75+
requires ``USE_REST_DOCINFO_METADATA`` now (Issue #2987)
76+
* RSS feeds might have changed their places due to ``RSS_PATH``
77+
behavior changes (you may need to change ``RSS_PATH``,
78+
``RSS_FILENAME_BASE``)
79+
* Atom feeds for archives and Atom pagination are no longer supported
80+
(Issue #3016)
81+
82+
Removed and renamed settings
83+
============================
84+
85+
The following settings have been removed. Nikola will now always
86+
behave as if the value was what is displayed afer the setting name.
87+
88+
* ``FEED_PREVIEWIMAGE = True``
89+
* ``SITEMAP_INCLUDE_FILELESS_DIRS = True``
90+
* ``USE_OPEN_GRAPH = True``
91+
* ``USE_BASE_TAG = False``
92+
93+
The following settings were renamed
94+
95+
Sections were replaced by categories
96+
====================================
97+
98+
`Sections were an unfinished feature.`__ Having both sections and categories at the same time made no sense. The sections feature was removed and replaced by categories. Categories now support using the destination path, with the possibility to ignore common prefixes, and to use subdirectories. Categories can do everything sections used to.
99+
100+
__ https://github.com/getnikola/nikola/issues/2833
101+
102+
The way to migrate depends on what your blog setup was:
103+
104+
* if you were only using categories, you don’t need to do anything (except for
105+
the two renamed settings mentioned above)
106+
* if you were only using sections, read on or details of required changes
107+
* if you were using both,
108+
109+
PS. the ``section_prevnext`` plugin has been renamed ``category_prevnext`` for
110+
v8.
111+
112+
Changes to posts
113+
----------------
114+
115+
If your posts are using the ``section`` metadata field, you should rename it to ``category``. Nikola will do this conversion automatically if no category is specified, while also issuing a warning.
116+
117+
Changes to configuration
118+
------------------------
119+
120+
* ``POSTS_SECTION_TITLE`` has been merged into ``CATEGORY_TITLES`` (whose name has changed from ``CATEGORY_PAGES_TITLES``)
121+
* ``POSTS_SECTION_DESCRIPTIONS`` has been merged into ``CATEGORY_DESCRIPTIONS`` (whose name has changed from ``CATEGORY_PAGES_DESCRPTIONS``)
122+
* In order to activate the path-based behavior, enable ``CATEGORY_DESTPATH_AS_DEFAULT``
123+
* To control what is used to generate paths, you can set ``CATEGORY_DESTPATH_TRIM_PREFIX`` and ``CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY`` (old sections behavior/default values are False and True respectively, but flipping them makes the feature much more flexible)
124+
* ``POSTS_SECTION_NAME`` is now ``CATEGORY_DESTPATH_NAMES``
125+
* ``POSTS_SECTION_COLORS`` is not supported by default, but you can replace it with some manual tinkering
126+
* ``CATEGORY_ALLOW_HIERARCHIES``, ``CATEGORY_OUTPUT_FLAT_HIERARCHY`` are heavily recommended if you use ``CATEGORY_DESTPATH_AS_DEFAULT``, and required if you use ``CATEGORY_PAGES_FOLLOW_DESTPATH``
127+
128+
Recreating the old behavior of sections
129+
---------------------------------------
130+
131+
.. code:: python
132+
133+
CATEGORY_ALLOW_HIERARCHIES = True
134+
CATEGORY_OUTPUT_FLAT_HIERARCHY = True
135+
CATEGORY_DESTPATH_AS_DEFAULT = True
136+
CATEGORY_DESTPATH_TRIM_PREFIX = False
137+
CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY = True
138+
CATEGORY_PAGES_FOLLOW_DESTPATH = True
139+
140+
Colorizing categories (or anything, really)
141+
-------------------------------------------
142+
143+
The colorization feature is now available for *anything*, not only sections.
144+
Templates can use the ``colorize_str(string, base_color, presets)`` function,
145+
like so:
146+
147+
.. code:: mako
148+
149+
${colorize_str(post.meta('category'), theme_color, category_colors)}
150+
151+
You need to add ``category_colors`` to the global context manually — this
152+
expects a regular (untranslated) dict mapping category names to hex colors.
153+
154+
Plugins
155+
=======
156+
157+
If you are using ``section_prevnext``, remove it and install
158+
``category_prevnext`` instead.
159+
160+
If you are using the ``projectpages`` plugin, you can migrate your metadata like this:
161+
162+
.. code:: text
163+
164+
sed 's/.. status:/.. devstatus:/g' *.rst -i
165+
sed '/.. featured: False/d' *.rst -i
166+
sed 's/.. featured: True/.. status: featured/g' *.rst -i
167+
sed '/.. hidden: False/d' *.rst -i
168+
sed 's/.. hidden: True/.. status: private/g' *.rst -i
169+
170+
171+
On YAML configuration
172+
=====================
173+
174+
One of the features we’ve promised for Nikola v8 was YAML config. We’re afraid
175+
we won’t offer this in the v8.0.0 release just yet. Doing this *right* will require
176+
substantial amounts of time, and the v8 project has been going for over a year.
177+
178+
Rest assured: we haven’t scrapped this idea. YAML config will appear in a
179+
future v8.x.0 release. Before that happens, we need to build a configuration
180+
management framework, with support for `migrations <https://github.com/getnikola/nikola/issues/2475#issuecomment-384064771>`_
181+
among other things — its main focus will be Nikola config, but we hope
182+
to make it flexible enough to work anywhere.
183+
(If you’re aware of a good project that does this, do tell us!)

‎state_data.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"last_deploy": "2018-04-24T19:51:22.265768"
2+
"last_deploy": "2018-05-05T19:21:57.264415"
33
}

‎stories/AUTHORS.txt

+6
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* `Aru Sahni <https://github.com/arusahni>`_
99
* `Aurelien Naldi <https://github.com/aurelien-naldi>`_
1010
* `Ben Mather <https://github.com/bwhmather>`_
11+
* `Bendik Knapstad <https://github.com/knapstad>`_
1112
* `Boris Kaul <https://github.com/localvoid>`_
1213
* `Brad Miller <https://github.com/bnmnetp>`_
1314
* `Brandon W. Maister <https://github.com/quodlibetor>`_
@@ -56,6 +57,7 @@
5657
* `Joshua Barratt <https://github.com/jbarratt>`_
5758
* `Juan Pedro Fisanotti <https://github.com/fisadev>`_
5859
* `Juanjo Conti <https://github.com/jjconti>`_
60+
* `James C. McPherson <https://github.com/jmcp>`_
5961
* `Kade For <https://github.com/kadefor>`_
6062
* `Kay Hayen <https://github.com/kayhayen>`_
6163
* `lbiaggi <https://github.com/lbiaggi>`_
@@ -68,13 +70,16 @@
6870
* `Mario Pozzo <https://github.com/camboris>`_
6971
* `Mark Eichin <https://github.com/eichin>`_
7072
* `Martin Bless <https://github.com/marble>`_
73+
* `Martin Michlmayr <https://github.com/tbm>`_
7174
* `Martin Wimpress <https://github.com/wimpr1m>`_
7275
* `Martín Gaitán <https://github.com/mgaitan>`_
7376
* `Matias Novoa <https://github.com/mattgaviota>`_
77+
* `Michael Brakemeier <https://github.com/michaelb42>`_
7478
* `Michael Joseph <https://github.com/michaeljoseph>`_
7579
* `Michael McNeil Forbes <https://github.com/mforbes>`_
7680
* `Michal Petrucha <https://github.com/koniiiik>`_
7781
* `Miguel Ángel García <https://github.com/magmax>`_
82+
* `Mitch Chapman <https://github.com/mchapman87501>`_
7883
* `mrabbitt <https://github.com/mrabbitt>`_
7984
* `Neil MartinsenBurrell <https://github.com/neilmb>`_
8085
* `Niels Böhm <https://github.com/blubberdiblub>`_
@@ -114,6 +119,7 @@
114119
* `Tolu Sonaike <https://github.com/tolusonaike>`_
115120
* `Troy Toman <https://github.com/troytoman>`_
116121
* `Udo Spallek <https://github.com/udono>`_
122+
* `Will DeBerry <https://github.com/willdeberry>`_
117123
* `Yamila Moreno <https://github.com/yamila-moreno>`_
118124
* `yarko <https://github.com/yarko>`_
119125
* `Yasuhiko Shiga <https://github.com/quoth>`_

‎stories/CHANGES.txt

+192
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,195 @@
1+
New in v8.0.0b1
2+
===============
3+
4+
Important compatibility changes
5+
-------------------------------
6+
7+
* Rename ``crumbs.tmpl`` to ``ui_helper.tmpl`` and the breadcrumbs
8+
``bar`` function to ``breadcrumbs`` (your templates may need
9+
changing as well)
10+
* Rename ``post.is_mathjax`` to ``post.has_math``. Themes using
11+
``post.is_mathjax`` must be updated; it is recommended that they are
12+
changed to use ``math_helper.tmpl``.
13+
* Reading reST docinfo metadata, including first heading as title,
14+
requires ``USE_REST_DOCINFO_METADATA`` now (Issue #2987)
15+
* RSS feeds might have changed their places due to ``RSS_PATH``
16+
behavior changes (you may need to change ``RSS_PATH``,
17+
``RSS_FILENAME_BASE``)
18+
* Atom feeds for archives and Atom pagination are no longer supported
19+
(Issue #3016)
20+
* Sections are replaced by categories (Issue #2833)
21+
22+
Features
23+
--------
24+
25+
* Support hackerthemes.com themes and renamed bootswatch_theme command subtheme (Issue #3049)
26+
* Add ``DISABLE_MAIN_ATOM_FEED`` setting (Issue #3016, Issue #3039)
27+
* Add ``ATOM_FILENAME_BASE`` setting (defaults to ``index`` for
28+
existing sites, but ``feed`` for new sites) (Issue #3016)
29+
* Add ``CATEGORY_DESTPATH_AS_DEFAULT``, ``CATEGORY_DESTPATH_TRIM_PREFIX``,
30+
``CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY`` settings, as part of
31+
replacing sections with categories (Issue #2833)
32+
* Tags ``draft``, ``private`` and ``mathjax`` are no longer treated
33+
special if ``USE_TAG_METADATA`` is set to ``False`` (default for
34+
new sites) (Issue #2761)
35+
* Replace ``draft`` and ``private`` tags with a ``status`` meta field
36+
(supports ``published``, ``featured``, ``draft``, ``private``)
37+
and ``mathjax`` with ``.. has_math: yes`` (Issue #2761)
38+
* Rename ``TAG_PAGES_TITLES`` → ``TAG_TITLES``,
39+
``TAG_PAGES_DESCRIPTIONS`` → ``TAG_DESCRIPTIONS``.
40+
* Rename ``CATEGORY_PAGES_TITLES`` → ``CATEGORY_TITLES``,
41+
``CATEGORY_PAGES_DESCRIPTIONS`` → ``CATEGORY_DESCRIPTIONS``.
42+
* Produce a better error message when a template referenced in another
43+
template is missing (Issue #3055)
44+
* Support captioned images and image ordering in galleries, as well as
45+
arbitrary metadata through a new ``metadata.yml`` file (Issue #3017,
46+
Issue #3050, Issue #2837)
47+
* New ``ATOM_PATH`` setting (Issue #2971)
48+
* Make ``crumbs`` available to all pages
49+
* Allowing to customize RSS and Atom feed extensions with
50+
``RSS_EXTENSION``, ``ATOM_EXTENSION`` settings (Issue #3041)
51+
* Allowing to customize filename base appended to RSS_PATH
52+
with ``RSS_FILENAME_BASE`` setting (Issue #3041)
53+
* Use basic ipynb template by default for slightly better appearance
54+
and behavior
55+
* Fixing behavior of RSS_PATH to do what the documentation
56+
says it does (Issue #3024)
57+
* Add support for fragments in path handlers (Issue #3032)
58+
* New ``METADATA_VALUE_MAPPING`` setting to allow for flexible global
59+
modification of metadata (Issue #3025)
60+
* New ``smartjoin`` template function/filter that joins lists and
61+
leaves strings as-is (Issue #3025)
62+
* Explain index.html conflicts better (Issue #3022)
63+
* Recognize both TEASER_END and (new) END_TEASER (Issue #3010)
64+
(warning: if you perform manual splits, the regex change means new
65+
indexes must be used)
66+
* New MARKDOWN_EXTENSION_CONFIGS setting (Issue #2970)
67+
* Replace ``flowr.js`` with ``justified-layout.js`` by Flickr
68+
(does not require jQuery!)
69+
* ``bootblog4`` is the new default theme (Issue #2964)
70+
* New ``bootstrap4`` and ``bootblog4`` themes (Issue #2964)
71+
* New Thai translation by Narumol Hankrotha and Jean Jordaan
72+
* Support for Commento comment system (Issue #2773)
73+
* New PRESERVE_ICC_PROFILES option to control whether ICC profiles are
74+
preserved when copying images.
75+
* Use baguetteBox in Bootstrap theme (part of Issue #2777)
76+
* New default-config command to generate a clean configuration.
77+
* New ``thumbnail`` shortcode similar to the reStructuredText
78+
``thumbnail`` directive (via Issue #2809)
79+
* Rewrite ``nikola auto`` with asyncio and aiohttp (Issue #2850)
80+
* New ``listings`` shortcode similar to the reStructuredText listings
81+
directive (Issue #2868)
82+
* Switch to reStructuredText’s new HTML 5 renderer (Issue #2874)
83+
* Deprecate ``html4css1.css`` in favor of ``rst_base.css`` (Issue
84+
#2874)
85+
* Add support for ``MetadataExtractor`` plugins that allow custom,
86+
extensible metadata extraction from posts (Issue #2830)
87+
* Support YAML and TOML metadata in 2-file posts (via Issue #2830)
88+
* Renamed ``UNSLUGIFY_TITLES`` → ``FILE_METADATA_UNSLUGIFY_TITLES``
89+
(Issue #2840)
90+
* Add ``NIKOLA_SHOW_TRACEBACKS`` environment variable that shows
91+
full tracebacks instead of one-line summaries
92+
* Use ``PRETTY_URLS`` by default on all sites (Issue #1838)
93+
* Feed link generation is completely refactored (Issue #2844)
94+
* Let path handlers return absolute URLs (Issue #2876)
95+
* Add ``BLOG_EMAIL`` to global context to make it available for
96+
templates (Issue #2968)
97+
98+
Bugfixes
99+
--------
100+
101+
* Fixes behavior for posts not available in default language
102+
(Issues #2956 and #3073)
103+
* Always follow ``FEED_LENGTH`` for Atom feeds
104+
* Apply filters to all Atom feeds
105+
* Read file metadata if compiler metadata exists and prefer it over
106+
compiler metadata (Issue #3008)
107+
* Rename ``DISABLE_INDEXES_PLUGIN_INDEX_AND_ATOM_FEED`` to ``DISABLE_INDEXES``
108+
and ``DISABLE_INDEXES_PLUGIN_RSS_FEED`` to ``DISABLE_MAIN_RSS_FEED`` (Issue #3039)
109+
* Make chart shortcode its own plugin and make the reST directive
110+
depend on it.
111+
* Put post_list shortcode in its own plugin and make the reST
112+
directive depend on it.
113+
* Don’t silence syntax errors and other exceptions that occur while
114+
reading metadata
115+
* Use documented dateutil API for time zone list (Issue #3006)
116+
* Handle trailing slash redirects with query strings correctly in
117+
``nikola serve`` (Issue #3000)
118+
* Fix w3c validation errors for itemscope entries in default themes
119+
* Hide “Incomplete language” message for overrides of complete
120+
languages
121+
* Handle '/' and other absolute paths better in POSTS / PAGES / TRANSLATIONS
122+
(Issue #2982)
123+
* Fix loading non-default languages
124+
* Support KaTeX for reST display math (Issue #2888)
125+
* Use npm for asset management instead of bower, which was deprecated
126+
(Issue #2790)
127+
* Properly handle ``SHOW_INDEX_PAGE_NAVIGATION`` with Jinja templates
128+
(Issue #2960)
129+
* Prevent crashes due to Windows-specific code in ``auto`` running on
130+
all platforms (Issue #2940)
131+
* Don’t run hyphenate on ``<pre>`` blocks (Issue #2939)
132+
* Make errors in reST display in logs again
133+
* Unquote paths given to ``link://`` magic URLs (Issue #2934)
134+
* Specify UTF-8 input encoding for Mako as default (Issue #2930)
135+
* Don't trigger rebuilds in auto mode for files it's safe to ignore
136+
(Issue #2906)
137+
* Fix padding for Jupyter code blocks (Issue #2927)
138+
* Apply ``SCHEDULE_ALL`` to posts only (Issue #2921)
139+
* Restore version number to Bootswatch URLs (Issue #2916)
140+
* Do not strip trailing slash in ``slug`` magic links
141+
* Ignore empty tags in HTML metadata reader (Issue #2890)
142+
* Do not remove doctype if ``add_header_permalinks`` or
143+
``deduplicate_ids`` are used
144+
* Handle empty slug metadata (Issue #2887)
145+
* Fix crash when compiling empty ``.html`` posts (Issue #2851)
146+
* Make failures to get source commit hash non-fatal in
147+
``github_deploy`` (Issue #2847)
148+
* Less cryptic error when guessing format from extension in ``new_post``
149+
fails
150+
* Use Jupyter name more consistently in docs
151+
* Support CODE_COLOR_SCHEME in Jupyter notebooks (Issue #2093)
152+
* Language was not passed to title and link generation for page indexes
153+
* Addressed issue with snaps not allowing certain functions to work properly.
154+
155+
Removed conf.py settings
156+
------------------------
157+
158+
The following settings have been removed. Nikola will now always
159+
behave as if the value was what is displayed afer the setting name.
160+
161+
* ``FEED_PREVIEWIMAGE = True``
162+
* ``SITEMAP_INCLUDE_FILELESS_DIRS = True``
163+
* ``USE_OPEN_GRAPH = True``
164+
* ``USE_BASE_TAG = False``
165+
166+
Removed features
167+
----------------
168+
169+
* Removed Colorbox, baguetteBox is used instead (Issue #2777)
170+
* Removed ``googleplus`` comments (no longer supported) (Issue #635)
171+
* Removed the slides directive for docutils, it will now be a separate plugin.
172+
* Dropped Python 2 and Python 3.3 support (oldest supported version is 3.4)
173+
* Removed ``nikola install_theme`` — use ``nikola theme`` instead
174+
* Droppped insecure post “encryption” feature
175+
* Stopped supporting all deprecated config options
176+
* Dropped annotations support (annotateit.org closed down in March 2017)
177+
* Removed taxonomy option ``also_create_classifications_from_other_languages``
178+
(Issue #2785) and ``generate_atom_feeds_for_post_lists`` (Issue
179+
#3016)
180+
* Removed old 7-line metadata format (Issue #2839)
181+
* Atom feeds are now limited to one page (Issue #3016)
182+
* Removed sections (replaced by improved categories) (Issue #2833)
183+
184+
New in v7.8.15
185+
==============
186+
187+
* Fix behavior for posts not available in default language
188+
(Issues #2956 and #3073)
189+
* Fix behavior of RSS_PATH to do what the documentation
190+
says it does (Issue #3024)
191+
* Use documented dateutil API for time zone list (Issue #3006)
192+
1193
New in v7.8.14
2194
==============
3195

‎stories/conf.txt ‎stories/conf.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
.. title: Nikola v7.8.14 configuration file
1+
.. title: Nikola v8.0.0b1 configuration file
22
.. slug: conf
33
.. date: 2014-11-08 18:51:30 UTC
44
.. description: The Nikola configuration file.
55
.. type: text
66
.. author: The Nikola Team
77
8-
The default config file for Nikola v7.8.14 is reproduced below.
8+
The default config file for Nikola v8.0.0b1 is reproduced below.
99

1010
.. raw:: html
1111

‎stories/creating-a-site.txt ‎stories/creating-a-site.rst

+7-4
Original file line numberDiff line numberDiff line change
@@ -52,14 +52,17 @@ configuration file:
5252
POSTS = ()
5353
# remove destination directory to generate pages in the root directory
5454
PAGES = (
55-
("pages/*.rst", "", "story.tmpl"),
56-
("pages/*.txt", "", "story.tmpl"),
57-
("pages/*.html", "", "story.tmpl"),
55+
("pages/*.rst", "", "page.tmpl"),
56+
("pages/*.txt", "", "page.tmpl"),
57+
("pages/*.html", "", "page.tmpl"),
5858
)
5959
6060
# And to avoid a conflict because blogs try to generate /index.html
6161
INDEX_PATH = "blog"
6262
63+
# Or you can disable blog indexes altogether:
64+
# DISABLE_INDEXES = True
65+
6366
6467
And now we are ready to create our first page:
6568

@@ -116,7 +119,7 @@ people might find it a bit too limiting — if that is the case, try using HTML
116119
for your pages (Nikola does this on the index page, for example).
117120

118121
So, let's give the page a nicer title, and some fake content. Since the default
119-
Nikola theme (called ``bootstrap3``) is based on `Bootstrap <http://getbootstrap.com/>`_
122+
Nikola theme (called ``bootblog4``) is based on `Bootstrap <http://getbootstrap.com/>`_
120123
you can use anything you like from it:
121124

122125
.. code:: rest

‎stories/creating-a-theme.txt ‎stories/creating-a-theme.rst

+14-11
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ create themes. Since I **suck** at designing websites, I asked for opinions on t
1818
and got some feedback. Since this is **Not So Hard™**, I will try to make time to port a few
1919
and see what happens.
2020

21-
If you are looking for a reference, check out `Theming reference <theming.html>`_ and `Template variables <https://getnikola.com/template-variables.html>`_.
21+
If you are looking for a reference, check out :doc:`Theming reference <theming>` and `Template variables <https://getnikola.com/template-variables.html>`_.
2222

2323
Today’s theme is `Lanyon <https://github.com/poole/lanyon>`__ which is written by `@mdo <https://twitter.com/mdo>`__
2424
and released under a MIT license, which is liberal enough.
@@ -177,7 +177,7 @@ see something fairly similar:
177177
<meta name="viewport" content="width=device-width">
178178
<title>My Nikola Site | My Nikola Site</title>
179179

180-
<link href="assets/css/rst.css" rel="stylesheet" type="text/css">
180+
<link href="assets/css/rst_base.css" rel="stylesheet" type="text/css">
181181
<link href="assets/css/code.css" rel="stylesheet" type="text/css">
182182
<link href="assets/css/theme.css" rel="stylesheet" type="text/css">
183183

@@ -200,10 +200,11 @@ in a particular way, using a setting called ``CODE_COLOR_SCHEME`` where you can
200200
what color scheme the syntax highlighter uses. You can use your own ``assets/css/code.css`` if you
201201
don’t like the provided ones.
202202

203-
Nikola **requires** ``assets/css/rst.css`` and ``assets/css/code.css`` to function properly.
204-
We will also add themes for IPython Notebook (``assets/css/ipython.min.css``
203+
Nikola **requires** ``assets/css/rst_base.css`` and ``assets/css/code.css`` to function properly.
204+
We will also add themes for Jupyter (``assets/css/ipython.min.css``
205205
and ``assets/css/nikola_ipython.css``) into the template; note that they are
206206
activated only if you configured your ``POSTS``/``PAGES`` with ipynb support.
207+
There’s also ``assets/css/nikola_rst.css``, which adds Bootstrap 3-style reST notes etc.
207208

208209
But how do I tell **our** lanyon theme to use those CSS files instead of whatever it’s using now?
209210
By giving our theme its own base_helper.tmpl.
@@ -227,7 +228,8 @@ The part we want to change is this:
227228
<link href="/assets/css/all-nocdn.css" rel="stylesheet" type="text/css">
228229
%endif
229230
%else:
230-
<link href="/assets/css/rst.css" rel="stylesheet" type="text/css">
231+
<link href="/assets/css/rst_base.css" rel="stylesheet" type="text/css">
232+
<link href="/assets/css/nikola_rst.css" rel="stylesheet" type="text/css">
231233
<link href="/assets/css/code.css" rel="stylesheet" type="text/css">
232234
<link href="/assets/css/theme.css" rel="stylesheet" type="text/css">
233235
%if has_custom_css:
@@ -248,7 +250,8 @@ And we will change it so it uses the lanyon styles instead of theme.css (again,
248250
%if use_bundles:
249251
<link href="/assets/css/all.css" rel="stylesheet" type="text/css">
250252
%else:
251-
<link href="/assets/css/rst.css" rel="stylesheet" type="text/css">
253+
<link href="/assets/css/rst_base.css" rel="stylesheet" type="text/css">
254+
<link href="/assets/css/nikola_rst.css" rel="stylesheet" type="text/css">
252255
<link href="/assets/css/poole.css" rel="stylesheet" type="text/css">
253256
<link href="/assets/css/lanyon.css" rel="stylesheet" type="text/css">
254257
<link href="/assets/css/code.css" rel="stylesheet" type="text/css">
@@ -327,7 +330,6 @@ all the interesting stuff:
327330
<%namespace name="base" file="base_helper.tmpl" import="*"/>
328331
<%namespace name="header" file="base_header.tmpl" import="*"/>
329332
<%namespace name="footer" file="base_footer.tmpl" import="*"/>
330-
<%namespace name="annotations" file="annotation_helper.tmpl"/>
331333
${set_locale(lang)}
332334
${base.html_headstart()}
333335
<%block name="extra_head">
@@ -363,7 +365,6 @@ So, first, lets change that base template to be more lanyon-like:
363365
<%namespace name="base" file="base_helper.tmpl" import="*"/>
364366
<%namespace name="header" file="base_header.tmpl" import="*"/>
365367
<%namespace name="footer" file="base_footer.tmpl" import="*"/>
366-
<%namespace name="annotations" file="annotation_helper.tmpl"/>
367368
${set_locale(lang)}
368369
${base.html_headstart()}
369370
<%block name="extra_head">
@@ -402,7 +403,7 @@ So, first, lets change that base template to be more lanyon-like:
402403
And that’s after I exposed the sidebar by clicking on an invisible widget!
403404

404405
One problem, which causes that yellow color in the sidebar is a CSS conflict.
405-
We are loading ``rst.css`` which specifies
406+
We are loading ``rst_base.css`` which specifies
406407
the background color of ``div.sidebar`` which is more specific than
407408
``lanyon.css``, which specifies for ``.sidebar`` alone.
408409

@@ -506,7 +507,7 @@ and at the bottom a label for the sidebar toggle. Easy to do in ``base.tmpl``
506507
507508
Getting there!
508509
509-
The sidebar looks bad because of yet more CSS conflicts with ``rst.css``. By
510+
The sidebar looks bad because of yet more CSS conflicts with ``rst_base.css``. By
510511
adding some extra styling in ``lanyon.css``, it will look better.
511512
512513
.. code:: css
@@ -816,7 +817,7 @@ which makes sites load faster. To do that, your theme needs a ``bundles`` file w
816817

817818
For the Lanyon theme, it should be like this::
818819

819-
assets/css/all.css=rst.css,code.css,poole.css,lanyon.css,custom.css
820+
assets/css/all.css=rst_base.css,nikola_rst.css,code.css,poole.css,lanyon.css,custom.css
820821

821822
**Note:** Some themes also support the ``USE_CDN`` option meaning that in some cases it will load one bundle with all CSS and in other will load some CSS files
822823
from a CDN and others from a bundle. This is complicated and probably not worth the effort.
@@ -827,3 +828,5 @@ The End
827828
And that’s it, that’s a whole theme. Eventually, once people start using it, they will notice small broken details, which will need handling one at a time.
828829

829830
This theme should be available in http://themes.getnikola.com/v7/lanyon/ and you can see it in action at https://themes.getnikola.com/v7/lanyon/demo/ .
831+
832+
What if you want to extend other parts of the theme? Check out the :doc:`Theming reference <theming>`. You can also contribute your improvements to the `nikola-themes <https://github.com/getnikola/nikola>` repository on GitHub.

‎stories/documentation.txt

+3
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ current GitHub master, check out `Nikola on ReadTheDocs
2525
It contains some useful documentation not mentioned in the manual, and can
2626
be used for people upgrading to compare with their existing config files.
2727

28+
`Upgrading to Nikola v8 </blog/upgrading-to-nikola-v8.html>`_
29+
A blog post detailing all the changes from Nikola v7.
30+
2831
`Changelog <changes.html>`_, `Contributors <authors.html>`_, `The MIT License <license.html>`_
2932
What’s new, who made this, and the rules for distribution.
3033

‎stories/extending.txt ‎stories/extending.rst

+27-4
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Extending Nikola
1010
================
1111

12-
:Version: 7.8.14
12+
:Version: 8.0.0b1
1313
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>
1414

1515
.. class:: alert alert-primary float-md-right
@@ -383,8 +383,31 @@ If the compiler produces something other than HTML files, it should also impleme
383383
returns the preferred extension for the output file.
384384

385385
These plugins can also be used to extract metadata from a file. To do so, the
386-
plugin may implement ``read_metadata`` that will return a dict containing the
387-
metadata contained in the file.
386+
plugin must set ``supports_metadata`` to ``True`` and implement ``read_metadata`` that will return a dict containing the
387+
metadata contained in the file. Optionally, it may list ``metadata_conditions`` (see `MetadataExtractor Plugins`_ below)
388+
389+
MetadataExtractor Plugins
390+
-------------------------
391+
392+
Plugins that extract metadata from posts. If they are based on post content,
393+
they must implement ``_extract_metadata_from_text`` (takes source of a post
394+
returns a dict of metadata). They may also implement
395+
``split_metadata_from_text``, ``extract_text``. If they are based on filenames,
396+
they only need ``extract_filename``. If ``support_write`` is set to True,
397+
``write_metadata`` must be implemented.
398+
399+
Every extractor must be configured properly. The ``name``, ``source`` (from the
400+
``MetaSource`` enum in ``metadata_extractors``) and ``priority``
401+
(``MetaPriority``) fields are mandatory. There might also be a list of
402+
``conditions`` (tuples of ``MetaCondition, arg``), used to check if an
403+
extractor can provide metadata, a compiled regular expression used to split
404+
metadata (``split_metadata_re``, may be ``None``, used by default
405+
``split_metadata_from_text``), a list of ``requirements`` (3-tuples: import
406+
name, pip name, friendly name), ``map_from`` (name of ``METADATA_MAPPING`` to
407+
use, if any) and ``supports_write`` (whether the extractor supports writing
408+
metadata in the desired format).
409+
410+
For more details, see the definition in ``plugin_categories.py`` and default extractors in ``metadata_extractors.py``.
388411

389412
RestExtension Plugins
390413
---------------------
@@ -503,7 +526,7 @@ Here's the relevant code from the tag plugin.
503526
# In set_site
504527
site.register_path_handler('tag_rss', self.tag_rss_path)
505528
506-
# And these always take name and lang as arguments and returl a list of
529+
# And these always take name and lang as arguments and return a list of
507530
# path elements.
508531
def tag_rss_path(self, name, lang):
509532
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],

‎stories/internals.txt ‎stories/internals.rst

File renamed without changes.

‎stories/manual.txt ‎stories/manual.rst

+198-153
Large diffs are not rendered by default.

‎stories/path_handlers.txt ‎stories/path_handlers.rst

+7-30
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,13 @@
22
.. slug: path-handlers
33
.. author: The Nikola Team
44
5-
Nikola supports special links with the syntax ``link://kind/name``. In the templates you can also use ``_link(kind, name)``.
6-
You can also add query strings (``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in templates (support and behavior depends on path handlers themselves)
5+
.. DO NOT EDIT, this file is auto-generated by scripts/document_path_handlers.py
6+
7+
Nikola supports special links with the syntax ``link://kind/name``. In
8+
templates you can also use ``_link(kind, name)``. You can add query strings
9+
(``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in
10+
templates (support and behavior depends on path handlers themselves). Fragments
11+
(``#anchor``) will be appended to the transformed link.
712

813
Here are the descriptions for all the supported kinds.
914

@@ -16,13 +21,6 @@ archive
1621

1722
link://archive/2013 => /archives/2013/index.html
1823

19-
archive_atom
20-
Link to archive Atom path, name is the year (archive pages must be indexes).
21-
22-
Example:
23-
24-
link://archive_atom/2013 => /archives/2013/index.atom
25-
2624
author
2725
Link to an author's page.
2826

@@ -191,27 +189,6 @@ rss
191189

192190
link://rss => /blog/rss.xml
193191

194-
section_index
195-
Link to the index for a section.
196-
197-
Example:
198-
199-
link://section_index/cars => /cars/index.html
200-
201-
section_index_atom
202-
Link to the Atom index for a section.
203-
204-
Example:
205-
206-
link://section_index_atom/cars => /cars/index.atom
207-
208-
section_index_rss
209-
Link to the RSS feed for a section.
210-
211-
Example:
212-
213-
link://section_index_rss/cars => /cars/rss.xml
214-
215192
slug
216193
Return a link to a post with given slug, if not ambiguous.
217194

‎stories/social_buttons.txt ‎stories/social_buttons.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Using Alternative Social Buttons with Nikola
1010
============================================
1111

12-
:Version: 7.8.14
12+
:Version: 8.0.0b1
1313

1414
.. class:: alert alert-primary float-md-right
1515

‎stories/support.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
.. description: Get help using Nikola, or contact us.
55
.. author: The Nikola Team
66
7-
:Version: 7.8.14
7+
:Version: 8.0.0b1
88

99
.. class:: alert alert-primary float-md-right
1010

‎stories/template-variables.rst

+10-13
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
.. date: 2017-04-13 12:00:00
44
.. author: The Nikola Team
55
6-
:Version: 7.8.14
6+
:Version: 8.0.0b1
77
:Author: Chris Warrick <chris@getnikola.com>
88

99
Variables available in templates are listed below.
@@ -39,14 +39,14 @@ Name Type Descript
3939
================================== ================================== ================================================================================
4040
``_link`` function ``Nikola.link`` function
4141
``abs_link`` function ``Nikola.abs_link`` function
42-
``annotations`` bool ``ANNOTATIONS`` setting
42+
``atom_path`` TranslatableSetting<str> ``ATOM_PATH`` setting
4343
``author_pages_generated`` bool False
4444
``blog_author`` TranslatableSetting<str> ``BLOG_AUTHOR`` setting
45+
``blog_email`` str ``BLOG_EMAIL`` setting
4546
``blog_description`` TranslatableSetting<str> ``BLOG_DESCRIPTION`` setting
4647
``blog_title`` TranslatableSetting<str> ``BLOG_TITLE`` setting
4748
``blog_url`` str ``SITE_URL`` setting
4849
``body_end`` TranslatableSetting<str> ``BODY_END`` setting
49-
``colorbox_locales`` defaultdict<str, str> dictionary of available Colorbox locales
5050
``colorize_str_from_base_color`` function ``utils.colorize_str_from_base_color`` function
5151
``color_hsl_adjust_hex`` function ``utils.color_hsl_adjust_hex`` function
5252
``comment_system_id`` str ``COMMENT_SYSTEM_ID`` setting
@@ -78,7 +78,7 @@ Name Type Descript
7878
``meta_generator_tag`` bool ``META_GENERATOR_TAG`` setting
7979
``momentjs_locales`` defaultdict<str, str> dictionary of available Moment.js locales
8080
``navigation_links`` TranslatableSetting ``NAVIGATION_LINKS`` setting
81-
``needs_ipython_css`` bool whether or not IPython CSS is needed by this site
81+
``needs_ipython_css`` bool whether or not Jupyter CSS is needed by this site
8282
``posts_sections`` bool ``POSTS_SECTIONS`` setting
8383
``posts_section_are_indexes`` bool ``POSTS_SECTIONS_ARE_INDEXES`` setting
8484
``posts_sections_are_indexes`` bool ``POSTS_SECTIONS_ARE_INDEXES`` setting
@@ -89,28 +89,25 @@ Name Type Descript
8989
``posts_section_title`` TranslatableSetting<str> ``POSTS_SECTION_TITLE`` setting
9090
``rel_link`` function ``Nikola.rel_link`` function
9191
``rss_link`` str ``RSS_LINK`` setting
92-
``rss_path`` TranslatableSetting<str> ``RSS_PATH`` setting
9392
``search_form`` TranslatableSetting<str> ``SEARCH_FORM`` setting
9493
``set_locale`` function ``LocaleBorg.set_locale`` function (or None if not available)
9594
``show_blog_title`` bool ``SHOW_BLOG_TITLE`` setting
9695
``show_sourcelink`` bool ``SHOW_SOURCELINK`` setting
9796
``site_has_comments`` bool whether or not a comment system is configured
98-
``SLUG_AUTHOR_PATH`` bool ``SLUG_AUTHOR_PATH`` setting
99-
``SLUG_TAG_PATH`` bool ``SLUG_TAG_PATH`` setting
10097
``social_buttons_code`` TranslatableSetting<str> ``SOCIAL_BUTTONS_CODE`` setting
10198
``sort_posts`` function ``utils.sort_posts`` function
99+
``smartjoin`` function ``utils.smartjoin`` function
100+
``colorize_str`` function ``utils.colorize_str`` function
102101
``template_hooks`` dict<str, TemplateHookRegistry> Template hooks registered by plugins
103102
``theme_color`` str ``THEME_COLOR`` setting
104103
``timezone`` tzinfo Timezone object (represents the configured timezone)
105104
``translations`` dict<str, str> ``TRANSLATIONS`` setting
106105
``twitter_card`` dict ``TWITTER_CARD`` setting, defaults to an empty dictionary
107106
``url_replacer`` function ``Nikola.url_replacer`` function
108107
``url_type`` str ``URL_TYPE`` setting
109-
``use_base_tag`` bool ``USE_BASE_TAG`` setting
110108
``use_bundles`` bool ``USE_BUNDLES`` setting
111109
``use_cdn`` bool ``USE_CDN`` setting
112110
``use_katex`` bool ``USE_KATEX`` setting
113-
``use_open_graph`` bool ``USE_OPEN_GRAPH`` setting, defaults to True
114111
``subtheme`` str? ``THEME_REVEAL_CONFIG_SUBTHEME`` setting (only if set — deprecated)
115112
``transition`` str? ``THEME_REVEAL_CONFIG_TRANSITION`` setting (only if set — deprecated)
116113
================================== ================================== ================================================================================
@@ -132,12 +129,13 @@ Name Type Description
132129
``title`` str Title of the page (taken from post, config, etc.)
133130
``formatmsg`` function Wrapper over ``%`` string formatting
134131
``striphtml`` function Strips HTML tags (Mako only)
132+
``crumbs`` list Breadcrumbs for this page
135133
================== ========== ===============================================================
136134

137135
__ https://getnikola.com/theming.html#identifying-and-customizing-different-kinds-of-pages-with-a-shared-template
138136

139-
Variables available in post pages (``post.tmpl``, ``story.tmpl`` etc.)
140-
----------------------------------------------------------------------
137+
Variables available in post pages (``post.tmpl``, ``page.tmpl`` etc.)
138+
---------------------------------------------------------------------
141139

142140
.. class:: table table-bordered table-striped
143141

@@ -253,12 +251,11 @@ Name Type Description
253251
``kind`` str The classification name
254252
``items`` list? List of items for ``list.tmpl`` *(title, permalink, None)*
255253
``posts`` list<Post>? List of items for other templates
256-
``kind`` str The classification name
257254
``permalink`` str Permanent link to page
258255
``other_languages`` list<tuple> List of triples ``(other_lang, other_classification, title)``
259256
=================== ============== =============================================================
260257

261-
Index-style classification pages have ``kind`` in addtion to the usual index variables.
258+
Index-style classification pages have ``kind`` in addition to the usual index variables.
262259

263260
Subclassification page
264261
~~~~~~~~~~~~~~~~~~~~~~

‎stories/theming.txt ‎stories/theming.rst

+38-27
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Theming Nikola
1010
==============
1111

12-
:Version: 7.8.14
12+
:Version: 8.0.0b1
1313
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>
1414

1515
.. class:: alert alert-primary float-md-right
@@ -19,7 +19,7 @@ Theming Nikola
1919
.. class:: lead
2020

2121
This document is a reference about themes. If you want a tutorial, please read
22-
`Creating a Theme <creating-a-theme.html>`_. If you’re looking for a ready-made
22+
:doc:`Creating a Theme <creating-a-theme>`. If you’re looking for a ready-made
2323
theme for your site, check out the `Themes Index <https://themes.getnikola.com/>`_.
2424

2525
The Structure
@@ -36,9 +36,9 @@ assets
3636
references to them. The default subdirectories are ``css``, ``js``, ``xml``
3737
and ``fonts`` (Bootstrap).
3838

39-
The included themes use `Bootstrap <https://getbootstrap.com/>`_, `Colorbox
40-
<http://www.jacklmoore.com/colorbox>`_, `Flowr.js
41-
<https://github.com/kalyan02/flowr-js>`_ and `Moment.js
39+
The included themes use `Bootstrap <https://getbootstrap.com/>`_,
40+
`baguetteBox <https://feimosi.github.io/baguetteBox.js/>`_, `Justified Layout by Flickr
41+
<http://flickr.github.io/justified-layout/>`_ and `Moment.js
4242
<https://momentjs.com/>`_, so they are in assets, along with CSS files for
4343
syntax highlighting, reStructuredText and Jupyter, as well as a minified
4444
copy of jQuery.
@@ -78,7 +78,7 @@ bundles
7878

7979
.. code:: text
8080
81-
assets/css/all.css=bootstrap.css,rst.css,code.css,colorbox.css,custom.css
81+
assets/css/all.css=bootstrap.min.css,rst_base.css,nikola_rst.css,code.css,baguetteBox.min.css,theme.css,custom.css
8282
8383
This creates a file called "assets/css/all.css" in your output that is the
8484
combination of all the other file paths, relative to the output file.
@@ -143,7 +143,7 @@ The following keys are currently supported:
143143
* ``tags`` — optional list of tags (comma-separated) to describe the theme.
144144

145145
* ``Family`` — contains information about other related themes. All values
146-
optional.
146+
optional. (Do not use unless you have related themes.)
147147

148148
* ``family`` — the name of the main theme in a family, which is also used as
149149
the family name.
@@ -158,9 +158,6 @@ The following keys are currently supported:
158158
defaults to False)
159159
* ``ignored_assets`` — comma-separated list of assets to ignore (relative to
160160
the ``assets/`` directory, eg. ``css/theme.css``)
161-
* ``ignore_colorbox_i18n`` — prevent copying Colorbox locales. Accepted
162-
values: ``all`` (all ignored), ``unused`` (used locales copied),
163-
``none`` (all copied)
164161

165162
Templates
166163
---------
@@ -176,11 +173,36 @@ should learn one first. What engine is used by the theme is declared in the ``en
176173
you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__
177174

178175

179-
Both template engines have a nifty concept of template inheritance. That means that, a
176+
Both template engines have a nifty concept of template inheritance. That means that a
180177
template can inherit from another and only change small bits of the output. For example,
181178
``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
182179
so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
183180

181+
Another concept is theme inheritance. You do not need to duplicate all the
182+
default templates in your theme — you can just override the ones you want
183+
changed, and the rest will come from the parent theme. (Every theme needs a
184+
parent.)
185+
186+
Apart from the `built-in templates`_ listed below, you can add other templates for specific
187+
pages, which the user can then use in his ``POSTS`` or ``PAGES`` option in
188+
``conf.py``. Also, you can specify a custom template to be used by a post or
189+
page via the ``template`` metadata, and custom templates can be added in the
190+
``templates/`` folder of your site.
191+
192+
If you want to modify (override) a built-in template, use ``nikola theme -c
193+
<name>.tmpl``. This command will copy the specified template file to the
194+
``templates/`` directory of your currently used theme.
195+
196+
Keep in mind that your theme is *yours*, so you can require whatever data you
197+
want (eg. you may depend on specific custom ``GLOBAL_CONTEXT`` variables, or
198+
post meta attributes). You don’t need to keep the same theme structure as the
199+
default themes do (although many of those names are hardcoded). Inheriting from
200+
at least ``base`` (or ``base-jinja``) is heavily recommended, but not strictly
201+
required (unless you want to share it on the Themes Index).
202+
203+
Built-in templates
204+
------------------
205+
184206
These are the templates that come with the included themes:
185207

186208
``base.tmpl``
@@ -195,10 +217,7 @@ These are the templates that come with the included themes:
195217
Template used to render the multipost indexes. The posts are in a ``posts`` variable.
196218
Some functionality is in the ``index_helper.tmpl`` helper template.
197219

198-
``annotation_helper.tmpl`` (internal)
199-
Code for the optional annotations feature.
200-
201-
``archive_navigation_helper.tmpl``
220+
``archive_navigation_helper.tmpl`` (internal)
202221
Code that implements archive navigation (previous/up/next). Included by
203222
archive templates.
204223

@@ -219,7 +238,7 @@ These are the templates that come with the included themes:
219238
It uses a bunch of helper templates, one for each supported comment system
220239
(all of which start with ``comments_helper``)
221240

222-
``crumbs.tmpl``, ``slides.tmpl``, ``pagination_helper.tmpl``
241+
``ui_helper.tmpl``, ``pagination_helper.tmpl``
223242
These templates help render specific UI items, and can be tweaked as needed.
224243

225244
``gallery.tmpl``
@@ -237,7 +256,8 @@ These are the templates that come with the included themes:
237256
+ ``title``: The title of the image.
238257
+ ``size``: A dict containing ``w`` and ``h``, the real size of the thumbnail.
239258

240-
* ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js
259+
* ``photo_array_json``: a JSON dump of photo_array, used by the
260+
``justified-layout`` script
241261

242262
``list.tmpl``
243263
Template used to display generic lists of links, which it gets in ``items``,
@@ -264,7 +284,7 @@ These are the templates that come with the included themes:
264284
Used to display section indexes, if ``POST_SECTIONS_ARE_INDEXES`` is True.
265285
By default, it just inherits ``index.tmpl``, with added feeds.
266286

267-
``story.tmpl``
287+
``page.tmpl``
268288
Used for pages that are not part of a blog, usually a cleaner, less
269289
intrusive layout than ``post.tmpl``, but same parameters.
270290

@@ -279,15 +299,6 @@ These are the templates that come with the included themes:
279299
``tags.tmpl``
280300
Used to display the list of tags and categories.
281301

282-
You can add other templates for specific pages, which the user can then use in his ``POSTS``
283-
or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is
284-
*yours*, there is no reason why you would need to maintain the inheritance as
285-
it is, or not require whatever data you want (eg. you may depend on specific
286-
custom ``GLOBAL_CONTEXT`` variables, or post meta attributes)
287-
288-
Also, you can specify a custom template to be used by a post or page via the ``template`` metadata,
289-
and custom templates can be added in the ``templates/`` folder of your site.
290-
291302
Variables available in templates
292303
--------------------------------
293304

0 commit comments

Comments
 (0)
Please sign in to comment.