diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 10ecc8fcce2..e6dfc5953a9 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -194,7 +194,7 @@ Organizations based authorization (see :doc:`authorization`):
  * New authorization ini file options
 
 
-New frontend (see :doc:`theming`):
+New frontend (see :doc:`theming/index`):
  CKAN's frontend has been completely redesigned, inside and out. There is
  a new default theme and the template engine has moved from Genshi to
  Jinja2. Any custom templates using Genshi will need to be updated, although
diff --git a/ckan/plugins/interfaces.py b/ckan/plugins/interfaces.py
index 14d64b01146..f3dfce7d962 100644
--- a/ckan/plugins/interfaces.py
+++ b/ckan/plugins/interfaces.py
@@ -770,7 +770,7 @@ def read_template(self):
 
         If the user requests the dataset in a format other than HTML
         (CKAN supports returning datasets in RDF or N3 format by appending .rdf
-        or .n3 to the dataset read URL, see :doc:`linked-data-and-rdf`) then
+        or .n3 to the dataset read URL, see :doc:`/linked-data-and-rdf`) then
         CKAN will try to render
         a template file with the same path as returned by this function,
         but a different filename extension, e.g. ``'package/read.rdf'``.
diff --git a/ckan/plugins/toolkit.py b/ckan/plugins/toolkit.py
index 34e9d671cf1..3e5ba71f8f8 100644
--- a/ckan/plugins/toolkit.py
+++ b/ckan/plugins/toolkit.py
@@ -216,7 +216,7 @@ def _initialize(self):
     def _render_snippet(cls, template, data=None):
         '''Render a template snippet and return the output.
 
-        See :doc:`/theming`.
+        See :doc:`/theming/index`.
 
         '''
         data = data or {}
@@ -266,7 +266,7 @@ def _add_resource(cls, path, name):
         Fanstatic libraries are directories containing static resource files
         (e.g. CSS, JavaScript or image files) that can be accessed from CKAN.
 
-        See :doc:`/theming` for more details.
+        See :doc:`/theming/index` for more details.
 
         '''
         # we want the filename that of the function caller but they will
diff --git a/doc/conf.py b/doc/conf.py
index 22e1049600a..b5f78af3ac7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -58,6 +58,10 @@
 .. |javascript| replace:: JavaScript
 .. |apache| replace:: Apache
 
+.. _Jinja2: http://jinja.pocoo.org/
+.. _CKAN front page: http://127.0.0.1:5000
+.. _bootstrap: http://getbootstrap.com/2.3.2/
+
 '''
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 8cf90b9ab2d..1c76289685a 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -655,7 +655,7 @@ Format tips:
 * the format is Markdown
 
 .. note:: Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable.
-          For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming`.
+          For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming/index`.
 
 .. _ckan.main_css:
 
@@ -951,7 +951,7 @@ Example::
 
 To customise the display of CKAN you can supply replacements for the Genshi template files. Use this option to specify where CKAN should look for additional templates, before reverting to the ``ckan/templates`` folder. You can supply more than one folder, separating the paths with a comma (,).
 
-For more information on theming, see :doc:`theming`.
+For more information on theming, see :doc:`theming/index`.
 
 .. _extra_public_paths:
 
@@ -964,7 +964,7 @@ Example::
 
 To customise the display of CKAN you can supply replacements for static files such as HTML, CSS, script and PNG files. Use this option to specify where CKAN should look for additional files, before reverting to the ``ckan/public`` folder. You can supply more than one folder, separating the paths with a comma (,).
 
-For more information on theming, see :doc:`theming`.
+For more information on theming, see :doc:`theming/index`.
 
 .. end_config-theming
 
diff --git a/doc/index.rst b/doc/index.rst
index e0167318ecb..2ec40ed7af9 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,7 +19,7 @@ advanced documentation last:
   beyond those that just work out of the box.  These are for **sysadmins** who
   want to learn how to manage and get more out of their CKAN site.
 
-* :doc:`extensions/index`, :doc:`theming` and :doc:`api` are advanced docs
+* :doc:`extensions/index`, :doc:`theming/index` and :doc:`api` are advanced docs
   for **developers** who want to develop an extension, theme or API app using
   CKAN.
 
@@ -39,7 +39,7 @@ advanced documentation last:
    getting-started
    features
    extensions/index
-   theming
+   theming/index
    api
    contributing
    test
diff --git a/doc/tag-vocabularies.rst b/doc/tag-vocabularies.rst
index f86d4332aaa..4a467808b78 100644
--- a/doc/tag-vocabularies.rst
+++ b/doc/tag-vocabularies.rst
@@ -65,6 +65,6 @@ To add a tag vocabulary to a site, a CKAN sysadmin must:
 
 3. Provide custom dataset templates to display the new field to users when
    adding, updating or viewing datasets in the CKAN web interface.
-   See :doc:`theming`.
+   See :doc:`theming/index`.
 
 See ``ckanext/example_idatasetform`` for a working example of these steps.
