Merge tag 'upstream/7.6.4'

Upstream version 7.6.4

1 files changed, 30 insertions, 8 deletions

diff --git a/docs/extending.txt b/docs/extending.txt
index 9db5344..bb94003 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 7.6.0
+:Version: 7.6.4
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -34,7 +34,9 @@ of Nikola.
 Command Plugins
 ---------------
 
-When you run ``nikola --help`` you will see something like this::
+When you run ``nikola --help`` you will see something like this:
+
+.. code-block:: console
 
     $ nikola help
     Nikola is a tool to create static websites and blogs. For full documentation and more
@@ -146,7 +148,9 @@ For your own plugin, just change the values in a sensible way. The
                 httpd.serve_forever()
 
 As mentioned above, a plugin can have options, which the user can see by doing
-``nikola help command`` and can later use, for example::
+``nikola help command`` and can later use, for example:
+
+.. code-block:: console
 
     $ nikola help serve
     Purpose: start the test webserver
@@ -242,6 +246,7 @@ a stub for a hypothetical system called "Templater":
             template search mechanism."""
             pass
 
+You can see a real example in `the Jinja plugin <https://github.com/getnikola/nikola/blob/master/nikola/plugins/template/jinja.py>`__
 
 Task Plugins
 ------------
@@ -257,7 +262,7 @@ T
     and ``TaskMultiplier`` plugins that take a task and create
     more tasks out of it.
 
-::
+.. code-block:: console
 
     $ nikola list
     Scanning posts....done!
@@ -361,7 +366,7 @@ PageCompiler Plugins
 --------------------
 
 These plugins implement markup languages, they take sources for posts or pages and
-create HTML or other output files. A good example is the ``misaka`` plugin.
+create HTML or other output files. A good example is `the misaka plugin. <https://github.com/getnikola/plugins/tree/master/v7/misaka>`__
 
 They must provide:
 
@@ -381,12 +386,27 @@ metadata contained in the file.
 RestExtension Plugins
 ---------------------
 
-Implement directives for reStructuredText, see ``media.py`` for a simple example.
+Implement directives for reStructuredText, see `media.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/media.py>`__ for a simple example.
+
+If your output depends on a config value, you need to make your post record a dependency on a pseudo-path, like this:
+
+.. code-block:: text
+
+    ####MAGIC####CONFIG:OPTIONNAME
+
+Then, whenever the ``OPTIONNAME`` option is changed in conf.py, the file will be rebuilt.
+
+If your directive depends or may depend on the whole timeline (like the post-list directive, where adding new posts
+to the site could make it stale), you should record a dependency on the
+pseudo-path ``####MAGIC####TIMELINE``.
 
 MarkdownExtension Plugins
 -------------------------
 
-Implement Markdown extensions, see ``mdx_nikola.py`` for a simple example.
+Implement Markdown extensions, see `mdx_nikola.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/markdown/mdx_nikola.py>`__ for a simple example.
+
+Note that python markdown extensions are often also available as separate packages. This is only meant to ship extensions
+along with Nikola.
 
 SignalHandler Plugins
 ---------------------
@@ -424,13 +444,15 @@ Currently Nikola emits the following signals:
          'undeployed': # all files not deployed since they are either future posts/drafts
         }
 
+One example is the `deploy_hooks plugin. <https://github.com/getnikola/plugins/tree/master/v6/deploy_hooks>`__
+
 ConfigPlugin Plugins
 --------------------
 
 Does nothing specific, can be used to modify the site object (and thus the config).
 
 Put all the magic you want in ``set_site()``, and don’t forget to run the one
-from ``super()``.
+from ``super()``. Example  plugin: `navstories <https://github.com/getnikola/plugins/tree/master/v7/navstories>`__
 
 PostScanner Plugins
 -------------------