Merge pull request #1067 from waylan/theme-docs

Document using theme_dir and template blocks togeather

docs/user-guide/styling-your-docs.md

@@ -94,9 +94,10 @@ theme.
 !!! Note
 
     For this to work, the `theme` setting must be set to a known installed theme.
-    If the `theme` settign is instead set to `null`, then there is no theme to
-    override and the contents of the `theme_dir` must be a complete, standalone
-    theme. See [Custom Themes][custom theme] for more information.
+    If the `theme` setting is instead set to `null` (or not defined), then there
+    is no theme to override and the contents of the `theme_dir` must be a
+    complete, standalone theme. See [Custom Themes][custom theme] for more
+    information.
 
 For example, the [mkdocs] theme ([browse source]), contains the following
 directory structure (in part):
@@ -206,6 +207,45 @@ work with the structure of the site. See [Template Variables] for a list of
 variables you can use within your custom blocks. For a more complete
 explaination of blocks, consult the [Jinja documentation].
 
+#### Combining the theme_dir and Template Blocks
+
+Adding a JavaScript library to the `theme_dir` will make it available, but
+won't include it in the pages generated by MkDocs. Therefore, a link needs to
+be added to the library from the HTML.
+
+Starting the with directory structure above (truncated):
+
+```nohighlight
+- docs/
+- custom_theme/
+  - js/
+    - somelib.js
+- config.yml
+```
+
+A link to the `custom_theme/js/somelib.js` file needs to be added to the
+template. As `somelib.js` is a JavaScript library, it would logically go in the
+`libs` block. However, a new `libs` block that only includes the new script will
+replace the block defined in the parent template and any links to libraries in
+the parent template will be removed. To avoid breaking the template, a
+[super block] can be used with a call to `super` from within the block:
+
+```django
+{% extends "base.html" %}
+
+{% block libs %}
+    {{ super() }}
+    <script src="{{ base_url }}/js/somelib.js"></script>
+{% endblock %}
+```
+
+Note that the [base_url] template variable was used to ensure that the link is
+always relative to the current page.
+
+Now the generated pages will include links to the template provided libraries as
+well as the library included in the `theme_dir`. The same would be required for
+any additional CSS files included in the `theme_dir`.
+
 [browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
 [built-in themes]: #built-in-themes
 [community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
@@ -222,3 +262,5 @@ explaination of blocks, consult the [Jinja documentation].
 [theme]: ./configuration/#theme
 [theme_dir]: ./configuration/#theme_dir
 [third party themes]: #third-party-themes
+[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
+[base_url]: ./custom-themes.md#base_url