diff options
Diffstat (limited to 'docs/extending.txt')
| -rw-r--r-- | docs/extending.txt | 38 |
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 ------------------- |