diff --git a/doc/template-helper-functions.rst b/doc/template-helper-functions.rst
deleted file mode 100644
index 77a36f972dc..00000000000
--- a/doc/template-helper-functions.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-=========================
-Template helper functions
-=========================
-
-.. automodule:: ckan.lib.helpers
-   :members:
-   :undoc-members:
diff --git a/doc/theming/css.rst b/doc/theming/css.rst
new file mode 100644
index 00000000000..e2add6e26f3
--- /dev/null
+++ b/doc/theming/css.rst
@@ -0,0 +1,63 @@
+======================
+Customizing CKAN's CSS
+======================
+
+Extensions can add their own CSS files to modify or extend CKAN's default CSS.
+Create an ``example_theme.css`` file in your extension's ``public`` directory::
+
+    ckanext-example_theme/
+      public/
+        example_theme.css
+
+Add this CSS into the ``example_theme.css`` file, to change the color of CKAN's
+"account masthead" (the bar across the top of the site that shows the logged-in
+user's account info):
+
+.. literalinclude:: /../ckanext/example_theme/v12_custom_css/public/example_theme.css
+
+If your restart the development web server (kill the server using Ctrl-c, then
+run the ``paster serve`` command again) you should be able to open this file at
+http://127.0.0.1:5000/example_theme.css in a web browser.
+
+To make CKAN use our custom CSS we need to override the ``base.html`` template,
+this is the base template which the templates for all CKAN pages extend, so if
+we include a CSS file in this base template then the file will be included in
+every page of your CKAN site. Create the file::
+
+    ckanext-example_theme/
+      templates/
+        base.html
+
+and put this Jinja code in it:
+
+.. literalinclude:: /../ckanext/example_theme/v12_custom_css/templates/base.html
+
+The default ``base.html`` template defines a ``styles`` block which can be
+extended to link to custom CSS files (any code in the styles block will appear
+in the ``<head>`` of the HTML page).
+
+Restart the development web server, and you should see the background color of
+the account masthead change. This custom color should appear on all pages of
+your CKAN site.
+
+Now that we have CKAN using our CSS file, we can add more CSS rules to the file
+and customize CKAN's CSS as much as we want. There's nothing special about CSS
+in CKAN, you just use the usual tools and techniques to explore and hack the
+CSS.
+
+.. todo:: Link to some tools?
+
+   e.g. Firefox inspector etc (or Chrome? Firebug?)
+
+   e.g. Some online CSS reference.
+
+Let's add a bit more code to our ``example_theme.css`` file. This CSS
+implements a partial imitation of the `datahub.io <http://datahub.io/>`_ theme
+(circa 2013):
+
+.. literalinclude:: /../ckanext/example_theme/v13_more_custom_css/public/example_theme.css
+
+.. todo::
+
+   We use LESS for the CKAN core CSS. Do we want to mention that here?
+
diff --git a/doc/theming/index.rst b/doc/theming/index.rst
new file mode 100644
index 00000000000..7f508c7791f
--- /dev/null
+++ b/doc/theming/index.rst
@@ -0,0 +1,31 @@
+=======
+Theming
+=======
+
+The CKAN web interface's HTML, CSS and JavaScript is fully customizable by
+creating a CKAN theme.
+If you just want to do some simple customizations such as changing the title
+of your CKAN site, or making some small CSS customizations,
+:doc:`/getting-started` documents some simple configuration settings you can
+use.
+If you want more control, follow the tutorials below to learn how to develop
+your custom CKAN theme.
+
+
+.. note::
+
+  Before you can start developing a CKAN theme, you’ll need a working source
+  install of CKAN on your system. If you don't have a CKAN source install
+  already, follow the instructions in :doc:`/install-from-source` before
+  continuing.
+
+.. toctree::
+   :maxdepth: 2
+
+   templates
+   static-files
+   css
+   javascript
+   jinja-tags
+   variables-and-functions
+   template-helper-functions
diff --git a/doc/theming/javascript.rst b/doc/theming/javascript.rst
new file mode 100644
index 00000000000..9532734635b
--- /dev/null
+++ b/doc/theming/javascript.rst
@@ -0,0 +1,120 @@
+=============================
+Customizing CKAN's JavaScript
+=============================
+
+.. todo:: Link to an introductory JavaScript tutorial.
+
+.. todo:: Introduce the example we're doing here: starring datasets using a
+     custom dataset_star action (also need the code to add this action).
+
+.. todo:: Explain that Bootstrap's JavaScript features can be used just by CSS.
+
+
+--------------------------------
+Initializing a JavaScript module
+--------------------------------
+
+To get CKAN to call some custom JavaScript code, we need to:
+
+1. Implement a |javascript| module, and register it with CKAN.
+   Create the file ``ckanext-example_theme/fanstatic/favorite.js``, with these
+   contents:
+
+   .. literalinclude:: /../ckanext/example_theme/v14_initialize_a_javascript_module/fanstatic/favorite.js
+
+   This bit of |javascript| calls the ``ckan.module()`` function to register a
+   new JavaScript module with CKAN. ``ckan.module()`` takes two arguments: the
+   name of the module being registered (``'favorite'`` in this example) and a
+   function that returns the module itself. The function takes two arguments,
+   which we'll look at later. The module is just a |javascript| object with a
+   single attribute, ``initialize``, whose value is a function that CKAN will
+   call to initialize the module. In this example, the initialize function just
+   prints out a confirmation message - this |javascript| module doesn't do
+   anything interesting yet.
+
+2. Include the |javascript| module in a page, using Fanstatic, and apply it to
+   one or more HTML elements on that page. We'll override CKAN's
+   ``package_item.html`` template snippet to insert our module whenever a
+   package is rendered as part of a list of packages (for example, on the
+   dataset search page). Create the file
+   ``ckanext-example_theme/templates/snippets/package_item.html`` with these
+   contents:
+
+   .. literalinclude:: /../ckanext/example_theme/v14_initialize_a_javascript_module/templates/snippets/package_item.html
+
+   .. todo:: Link to something about HTML data-* attributes.
+
+   If you now restart the development server and open
+   http://127.0.0.1:5000/dataset in your web browser, you should see an
+   extra "star this dataset" button next to each dataset shown. If you open a
+   |javascript| console in your browser, you should see the message that your
+   module has printed out.
+
+   .. todo:: Link to something about JavaScript consoles.
+
+   If you have more than one dataset on your page, you'll see the module's
+   message printed once for each dataset. The ``package_item.html`` template
+   snippet is rendered once for each dataset that's shown in the list, and
+   CKAN creates a new instance of your |javascript| module for each dataset.
+   If you view the source of your page, however, you'll see that
+   ``favorite.js`` is only included with a ``<script>`` tag once. Fanstatic
+   is smart enough to deduplicate resources.
+
+   .. note:: |javascript| modules *must* be included as Fanstatic resources,
+      you can't add them to a ``public`` directory and include them using your
+      own ``<script>`` tags.
+
+
+--------------------
+Responding to events
+--------------------
+
+To get our |javascript| module to do something more interesting, we'll use its
+initialize function to register some event handler functions which we'll then
+use to do some actions in response to events such as mouse clicks. Edit your
+``favorite.js`` file to look like this:
+
+.. Link to some JavaScript tutorial?
+
+   JavaScript modules are the core - every javascripted object should be a
+   module. Small, isolated components that can be easily tested. They should
+   not use any global objects, all functionality provided to them via a sandbox
+   object.
+
+   A module is a JavaScript object with an initialize() and a teardown()
+   method.
+
+   Initialize a module with a data-module attribute:
+     <select name="format" data-module="autocomplete"></select>
+
+   Or apparently you can also use {% resource %}? Or you have to use resource?
+
+   "favorite" module goes in favorite.js file.
+
+   The idea is that the HTML element should still work fine is JavaScript is
+   disabled - e.g. use form submission instead of XHR request.
+
+   You can pass "options objects" with further data-module-* attributes.
+
+   The modules are initialized "on DOM ready", each module's initialize()
+   method is called.
+
+   this.sandbox.jQuery - access jQuery methods
+   this.sandbox.translte() - i18n
+   (or these are the jQuery and _ params of your module function)
+
+   pub/sub for sending messages between modules:
+   this.sandbox.publish/subscribe/unsubscribe
+
+   this.sandbox.client should be used to make XHR requests to the CKAN API
+   (not jQuery.ajax())
+
+   i18n: this.sandbox.translate(), supports %(name)s, including plurals.
+   The options() method of each module should set all strings to be i18n'd?
+   Then other code uses this.18n() to retrieve them.
+
+   If not CKAN specific, module functionality should be packaged up in jQuery
+   plugins.
+
+   Testing.
+
diff --git a/doc/theming/jinja-tags.rst b/doc/theming/jinja-tags.rst
new file mode 100644
index 00000000000..7ff8d1f35a6
--- /dev/null
+++ b/doc/theming/jinja-tags.rst
@@ -0,0 +1,5 @@
+============================
+Custom Jinja2 tags reference
+============================
+
+.. todo::
diff --git a/doc/theming/static-files.rst b/doc/theming/static-files.rst
new file mode 100644
index 00000000000..34c1302cc11
--- /dev/null
+++ b/doc/theming/static-files.rst
@@ -0,0 +1,151 @@
+===================
+Adding static files
+===================
+
+---------------------------------------------------
+Adding static files using a simple public directory
+---------------------------------------------------
+
+You may need to add some custom *static files* to your CKAN site and use them
+from your templates, for example image files, PDF files, or any other static
+files that should be returned as-is by the webserver (as opposed to Jinja
+template files, which CKAN renders before returning them to the user).
+
+By adding a directory to CKAN's :ref:`extra_public_paths` config setting,
+a plugin can make a directory of static files available to be used or linked to
+by templates. Let's add a static image file, and change the home page template
+to use our file as the promoted image on the front page.
+
+.. note::
+
+   If you're adding |javascript| or CSS files, consider using Fanstatic instead
+   of :ref:`extra_public_paths`, to take advantage of extra features.
+   See :ref:`fanstatic tutorial` below.
+
+First, create a ``public`` directory in your extension with a
+``promoted-image.jpg`` file in it::
+
+ ckanext-example_theme/
+   public/
+     promoted-image.jpg
+
+``promoted-image.jpg`` should be a 420x220px JPEG image file. You could use
+this image file for example:
+
+.. image:: /../ckanext/example_theme/v11_extra_public_directory/public/promoted-image.jpg
+   :alt: An example promoted image
+   :height: 220px
+   :width: 420px
+
+Then in ``plugin.py``, register your ``public`` directory with CKAN by calling
+the :py:func:`~ckan.plugins.toolkit.add_public_directory` function. Add this
+line to the :py:func:`~ckan.ckanext.example_theme.v11_extra_public_directory.plugin.update_config`
+function:
+
+.. literalinclude:: /../ckanext/example_theme/v11_extra_public_directory/plugin.py
+   :pyobject: ExampleThemePlugin.update_config
+
+If you now browse to `127.0.0.1:5000/promoted-image.jpg <http://127.0.0.1:5000/promoted-image.jpg>`_,
+you should see your image file.
+
+To replace the image on the front page with your custom image, we need to
+override the ``promoted.html`` template snippet. Create the following directory
+and file::
+
+ ckanext-example_theme/
+   templates/
+     home/
+       snippets/
+         promoted.html
+
+Edit your new ``promoted.html`` snippet, and insert these contents:
+
+.. literalinclude:: /../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
+
+After calling ``{% ckan_extends %}`` to declare that it extends (rather than
+completely replaces) the default ``promoted.html`` snippet, this custom snippet
+overrides two of ``promoted.html``'s template blocks. The first block replaces
+the caption text of the promoted image. The second block replaces the ``<img>``
+tag itself, pointing it at our custom static image file:
+
+.. literalinclude:: /../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
+   :start-after: {# Replace the promoted image. #}
+
+If you now reload the `CKAN front page`_ in your browser, you should see the
+promoted image replaced with our custom one.
+
+
+.. _fanstatic tutorial:
+
+------------------------------------------------
+Adding |javascript| and CSS file using Fanstatic
+------------------------------------------------
+
+If you're adding |javascript| or CSS files to your theme, you can add them
+using `Fanstatic <http://www.fanstatic.org/>`_ rather than the simple
+:ref:`extra_public_paths` method described above (`JavaScript modules
+<javascript modules>`_ *must* be added using Fanstatic). Using Fanstatic to add
+|javascript| and CSS files allows you to take advantage of Fanstatic's
+features, such as automatically serving minified files in production, caching
+and bundling files together to reduce page load times, specifying dependencies
+between files so that the files a page needs (and only the files it needs) are
+always loaded, and other tricks to optimize page load times.
+
+.. note::
+
+   CKAN will only serve ``*.js`` and ``*.css`` files as Fanstatic resources,
+   other types of static files (eg. image files, PDF files) must be added
+   using the :ref:`extra_public_paths` method described above.
+
+Adding a custom |javascript| or CSS file to CKAN is using Fanstatic is simple:
+
+.. todo:: Turn this into a real working example.
+
+1. First, create a fanstatic directory in your extension with the CSS and
+   |javascript| files in it::
+
+    ckanext-example_theme/
+      fanstatic/
+        my_style.css
+        my_script.js
+
+2. Use CKAN's ``add_resource()`` function to register your fanstatic
+   directory with CKAN. Edit the ``update_config()`` method in your
+   ``plugin.py`` file::
+
+        def update_config(self, config):
+
+            # Add this plugin's templates dir to CKAN's extra_template_paths, so
+            # that CKAN will use this plugin's custom templates.
+            toolkit.add_template_directory(config, 'templates')
+
+            # Add this plugin's public dir to CKAN's extra_public_paths, so
+            # that CKAN will use this plugin's custom static files.
+            toolkit.add_public_directory(config, 'public')
+
+            toolkit.add_resource('fanstatic', 'example_theme')
+
+   The second argument to ``add_resource()``, ``'example_theme'``, is the name
+   that you'll need to use to refer to your custom Fanstatic library from
+   templates (you can pass whatever name you want here).
+
+3. Finally, use CKAN's custom Jinja2 tag ``{% resource %}`` to import the file
+   in the template that needs it::
+
+     {% resource 'example_theme/my_script.js' %}
+     {% resource 'example_theme/my_style.css' %}
+
+   You can put the ``{% resource %}`` tag anywhere in the template, and
+   Fanstatic will insert and necessary ``<style>`` and ``<script>`` tags to
+   include your |javascript| and CSS files and their dependencies in the right
+   places in the HTML output (CSS files in the HTML ``<head>``, |javascript|
+   files at the bottom of the page).
+
+.. todo:: Add a note about Fanstatic resource configuration file.
+
+----------------------------------
+Fanstatic resource troubleshooting
+----------------------------------
+
+``AttributeError``
+==================
diff --git a/doc/theming/substitutions.rst b/doc/theming/substitutions.rst
new file mode 100644
index 00000000000..a79adc79773
--- /dev/null
+++ b/doc/theming/substitutions.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+{# Some common substitutions included by rst files in this directory. #}
+
+.. |extension_dir| replace:: ``ckanext-example_theme``
+.. |setup.py| replace:: ``ckanext-example_theme/setup.py`` ``ckan.plugins``
+.. |plugin.py| replace:: ``ckanext-example_theme/ckanext/example_theme/plugin.py``
+.. |templates_dir| replace:: ``ckanext-example_theme/ckanext/example_theme/templates``
+.. |index.html| replace:: ``ckanext-example_theme/ckanext/example_theme/templates/home/index.html``
+.. |snippets_dir| replace:: ``ckanext-example_theme/ckanext/example_theme/templates/snippets``
diff --git a/doc/theming/template-helper-functions.rst b/doc/theming/template-helper-functions.rst
new file mode 100644
index 00000000000..a16e698b88f
--- /dev/null
+++ b/doc/theming/template-helper-functions.rst
@@ -0,0 +1,7 @@
+===================================
+Template helper functions reference
+===================================
+
+.. automodule:: ckan.lib.helpers
+   :members:
+   :undoc-members:
diff --git a/doc/theming.rst b/doc/theming/templates.rst
similarity index 57%
rename from doc/theming.rst
rename to doc/theming/templates.rst
index d00b35ab63c..0a967d1e6b1 100644
--- a/doc/theming.rst
+++ b/doc/theming/templates.rst
@@ -1,60 +1,21 @@
-.. _Jinja2: http://jinja.pocoo.org/
-.. _CKAN front page: http://127.0.0.1:5000
-.. _bootstrap: http://getbootstrap.com/2.3.2/
-
-.. |extension_dir| replace:: ``ckanext-example_theme``
-.. |setup.py| replace:: ``ckanext-example_theme/setup.py`` ``ckan.plugins``
-.. |plugin.py| replace:: ``ckanext-example_theme/ckanext/example_theme/plugin.py``
-.. |templates_dir| replace:: ``ckanext-example_theme/ckanext/example_theme/templates``
-.. |index.html| replace:: ``ckanext-example_theme/ckanext/example_theme/templates/home/index.html``
-.. |snippets_dir| replace:: ``ckanext-example_theme/ckanext/example_theme/templates/snippets``
-
-
-=======
-Theming
-=======
-
-The CKAN frontend can be fully customized by developing a CKAN theme.
-If you just want to do some simple customizations such as changing the title
-of your CKAN site, or making some small CSS customizations,
-:doc:`getting-started` documents some simple configuration settings you can
-use.
-If you want more control, CKAN themes can customize all aspects of CKAN's
-frontend, including changing any of CKAN's templates or template snippets,
-adding custom snippets and helper functions, customizing CSS and JavaScript,
-and adding static files such as images. Follow the tutorial below to learn how
-to develop your custom CKAN theme.
-
-
-----------------
-Theming tutorial
-----------------
+.. include:: ./substitutions.rst
+
+============================
+Customizing CKAN's templates
+============================
 
 This tutorial walks you through the process of creating an example CKAN theme
 that demonstrates all of the main features of CKAN theming.
 
 
-Installing CKAN
-===============
-
-Before you can start developing a CKAN theme, you’ll need a working source
-install of CKAN on your system. If you don’t have a CKAN source install
-already, follow the instructions in :doc:`install-from-source` before
-continuing.
-
-.. todo::
-
-   Insert section about installing the extra dependencies needed for frontend
-   development, and running less.
-
-
+-------------------------
 Creating a CKAN extension
-=========================
+-------------------------
 
 A CKAN theme is simply a CKAN plugin that contains some custom templates and
 static files, so before getting started on our CKAN theme we'll have to create
 an extension and plugin. For a detailed explanation of the steps below, see
-:doc:`extensions/tutorial`.
+:doc:`/extensions/tutorial`.
 
 1. Use the ``paster create`` command to create an empty extension:
 
@@ -66,7 +27,7 @@ an extension and plugin. For a detailed explanation of the steps below, see
 
 2. Create the file |plugin.py| with the following contents:
 
-   .. literalinclude:: ../ckanext/example_theme/v1_empty_extension/plugin.py
+   .. literalinclude:: /../ckanext/example_theme/v1_empty_extension/plugin.py
 
 3. Edit the ``entry_points`` in |setup.py|::
 
@@ -102,8 +63,11 @@ an extension and plugin. For a detailed explanation of the steps below, see
    *do* anything yet.
 
 
-Customizing CKAN's HTML with Jinja2 templates
-=============================================
+.. _template overriding:
+
+---------------------------------
+Replacing a default template file
+---------------------------------
 
 Every CKAN page is generated by rendering a particular template. For each
 page of a CKAN site there's a corresponding template file. For example the
@@ -112,36 +76,30 @@ front page is generated from the ``ckan/templates/home/index.html`` file, the
 datasets page at ``/dataset`` is generated from
 ``ckan/templates/package/search.html``, etc.
 
-
-.. _template overriding:
-
-Replacing a default template file
----------------------------------
-
 To customize pages, our plugin needs to register its own custom template
 directory containing templates file that override the default ones.
 Edit the |plugin.py| file that we created earlier, so that it looks like
 this:
 
-.. literalinclude:: ../ckanext/example_theme/v2_empty_template/plugin.py
+.. literalinclude:: /../ckanext/example_theme/v2_empty_template/plugin.py
 
 This new code does a few things:
 
 1. It imports CKAN's *plugins toolkit* module:
 
-   .. literalinclude:: ../ckanext/example_theme/v2_empty_template/plugin.py
+   .. literalinclude:: /../ckanext/example_theme/v2_empty_template/plugin.py
       :start-after: import ckan.plugins as plugins
       :end-before: class ExampleThemePlugin(plugins.SingletonPlugin):
 
    The plugins toolkit is a Python module containing core functions, classes
    and exceptions for CKAN plugins to use. For more about the plugins toolkit,
-   see :doc:`extensions/tutorial`.
+   see :doc:`/extensions/tutorial`.
 
 2. It calls :py:func:`~ckan.plugins.core.implements` to declare that it
    implements the :py:class:`~ckan.plugins.interfaces.IConfigurer` plugin
    interface:
 
-   .. literalinclude:: ../ckanext/example_theme/v2_empty_template/plugin.py
+   .. literalinclude:: /../ckanext/example_theme/v2_empty_template/plugin.py
       :start-after: # Declare that this class implements IConfigurer.
       :end-before: def update_config(
 
@@ -157,7 +115,7 @@ This new code does a few things:
    is the only method declared in the
    :py:class:`~ckan.plugins.interfaces.IConfigurer` interface:
 
-   .. literalinclude:: ../ckanext/example_theme/v2_empty_template/plugin.py
+   .. literalinclude:: /../ckanext/example_theme/v2_empty_template/plugin.py
       :pyobject: ExampleThemePlugin.update_config
 
    CKAN will call this method when it starts up, to give our plugin a chance to
@@ -216,6 +174,7 @@ an empty page, because we've replaced the template file for the front page with
 an empty file.
 
 
+------
 Jinja2
 ------
 
@@ -232,7 +191,7 @@ features than these, for full details see the
 .. _expressions and variables:
 
 Expressions and variables
-`````````````````````````
+=========================
 
 Jinja2 *expressions* are snippets of code between ``{{ ... }}`` delimiters,
 when a template is rendered any expressions are evaluated and replaced with
@@ -283,12 +242,12 @@ any template file:
    `literals and operators <http://jinja.pocoo.org/docs/templates/#expressions>`_
    that Jinja provides.
 
-   See :doc:`theming/variables-and-functions` for a list of variables and
+   See :doc:`variables-and-functions` for a list of variables and
    functions available to templates.
 
 
 Tags
-````
+====
 
 :ref:`ckan.site_title` is an example of a simple string variable.
 Some variables, such as :ref:`ckan.plugins`, are lists, and can be looped over
@@ -320,7 +279,7 @@ tested using Jinja's ``{% if %}`` tag:
 
 
 Comments
-````````
+========
 
 Finally, any text between ``{# ... #}`` delimiters in a Jinja2 template is a
 *comment*, and will not be output when the template is rendered:
@@ -338,6 +297,7 @@ Finally, any text between ``{# ... #}`` delimiters in a Jinja2 template is a
       filters?
 
 
+-----------------------------------------------
 Extending templates with ``{% ckan_extends %}``
 -----------------------------------------------
 
@@ -346,7 +306,7 @@ declare that our ``home/index.html`` template extends the default
 ``home/index.html`` template, instead of completely replacing it.
 Edit the empty ``index.html`` file you just created, and add one line:
 
-.. literalinclude:: ../ckanext/example_theme/v3_ckan_extends/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v3_ckan_extends/templates/home/index.html
 
 If you now reload the `CKAN front page`_ in your browser, you should see the
 normal front page appear again. When CKAN processes our ``index.html`` file,
@@ -354,6 +314,7 @@ the ``{% ckan_extends %}`` tag tells it to process the default
 ``home/index.html`` file first.
 
 
+----------------------------------------------
 Replacing template blocks with ``{% block %}``
 ----------------------------------------------
 
@@ -386,7 +347,7 @@ When a custom template file extends one of CKAN's default template files using
 template with its own code by using ``{% block %}``. Edit your ``index.html``
 file again and change the contents to:
 
-.. literalinclude:: ../ckanext/example_theme/v4_block/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v4_block/templates/home/index.html
 
 Reload the `CKAN front page`_ in your browser.
 You should see that the featured groups section of the page has been replaced,
@@ -398,13 +359,14 @@ but the rest of the page remains intact.
    Do you have to just look at the source?
 
 
+------------------------------------------------------
 Extending parent blocks with Jinja's ``{{ super() }}``
 ------------------------------------------------------
 
 If you want to add some code to a block but don't want to replace the entire
 block, you can use Jinja's ``{{ super() }}`` tag:
 
-.. literalinclude:: ../ckanext/example_theme/v5_super/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v5_super/templates/home/index.html
 
 When the child block above is rendered, Jinja will replace the
 ``{{ super() }}`` tag with the contents of the parent block.
@@ -413,6 +375,7 @@ The ``{{ super() }}`` tag can be placed anywhere in the block.
 
 .. _template helper functions:
 
+-------------------------
 Template helper functions
 -------------------------
 
@@ -424,7 +387,7 @@ For example, let's replace the featured groups on the front page with an
 activity stream of the site's recently created, updated and deleted datasets.
 Change the code in |index.html| to this:
 
-.. literalinclude:: ../ckanext/example_theme/v6_helper_function/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v6_helper_function/templates/home/index.html
 
 Reload the `CKAN front page`_ in your browser and you should see a new activity
 stream.
@@ -433,7 +396,7 @@ To call a template helper function we use a Jinja2 *expression* (code wrapped
 in ``{{ ... }}`` brackets), and we use the global variable ``h`` (available
 to all templates) to access the helper:
 
-.. literalinclude:: ../ckanext/example_theme/v6_helper_function/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v6_helper_function/templates/home/index.html
    :start-after: {% block secondary_content %}
    :end-before: {% endblock %}
 
@@ -443,12 +406,13 @@ To see what other template helper functions are available, look at the
 
 .. _custom template helper functions:
 
+-----------------------------------------
 Adding your own template helper functions
 -----------------------------------------
 
 Plugins can add their own template helper functions by implementing CKAN's
 :py:class:`~ckan.plugins.interfaces.ITemplateHelpers` plugin interface.
-(see :doc:`extensions/tutorial` for a detailed explanation of CKAN plugins and
+(see :doc:`/extensions/tutorial` for a detailed explanation of CKAN plugins and
 plugin interfaces).
 
 Let's add another item to our custom front page: a list of the most "popular"
@@ -458,21 +422,21 @@ template helper function to select the groups to be shown.  First, in our
 :py:class:`~ckan.plugins.interfaces.ITemplateHelpers` and provide our helper
 function. Change the contents of ``plugin.py`` to look like this:
 
-.. literalinclude:: ../ckanext/example_theme/v7_custom_helper_function/plugin.py
+.. literalinclude:: /../ckanext/example_theme/v7_custom_helper_function/plugin.py
 
 We've added a number of new features to ``plugin.py``. First, we defined a
 function to get the most popular groups from CKAN:
 
-.. literalinclude:: ../ckanext/example_theme/v7_custom_helper_function/plugin.py
+.. literalinclude:: /../ckanext/example_theme/v7_custom_helper_function/plugin.py
    :pyobject: most_popular_groups
 
 This function calls one of CKAN's *action functions* to get the groups from
-CKAN.  See :doc:`extensions/tutorial` for more about action functions.
+CKAN.  See :doc:`/extensions/tutorial` for more about action functions.
 
 Next, we called :py:func:`~ckan.plugins.implements` to declare that our class
 now implements :py:class:`~ckan.plugins.interfaces.ITemplateHelpers`:
 
-.. literalinclude:: ../ckanext/example_theme/v7_custom_helper_function/plugin.py
+.. literalinclude:: /../ckanext/example_theme/v7_custom_helper_function/plugin.py
    :start-after: # Declare that this plugin will implement ITemplateHelpers.
    :end-before: def update_config(self, config):
 
@@ -481,7 +445,7 @@ Finally, we implemented the
 :py:class:`~ckan.plugins.interfaces.ITemplateHelpers` to register our function
 as a template helper:
 
-.. literalinclude:: ../ckanext/example_theme/v7_custom_helper_function/plugin.py
+.. literalinclude:: /../ckanext/example_theme/v7_custom_helper_function/plugin.py
    :pyobject: ExampleThemePlugin.get_helpers
 
 Now that we've registered our helper function, we need to call it from our
@@ -489,7 +453,7 @@ template. As with CKAN's default template helpers, templates access custom
 helpers via the global variable ``h``.
 Edit |index.html| to look like this:
 
-.. literalinclude:: ../ckanext/example_theme/v7_custom_helper_function/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v7_custom_helper_function/templates/home/index.html
 
 Now reload your `CKAN front page`_ in your browser. You should see a list of
 the most popular groups appear on the page.
@@ -500,6 +464,7 @@ the group such as its description and logo image. To display our groups nicely,
 we'll use CKAN's *template snippets*.
 
 
+-----------------
 Template snippets
 -----------------
 
@@ -518,18 +483,18 @@ directories in ``ckan/templates/``, such as ``ckan/templates/snippets/`` and
 list of groups nicely (it's used to render the groups on CKAN's ``/group`` page
 and one user dashboard pages, for example):
 
-.. literalinclude:: ../ckan/templates/group/snippets/group_list.html
+.. literalinclude:: /../ckan/templates/group/snippets/group_list.html
 
 (As you can see, this snippet calls another snippet, ``group_item.html``, to
 render each individual group.)
 
 Let's change our |index.html| file to call this snippet:
 
-.. literalinclude:: ../ckanext/example_theme/v8_snippet/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v8_snippet/templates/home/index.html
 
 Here we pass two arguments to the ``{% snippet %}`` tag:
 
-.. literalinclude:: ../ckanext/example_theme/v8_snippet/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v8_snippet/templates/home/index.html
    :start-after: {# Call the group_list.html snippet. #}
    :end-before: {% endblock %}
 
@@ -544,6 +509,7 @@ If you reload your `CKAN front page`_ in your web browser now, you should see
 the dataset of the day rendered nicely.
 
 
+---------------------------------
 Adding your own template snippets
 ---------------------------------
 
@@ -566,7 +532,7 @@ whole thing on different parts of the site if we want to.
 Create a new directory |snippets_dir| containing a file named
 ``example_theme_most_popular_groups.html`` with these contents:
 
-.. literalinclude:: ../ckanext/example_theme/v9_custom_snippet/templates/snippets/example_theme_most_popular_groups.html
+.. literalinclude:: /../ckanext/example_theme/v9_custom_snippet/templates/snippets/example_theme_most_popular_groups.html
 
 .. todo::
 
@@ -576,7 +542,7 @@ Create a new directory |snippets_dir| containing a file named
 Now edit your |index.html| file and change it to use our new snippet instead of
 the default one:
 
-.. literalinclude:: ../ckanext/example_theme/v9_custom_snippet/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v9_custom_snippet/templates/home/index.html
 
 .. warning::
 
@@ -600,12 +566,13 @@ the default one:
 .. note::
 
    Snippets don't have access to the global template context variable, ``c``
-   (see :doc:`theming/variables-and-functions`). Snippets *can* access other
+   (see :doc:`variables-and-functions`). Snippets *can* access other
    global variables such as ``h``, ``app_globals`` and ``request``, as well as
    any variables explicitly passed into the snippet by the parent template when
    it calls the snippet with a ``{% snippet %}`` tag.
 
 
+-------------------------
 HTML tags and CSS classes
 -------------------------
 
@@ -651,7 +618,7 @@ groups look better by laying them out and styling them. Change your
    used the way it's being used here and as a result the CSS is wrong
    (also the template crashes unless you hack it).
 
-.. literalinclude:: ../ckanext/example_theme/v10_HTML_and_CSS/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v10_HTML_and_CSS/templates/home/index.html
 
 This new template uses `Bootstrap's grid system <http://getbootstrap.com/2.3.2/scaffolding.html#gridSystem>`_
 to layout the two main elements. Bootstrap's grid system lays out the main
@@ -691,336 +658,10 @@ associated titles::
 Change your ``snippets/example_theme_most_popular_groups.html`` template to
 look like this:
 
-.. literalinclude:: ../ckanext/example_theme/v10_HTML_and_CSS/templates/snippets/example_theme_most_popular_groups.html
+.. literalinclude:: /../ckanext/example_theme/v10_HTML_and_CSS/templates/snippets/example_theme_most_popular_groups.html
 
 This uses the same ``box`` and ``module-heading`` classes to draw a box around
 the most popular groups.
 
 Now reload your `CKAN front page`_ in your browser, you should see the activity
 stream and groups lists layed out and styled nicely.
-
-
-CKAN custom Jinja2 tags reference
----------------------------------
-
--------------------
-Adding static files
--------------------
-
-You may need to add some custom *static files* to your CKAN site and use them
-from your templates, for example image files, PDF files, or any other static
-files that should be returned as-is by the webserver (as opposed to Jinja
-template files, which CKAN renders before returning them to the user).
-
-By adding a directory to CKAN's :ref:`extra_public_paths` config setting,
-a plugin can make a directory of static files available to be used or linked to
-by templates. Let's add a static image file, and change the home page template
-to use our file as the promoted image on the front page.
-
-.. note::
-
-   If you're adding |javascript| or CSS files, consider using Fanstatic instead
-   of :ref:`extra_public_paths`, to take advantage of extra features.
-   See :ref:`fanstatic tutorial` below.
-
-First, create a ``public`` directory in your extension with a
-``promoted-image.jpg`` file in it::
-
- ckanext-example_theme/
-   public/
-     promoted-image.jpg
-
-``promoted-image.jpg`` should be a 420x220px JPEG image file. You could use
-this image file for example:
-
-.. image:: ../ckanext/example_theme/v11_extra_public_directory/public/promoted-image.jpg
-   :alt: An example promoted image
-   :height: 220px
-   :width: 420px
-
-Then in ``plugin.py``, register your ``public`` directory with CKAN by calling
-the :py:func:`~ckan.plugins.toolkit.add_public_directory` function. Add this
-line to the :py:func:`~ckan.ckanext.example_theme.v11_extra_public_directory.plugin.update_config`
-function:
-
-.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/plugin.py
-   :pyobject: ExampleThemePlugin.update_config
-
-If you now browse to `127.0.0.1:5000/promoted-image.jpg <http://127.0.0.1:5000/promoted-image.jpg>`_,
-you should see your image file.
-
-To replace the image on the front page with your custom image, we need to
-override the ``promoted.html`` template snippet. Create the following directory
-and file::
-
- ckanext-example_theme/
-   templates/
-     home/
-       snippets/
-         promoted.html
-
-Edit your new ``promoted.html`` snippet, and insert these contents:
-
-.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
-
-After calling ``{% ckan_extends %}`` to declare that it extends (rather than
-completely replaces) the default ``promoted.html`` snippet, this custom snippet
-overrides two of ``promoted.html``'s template blocks. The first block replaces
-the caption text of the promoted image. The second block replaces the ``<img>``
-tag itself, pointing it at our custom static image file:
-
-.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
-   :start-after: {# Replace the promoted image. #}
-
-If you now reload the `CKAN front page`_ in your browser, you should see the
-promoted image replaced with our custom one.
-
-
-----------------------
-Customizing CKAN's CSS
-----------------------
-
-Extensions can add their own CSS files to modify or extend CKAN's default CSS.
-Create an ``example_theme.css`` file in your extension's ``public`` directory::
-
-    ckanext-example_theme/
-      public/
-        example_theme.css
-
-Add this CSS into the ``example_theme.css`` file, to change the color of CKAN's
-"account masthead" (the bar across the top of the site that shows the logged-in
-user's account info):
-
-.. literalinclude:: ../ckanext/example_theme/v12_custom_css/public/example_theme.css
-
-If your restart the development web server (kill the server using Ctrl-c, then
-run the ``paster serve`` command again) you should be able to open this file at
-http://127.0.0.1:5000/example_theme.css in a web browser.
-
-To make CKAN use our custom CSS we need to override the ``base.html`` template,
-this is the base template which the templates for all CKAN pages extend, so if
-we include a CSS file in this base template then the file will be included in
-every page of your CKAN site. Create the file::
-
-    ckanext-example_theme/
-      templates/
-        base.html
-
-and put this Jinja code in it:
-
-.. literalinclude:: ../ckanext/example_theme/v12_custom_css/templates/base.html
-
-The default ``base.html`` template defines a ``styles`` block which can be
-extended to link to custom CSS files (any code in the styles block will appear
-in the ``<head>`` of the HTML page).
-
-Restart the development web server, and you should see the background color of
-the account masthead change. This custom color should appear on all pages of
-your CKAN site.
-
-Now that we have CKAN using our CSS file, we can add more CSS rules to the file
-and customize CKAN's CSS as much as we want. There's nothing special about CSS
-in CKAN, you just use the usual tools and techniques to explore and hack the
-CSS.
-
-.. todo:: Link to some tools?
-
-   e.g. Firefox inspector etc (or Chrome? Firebug?)
-
-   e.g. Some online CSS reference.
-
-Let's add a bit more code to our ``example_theme.css`` file. This CSS
-implements a partial imitation of the `datahub.io <http://datahub.io/>`_ theme
-(circa 2013):
-
-.. literalinclude:: ../ckanext/example_theme/v13_more_custom_css/public/example_theme.css
-
-.. todo::
-
-   We use LESS for the CKAN core CSS. Do we want to mention that here?
-
-
-.. _fanstatic tutorial:
-
-------------------------------------------------
-Adding |javascript| and CSS file using Fanstatic
-------------------------------------------------
-
-If you're adding |javascript| or CSS files to your theme, you can add them
-using `Fanstatic <http://www.fanstatic.org/>`_ rather than the simple
-:ref:`extra_public_paths` method described above (`JavaScript modules
-<javascript modules>`_ *must* be added using Fanstatic). Using Fanstatic to add
-|javascript| and CSS files allows you to take advantage of Fanstatic's
-features, such as automatically serving minified files in production, caching
-and bundling files together to reduce page load times, specifying dependencies
-between files so that the files a page needs (and only the files it needs) are
-always loaded, and other tricks to optimize page load times.
-
-.. note::
-
-   CKAN will only serve ``*.js`` and ``*.css`` files as Fanstatic resources,
-   other types of static files (eg. image files, PDF files) must be added
-   using the :ref:`extra_public_paths` method described above.
-
-Adding a custom |javascript| or CSS file to CKAN is using Fanstatic is simple:
-
-.. todo:: Turn this into a real working example.
-
-1. First, create a fanstatic directory in your extension with the CSS and
-   |javascript| files in it::
-
-    ckanext-example_theme/
-      fanstatic/
-        my_style.css
-        my_script.js
-
-2. Use CKAN's ``add_resource()`` function to register your fanstatic
-   directory with CKAN. Edit the ``update_config()`` method in your
-   ``plugin.py`` file::
-
-        def update_config(self, config):
-
-            # Add this plugin's templates dir to CKAN's extra_template_paths, so
-            # that CKAN will use this plugin's custom templates.
-            toolkit.add_template_directory(config, 'templates')
-
-            # Add this plugin's public dir to CKAN's extra_public_paths, so
-            # that CKAN will use this plugin's custom static files.
-            toolkit.add_public_directory(config, 'public')
-
-            toolkit.add_resource('fanstatic', 'example_theme')
-
-   The second argument to ``add_resource()``, ``'example_theme'``, is the name
-   that you'll need to use to refer to your custom Fanstatic library from
-   templates (you can pass whatever name you want here).
-
-3. Finally, use CKAN's custom Jinja2 tag ``{% resource %}`` to import the file
-   in the template that needs it::
-
-     {% resource 'example_theme/my_script.js' %}
-     {% resource 'example_theme/my_style.css' %}
-
-   You can put the ``{% resource %}`` tag anywhere in the template, and
-   Fanstatic will insert and necessary ``<style>`` and ``<script>`` tags to
-   include your |javascript| and CSS files and their dependencies in the right
-   places in the HTML output (CSS files in the HTML ``<head>``, |javascript|
-   files at the bottom of the page).
-
-.. todo:: Add a note about Fanstatic resource configuration file.
-
-Fanstatic resource troubleshooting
-==================================
-
-``AttributeError``
-------------------
-
-.. _javascript modules:
-
------------------------------
-Customizing CKAN's JavaScript
------------------------------
-
-.. todo:: Link to an introductory JavaScript tutorial.
-
-.. todo:: Introduce the example we're doing here: starring datasets using a
-     custom dataset_star action (also need the code to add this action).
-
-.. todo:: Explain that Bootstrap's JavaScript features can be used just by CSS.
-
-
-Initializing a JavaScript module
-================================
-
-To get CKAN to call some custom JavaScript code, we need to:
-
-1. Implement a |javascript| module, and register it with CKAN.
-   Create the file ``ckanext-example_theme/fanstatic/favorite.js``, with these
-   contents:
-
-   .. literalinclude:: ../ckanext/example_theme/v14_initialize_a_javascript_module/fanstatic/favorite.js
-
-   This bit of |javascript| calls the ``ckan.module()`` function to register a
-   new JavaScript module with CKAN. ``ckan.module()`` takes two arguments: the
-   name of the module being registered (``'favorite'`` in this example) and a
-   function that returns the module itself. The function takes two arguments,
-   which we'll look at later. The module is just a |javascript| object with a
-   single attribute, ``initialize``, whose value is a function that CKAN will
-   call to initialize the module. In this example, the initialize function just
-   prints out a confirmation message - this |javascript| module doesn't do
-   anything interesting yet.
-
-2. Include the |javascript| module in a page, using Fanstatic, and apply it to
-   one or more HTML elements on that page. We'll override CKAN's
-   ``package_item.html`` template snippet to insert our module whenever a
-   package is rendered as part of a list of packages (for example, on the
-   dataset search page). Create the file
-   ``ckanext-example_theme/templates/snippets/package_item.html`` with these
-   contents:
-
-   .. literalinclude:: ../ckanext/example_theme/v14_initialize_a_javascript_module/templates/snippets/package_item.html
-
-   .. todo:: Link to something about HTML data-* attributes.
-
-   If you now restart the development server and open
-   http://127.0.0.1:5000/dataset in your web browser, you should see an
-   extra "star this dataset" button next to each dataset shown. If you open a
-   |javascript| console in your browser, you should see the message that your
-   module has printed out.
-
-   .. todo:: Link to something about JavaScript consoles.
-
-   If you have more than one dataset on your page, you'll see the module's
-   message printed once for each dataset. The ``package_item.html`` template
-   snippet is rendered once for each dataset that's shown in the list, and
-   CKAN creates a new instance of your |javascript| module for each dataset.
-   If you view the source of your page, however, you'll see that
-   ``favorite.js`` is only included with a ``<script>`` tag once. Fanstatic
-   is smart enough to deduplicate resources.
-
-   .. note:: |javascript| modules *must* be included as Fanstatic resources,
-      you can't add them to a ``public`` directory and include them using your
-      own ``<script>`` tags.
-
-.. Link to some JavaScript tutorial?
-
-   JavaScript modules are the core - every javascripted object should be a
-   module. Small, isolated components that can be easily tested. They should
-   not use any global objects, all functionality provided to them via a sandbox
-   object.
-
-   A module is a JavaScript object with an initialize() and a teardown()
-   method.
-
-   Initialize a module with a data-module attribute:
-     <select name="format" data-module="autocomplete"></select>
-
-   Or apparently you can also use {% resource %}? Or you have to use resource?
-
-   "favorite" module goes in favorite.js file.
-
-   The idea is that the HTML element should still work fine is JavaScript is
-   disabled - e.g. use form submission instead of XHR request.
-
-   You can pass "options objects" with further data-module-* attributes.
-
-   The modules are initialized "on DOM ready", each module's initialize()
-   method is called.
-
-   this.sandbox.jQuery - access jQuery methods
-   this.sandbox.translte() - i18n
-   (or these are the jQuery and _ params of your module function)
-
-   pub/sub for sending messages between modules:
-   this.sandbox.publish/subscribe/unsubscribe
-
-   this.sandbox.client should be used to make XHR requests to the CKAN API
-   (not jQuery.ajax())
-
-   i18n: this.sandbox.translate(), supports %(name)s, including plurals.
-   The options() method of each module should set all strings to be i18n'd?
-   Then other code uses this.18n() to retrieve them.
-
-   If not CKAN specific, module functionality should be packaged up in jQuery
-   plugins.
-
-   Testing.
diff --git a/doc/upgrade-package-ckan-1-to-2.rst b/doc/upgrade-package-ckan-1-to-2.rst
index e7258ce93cf..c3071c30bf7 100644
--- a/doc/upgrade-package-ckan-1-to-2.rst
+++ b/doc/upgrade-package-ckan-1-to-2.rst
@@ -73,6 +73,6 @@ database and any custom configuration, extensions or templates to your new CKAN
 #. If you had any custom templates in your CKAN 1.x instance, these will need
    to be adapted before they can be used with CKAN 2.0. CKAN 2.0 introduces
    an entirely new template system based on Jinja2 rather than on Genshi.
-   See :doc:`theming` for details.
+   See :doc:`theming/index` for details.