Changes from getnikola/nikola@a3dd4c2 getnikola/nikola-themes#131

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Aug 27, 2017 · c2049cf · c2049cf
1 parent bbddeb3
commit c2049cf
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 14 deletions.
diff --git a/state_data.json b/state_data.json
@@ -1,3 +1,3 @@
 {
-  "last_deploy": "2017-07-04T07:35:49.893746"
+  "last_deploy": "2017-08-27T13:05:10.676589"
 }
diff --git a/stories/creating-a-theme.txt b/stories/creating-a-theme.txt
@@ -18,7 +18,7 @@ create themes. Since I **suck** at designing websites, I asked for opinions on t
 and got some feedback. Since this is **Not So Hard™**, I will try to make time to port a few
 and see what happens.
 
-If you are looking for a reference, check out `Theming reference <theming.html>`_ and `Template variables <https://getnikola.com/template-variables.html>`_.
+If you are looking for a reference, check out :doc:`Theming reference <theming>` and `Template variables <https://getnikola.com/template-variables.html>`_.
 
 Today’s theme is `Lanyon <https://github.com/poole/lanyon>`__ which is written by `@mdo <https://twitter.com/mdo>`__
 and released under a MIT license, which is liberal enough.
@@ -827,3 +827,5 @@ The End
 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.
 
 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/ .
+
+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.
diff --git a/stories/theming.txt b/stories/theming.txt
@@ -19,7 +19,7 @@ Theming Nikola
 .. class:: lead
 
 This document is a reference about themes. If you want a tutorial, please read
-`Creating a Theme <creating-a-theme.html>`_. If you’re looking for a ready-made
+:doc:`Creating a Theme <creating-a-theme>`. If you’re looking for a ready-made
 theme for your site, check out the `Themes Index <https://themes.getnikola.com/>`_.
 
 The Structure
@@ -176,11 +176,36 @@ should learn one first. What engine is used by the theme is declared in the ``en
    you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__
 
 
-Both template engines have a nifty concept of template inheritance. That means that, a
+Both template engines have a nifty concept of template inheritance. That means that a
 template can inherit from another and only change small bits of the output. For example,
 ``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
 so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
 
+Another concept is theme inheritance. You do not need to duplicate all the
+default templates in your theme — you can just override the ones you want
+changed, and the rest will come from the parent theme. (Every theme needs a
+parent.)
+
+Apart from the `built-in templates`_ listed below, you can add other templates for specific
+pages, which the user can then use in his ``POSTS`` or ``PAGES`` option in
+``conf.py``.  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.
+
+If you want to modify (override) a built-in template, use ``nikola theme -c
+<name>.tmpl``.  This command will copy the specified template file to the
+``templates/`` directory of your currently used theme.
+
+Keep in mind that your theme is *yours*, so you can require whatever data you
+want (eg. you may depend on specific custom ``GLOBAL_CONTEXT`` variables, or
+post meta attributes). You don’t need to keep the same theme structure as the
+default themes do (although many of those names are hardcoded). Inheriting from
+at least ``base`` (or ``base-jinja``) is heavily recommended, but not strictly
+required (unless you want to share it on the Themes Index).
+
+Built-in templates
+------------------
+
 These are the templates that come with the included themes:
 
 ``base.tmpl``
@@ -198,7 +223,7 @@ These are the templates that come with the included themes:
 ``annotation_helper.tmpl`` (internal)
     Code for the optional annotations feature.
 
-``archive_navigation_helper.tmpl``
+``archive_navigation_helper.tmpl`` (internal)
     Code that implements archive navigation (previous/up/next). Included by
     archive templates.
 
@@ -279,15 +304,6 @@ These are the templates that come with the included themes:
 ``tags.tmpl``
     Used to display the list of tags and categories.
 
-You can add other templates for specific pages, which the user can then use in his ``POSTS``
-or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is
-*yours*, there is no reason why you would need to maintain the inheritance as
-it is, or not require whatever data you want (eg. you may depend on specific
-custom ``GLOBAL_CONTEXT`` variables, or post meta attributes)
-
-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.
-
 Variables available in templates
 --------------------------------