A new Riff-radio.org site with a static approach.

extending.html 74KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668
  1. <dl class="docinfo simple">
  2. <dt class="version">Version<span class="colon">:</span></dt>
  3. <dd class="version">8.2.3</dd>
  4. <dt class="author">Author<span class="colon">:</span></dt>
  5. <dd class="author"><p>Roberto Alsina &lt;<a class="reference external" href="mailto:ralsina&#64;netmanagers.com.ar">ralsina&#64;netmanagers.com.ar</a>&gt;</p></dd>
  6. </dl>
  7. <nav class="contents alert alert-primary float-md-right" id="contents" role="doc-toc">
  8. <p class="topic-title">Contents</p>
  9. <ul class="simple">
  10. <li><p><a class="reference internal" href="#available-plugin-categories" id="toc-entry-1">Available Plugin Categories</a></p>
  11. <ul>
  12. <li><p><a class="reference internal" href="#command-plugins" id="toc-entry-2">Command Plugins</a></p></li>
  13. <li><p><a class="reference internal" href="#templatesystem-plugins" id="toc-entry-3">TemplateSystem Plugins</a></p></li>
  14. <li><p><a class="reference internal" href="#task-plugins" id="toc-entry-4">Task Plugins</a></p></li>
  15. <li><p><a class="reference internal" href="#pagecompiler-plugins" id="toc-entry-5">PageCompiler Plugins</a></p></li>
  16. <li><p><a class="reference internal" href="#metadataextractor-plugins" id="toc-entry-6">MetadataExtractor Plugins</a></p></li>
  17. <li><p><a class="reference internal" href="#restextension-plugins" id="toc-entry-7">RestExtension Plugins</a></p></li>
  18. <li><p><a class="reference internal" href="#markdownextension-plugins" id="toc-entry-8">MarkdownExtension Plugins</a></p></li>
  19. <li><p><a class="reference internal" href="#signalhandler-plugins" id="toc-entry-9">SignalHandler Plugins</a></p></li>
  20. <li><p><a class="reference internal" href="#configplugin-plugins" id="toc-entry-10">ConfigPlugin Plugins</a></p></li>
  21. <li><p><a class="reference internal" href="#commentsystem-plugins" id="toc-entry-11">CommentSystem Plugins</a></p></li>
  22. <li><p><a class="reference internal" href="#shortcode-plugins" id="toc-entry-12">Shortcode Plugins</a></p></li>
  23. <li><p><a class="reference internal" href="#postscanner-plugins" id="toc-entry-13">PostScanner Plugins</a></p></li>
  24. </ul>
  25. </li>
  26. <li><p><a class="reference internal" href="#plugin-index" id="toc-entry-14">Plugin Index</a></p></li>
  27. <li><p><a class="reference internal" href="#path-link-resolution-mechanism" id="toc-entry-15">Path/Link Resolution Mechanism</a></p></li>
  28. <li><p><a class="reference internal" href="#template-hooks" id="toc-entry-16">Template Hooks</a></p></li>
  29. <li><p><a class="reference internal" href="#shortcodes" id="toc-entry-17">Shortcodes</a></p>
  30. <ul>
  31. <li><p><a class="reference internal" href="#template-based-shortcodes" id="toc-entry-18">Template-based Shortcodes</a></p></li>
  32. </ul>
  33. </li>
  34. <li><p><a class="reference internal" href="#state-and-cache" id="toc-entry-19">State and Cache</a></p></li>
  35. <li><p><a class="reference internal" href="#logging" id="toc-entry-20">Logging</a></p></li>
  36. <li><p><a class="reference internal" href="#template-and-dependency-injection" id="toc-entry-21">Template and Dependency Injection</a></p></li>
  37. </ul>
  38. </nav>
  39. <p class="lead">Nikola is extensible. Almost all its functionality is based on plugins,
  40. and you can add your own or replace the provided ones.</p>
  41. <p>Plugins consist of a metadata file (with <code class="docutils literal">.plugin</code> extension) and
  42. a Python module (a <code class="docutils literal">.py</code> file) or package (a folder containing
  43. a <code class="docutils literal">__init__.py</code> file.</p>
  44. <p>To use a plugin in your site, you just have to put it in a <code class="docutils literal">plugins</code>
  45. folder in your site.</p>
  46. <p>Plugins come in various flavours, aimed at extending different aspects
  47. of Nikola.</p>
  48. <section id="available-plugin-categories">
  49. <h1><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Available Plugin Categories</a></h1>
  50. <section id="command-plugins">
  51. <h2><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Command Plugins</a></h2>
  52. <p>When you run <code class="docutils literal">nikola <span class="pre">--help</span></code> you will see something like this:</p>
  53. <pre class="code console"><a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-1"></a><span class="gp">$</span> nikola <span class="nb">help</span>
  54. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-2"></a><span class="go">Nikola is a tool to create static websites and blogs. For full documentation and more</span>
  55. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-3"></a><span class="go">information, please visit https://getnikola.com/</span>
  56. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-4"></a>
  57. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-5"></a>
  58. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-6"></a><span class="go">Available commands:</span>
  59. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-7"></a><span class="go">nikola auto automatically detect site changes, rebuild</span>
  60. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-8"></a><span class="go"> and optionally refresh a browser</span>
  61. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-9"></a><span class="go">nikola bootswatch_theme given a swatch name from bootswatch.com and a</span>
  62. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-10"></a><span class="go"> parent theme, creates a custom theme</span>
  63. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-11"></a><span class="go">nikola build run tasks</span>
  64. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-12"></a><span class="go">nikola check check links and files in the generated site</span>
  65. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-13"></a><span class="go">nikola clean clean action / remove targets</span>
  66. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-14"></a><span class="go">nikola console start an interactive python console with access to</span>
  67. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-15"></a><span class="go"> your site and configuration</span>
  68. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-16"></a><span class="go">nikola deploy deploy the site</span>
  69. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-17"></a><span class="go">nikola dumpdb dump dependency DB</span>
  70. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-18"></a><span class="go">nikola forget clear successful run status from internal DB</span>
  71. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-19"></a><span class="go">nikola help show help</span>
  72. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-20"></a><span class="go">nikola ignore ignore task (skip) on subsequent runs</span>
  73. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-21"></a><span class="go">nikola import_blogger import a blogger dump</span>
  74. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-22"></a><span class="go">nikola import_feed import a RSS/Atom dump</span>
  75. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-23"></a><span class="go">nikola import_wordpress import a WordPress dump</span>
  76. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-24"></a><span class="go">nikola init create a Nikola site in the specified folder</span>
  77. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-25"></a><span class="go">nikola list list tasks from dodo file</span>
  78. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-26"></a><span class="go">nikola mincss apply mincss to the generated site</span>
  79. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-27"></a><span class="go">nikola new_post create a new blog post or site page</span>
  80. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-28"></a><span class="go">nikola run run tasks</span>
  81. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-29"></a><span class="go">nikola serve start the test webserver</span>
  82. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-30"></a><span class="go">nikola strace use strace to list file_deps and targets</span>
  83. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-31"></a><span class="go">nikola theme manage themes</span>
  84. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-32"></a><span class="go">nikola version print the Nikola version number</span>
  85. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-33"></a>
  86. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-34"></a><span class="go">nikola help show help / reference</span>
  87. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-35"></a><span class="go">nikola help &lt;command&gt; show command usage</span>
  88. <a name="rest_code_6fc228dc86544900b3254eb5bab7e47e-36"></a><span class="go">nikola help &lt;task-name&gt; show task usage</span>
  89. </pre><p>That will give you a list of all available commands in your version of Nikola.
  90. Each and every one of those is a plugin. Let's look at a typical example:</p>
  91. <p>First, the <code class="docutils literal">serve.plugin</code> file:</p>
  92. <pre class="code ini"><a name="rest_code_ba62f591ee56474b8dad401ec415b819-1"></a><span class="k">[Core]</span>
  93. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-2"></a><span class="na">Name</span> <span class="o">=</span> <span class="s">serve</span>
  94. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-3"></a><span class="na">Module</span> <span class="o">=</span> <span class="s">serve</span>
  95. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-4"></a>
  96. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-5"></a><span class="k">[Documentation]</span>
  97. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-6"></a><span class="na">Author</span> <span class="o">=</span> <span class="s">Roberto Alsina</span>
  98. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-7"></a><span class="na">Version</span> <span class="o">=</span> <span class="s">0.1</span>
  99. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-8"></a><span class="na">Website</span> <span class="o">=</span> <span class="s">https://getnikola.com</span>
  100. <a name="rest_code_ba62f591ee56474b8dad401ec415b819-9"></a><span class="na">Description</span> <span class="o">=</span> <span class="s">Start test server.</span>
  101. </pre><aside class="admonition note">
  102. <p class="admonition-title">Note</p>
  103. <p>If you want to publish your plugin on the Plugin Index, <a class="reference external" href="https://github.com/getnikola/plugins/blob/master/README.md">read
  104. the docs for the Index</a>
  105. (and the .plugin file examples and explanations).</p>
  106. </aside>
  107. <p>For your own plugin, just change the values in a sensible way. The
  108. <code class="docutils literal">Module</code> will be used to find the matching Python module, in this case
  109. <code class="docutils literal">serve.py</code>, from which this is the interesting bit:</p>
  110. <pre class="code python"><a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-1"></a><span class="kn">from</span> <span class="nn">nikola.plugin_categories</span> <span class="kn">import</span> <span class="n">Command</span>
  111. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-2"></a>
  112. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-3"></a><span class="c1"># You have to inherit Command for this to be a</span>
  113. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-4"></a><span class="c1"># command plugin:</span>
  114. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-5"></a>
  115. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-6"></a><span class="k">class</span> <span class="nc">CommandServe</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
  116. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-7"></a> <span class="sd">&quot;&quot;&quot;Start test server.&quot;&quot;&quot;</span>
  117. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-8"></a>
  118. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-9"></a> <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;serve&quot;</span>
  119. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-10"></a> <span class="n">doc_usage</span> <span class="o">=</span> <span class="s2">&quot;[options]&quot;</span>
  120. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-11"></a> <span class="n">doc_purpose</span> <span class="o">=</span> <span class="s2">&quot;start the test webserver&quot;</span>
  121. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-12"></a>
  122. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-13"></a> <span class="n">cmd_options</span> <span class="o">=</span> <span class="p">(</span>
  123. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-14"></a> <span class="p">{</span>
  124. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-15"></a> <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;port&#39;</span><span class="p">,</span>
  125. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-16"></a> <span class="s1">&#39;short&#39;</span><span class="p">:</span> <span class="s1">&#39;p&#39;</span><span class="p">,</span>
  126. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-17"></a> <span class="s1">&#39;long&#39;</span><span class="p">:</span> <span class="s1">&#39;port&#39;</span><span class="p">,</span>
  127. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-18"></a> <span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="mi">8000</span><span class="p">,</span>
  128. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-19"></a> <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
  129. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-20"></a> <span class="s1">&#39;help&#39;</span><span class="p">:</span> <span class="s1">&#39;Port number&#39;</span><span class="p">,</span>
  130. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-21"></a> <span class="p">},</span>
  131. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-22"></a> <span class="p">{</span>
  132. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-23"></a> <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;address&#39;</span><span class="p">,</span>
  133. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-24"></a> <span class="s1">&#39;short&#39;</span><span class="p">:</span> <span class="s1">&#39;a&#39;</span><span class="p">,</span>
  134. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-25"></a> <span class="s1">&#39;long&#39;</span><span class="p">:</span> <span class="s1">&#39;--address&#39;</span><span class="p">,</span>
  135. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-26"></a> <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
  136. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-27"></a> <span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="s1">&#39;127.0.0.1&#39;</span><span class="p">,</span>
  137. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-28"></a> <span class="s1">&#39;help&#39;</span><span class="p">:</span> <span class="s1">&#39;Address to bind&#39;</span><span class="p">,</span>
  138. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-29"></a> <span class="p">},</span>
  139. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-30"></a> <span class="p">)</span>
  140. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-31"></a>
  141. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-32"></a> <span class="k">def</span> <span class="nf">_execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
  142. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-33"></a> <span class="sd">&quot;&quot;&quot;Start test server.&quot;&quot;&quot;</span>
  143. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-34"></a> <span class="n">out_dir</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;OUTPUT_FOLDER&#39;</span><span class="p">]</span>
  144. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-35"></a> <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isdir</span><span class="p">(</span><span class="n">out_dir</span><span class="p">):</span>
  145. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-36"></a> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Error: Missing &#39;</span><span class="si">{0}</span><span class="s2">&#39; folder?&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">out_dir</span><span class="p">))</span>
  146. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-37"></a> <span class="k">return</span> <span class="mi">1</span> <span class="c1"># Exit code on failure. (return 0 not necessary)</span>
  147. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-38"></a> <span class="k">else</span><span class="p">:</span>
  148. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-39"></a> <span class="n">os</span><span class="o">.</span><span class="n">chdir</span><span class="p">(</span><span class="n">out_dir</span><span class="p">)</span>
  149. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-40"></a> <span class="n">httpd</span> <span class="o">=</span> <span class="n">HTTPServer</span><span class="p">((</span><span class="n">options</span><span class="p">[</span><span class="s1">&#39;address&#39;</span><span class="p">],</span> <span class="n">options</span><span class="p">[</span><span class="s1">&#39;port&#39;</span><span class="p">]),</span>
  150. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-41"></a> <span class="n">OurHTTPRequestHandler</span><span class="p">)</span>
  151. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-42"></a> <span class="n">sa</span> <span class="o">=</span> <span class="n">httpd</span><span class="o">.</span><span class="n">socket</span><span class="o">.</span><span class="n">getsockname</span><span class="p">()</span>
  152. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-43"></a> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Serving HTTP on&quot;</span><span class="p">,</span> <span class="n">sa</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="s2">&quot;port&quot;</span><span class="p">,</span> <span class="n">sa</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="s2">&quot;...&quot;</span><span class="p">)</span>
  153. <a name="rest_code_e3a6b6d51a3347a7adb07cea08cec1b1-44"></a> <span class="n">httpd</span><span class="o">.</span><span class="n">serve_forever</span><span class="p">()</span>
  154. </pre><p>As mentioned above, a plugin can have options, which the user can see by doing
  155. <code class="docutils literal">nikola help command</code> and can later use, for example:</p>
  156. <pre class="code console"><a name="rest_code_3c9de002787e43998e18ec2797969dbc-1"></a><span class="gp">$</span> nikola <span class="nb">help</span> serve
  157. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-2"></a><span class="go">nikola serve [options]</span>
  158. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-3"></a><span class="go">start the test webserver</span>
  159. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-4"></a>
  160. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-5"></a><span class="go">Options:</span>
  161. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-6"></a><span class="go"> -p ARG, --port=ARG</span>
  162. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-7"></a><span class="go"> Port number [default: 8000]</span>
  163. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-8"></a><span class="go"> -a ARG, --address=ARG</span>
  164. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-9"></a><span class="go"> Address to bind [default: 127.0.0.1]</span>
  165. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-10"></a>
  166. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-11"></a><span class="gp">$</span> nikola serve -p <span class="m">9000</span>
  167. <a name="rest_code_3c9de002787e43998e18ec2797969dbc-12"></a><span class="go">Serving HTTP on 127.0.0.1 port 9000 ...</span>
  168. </pre><p>So, what can you do with commands? Well, anything you want, really. I have implemented
  169. a sort of planet using it. So, be creative, and if you do something interesting,
  170. let me know ;-)</p>
  171. </section>
  172. <section id="templatesystem-plugins">
  173. <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">TemplateSystem Plugins</a></h2>
  174. <p>Nikola supports Mako and Jinja2. If you prefer some other templating
  175. system, then you will have to write a <code class="docutils literal">TemplateSystem</code> plugin. Here's how they work.
  176. First, you have to create a <code class="docutils literal">.plugin</code> file. Here's the one for the Mako plugin:</p>
  177. <pre class="code ini"><a name="rest_code_c5c3f7f326704b998816809be8814ef2-1"></a><span class="k">[Core]</span>
  178. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-2"></a><span class="na">Name</span> <span class="o">=</span> <span class="s">mako</span>
  179. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-3"></a><span class="na">Module</span> <span class="o">=</span> <span class="s">mako</span>
  180. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-4"></a>
  181. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-5"></a><span class="k">[Documentation]</span>
  182. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-6"></a><span class="na">Author</span> <span class="o">=</span> <span class="s">Roberto Alsina</span>
  183. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-7"></a><span class="na">Version</span> <span class="o">=</span> <span class="s">0.1</span>
  184. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-8"></a><span class="na">Website</span> <span class="o">=</span> <span class="s">https://getnikola.com</span>
  185. <a name="rest_code_c5c3f7f326704b998816809be8814ef2-9"></a><span class="na">Description</span> <span class="o">=</span> <span class="s">Support for Mako templates.</span>
  186. </pre><aside class="admonition note">
  187. <p class="admonition-title">Note</p>
  188. <p>If you want to publish your plugin on the Plugin Index, <a class="reference external" href="https://github.com/getnikola/plugins/blob/master/README.md">read
  189. the docs for the Index</a>
  190. (and the .plugin file examples and explanations).</p>
  191. </aside>
  192. <p>You will have to replace &quot;mako&quot; with your template system's name, and other data
  193. in the obvious ways.</p>
  194. <p>The &quot;Module&quot; option is the name of the module, which has to look something like this,
  195. a stub for a hypothetical system called &quot;Templater&quot;:</p>
  196. <pre class="code python"><a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-1"></a><span class="kn">from</span> <span class="nn">nikola.plugin_categories</span> <span class="kn">import</span> <span class="n">TemplateSystem</span>
  197. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-2"></a>
  198. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-3"></a><span class="c1"># You have to inherit TemplateSystem</span>
  199. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-4"></a>
  200. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-5"></a><span class="k">class</span> <span class="nc">TemplaterTemplates</span><span class="p">(</span><span class="n">TemplateSystem</span><span class="p">):</span>
  201. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-6"></a> <span class="sd">&quot;&quot;&quot;Wrapper for Templater templates.&quot;&quot;&quot;</span>
  202. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-7"></a>
  203. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-8"></a> <span class="c1"># name has to match Name in the .plugin file</span>
  204. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-9"></a> <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;templater&quot;</span>
  205. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-10"></a>
  206. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-11"></a> <span class="c1"># A list of directories where the templates will be</span>
  207. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-12"></a> <span class="c1"># located. Most template systems have some sort of</span>
  208. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-13"></a> <span class="c1"># template loading tool that can use this.</span>
  209. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-14"></a> <span class="k">def</span> <span class="nf">set_directories</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">directories</span><span class="p">,</span> <span class="n">cache_folder</span><span class="p">):</span>
  210. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-15"></a> <span class="sd">&quot;&quot;&quot;Sets the list of folders where templates are located and cache.&quot;&quot;&quot;</span>
  211. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-16"></a> <span class="k">pass</span>
  212. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-17"></a>
  213. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-18"></a> <span class="c1"># You *must* implement this, even if to return []</span>
  214. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-19"></a> <span class="c1"># It should return a list of all the files that,</span>
  215. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-20"></a> <span class="c1"># when changed, may affect the template&#39;s output.</span>
  216. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-21"></a> <span class="c1"># usually this involves template inheritance and</span>
  217. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-22"></a> <span class="c1"># inclusion.</span>
  218. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-23"></a> <span class="k">def</span> <span class="nf">template_deps</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">template_name</span><span class="p">):</span>
  219. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-24"></a> <span class="sd">&quot;&quot;&quot;Returns filenames which are dependencies for a template.&quot;&quot;&quot;</span>
  220. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-25"></a> <span class="k">return</span> <span class="p">[]</span>
  221. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-26"></a>
  222. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-27"></a> <span class="k">def</span> <span class="nf">render_template</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">template_name</span><span class="p">,</span> <span class="n">output_name</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
  223. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-28"></a> <span class="sd">&quot;&quot;&quot;Renders template to a file using context.</span>
  224. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-29"></a>
  225. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-30"></a><span class="sd"> This must save the data to output_name *and* return it</span>
  226. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-31"></a><span class="sd"> so that the caller may do additional processing.</span>
  227. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-32"></a><span class="sd"> &quot;&quot;&quot;</span>
  228. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-33"></a> <span class="k">pass</span>
  229. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-34"></a>
  230. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-35"></a> <span class="c1"># The method that does the actual rendering.</span>
  231. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-36"></a> <span class="c1"># template_name is the name of the template file,</span>
  232. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-37"></a> <span class="c1"># context is a dictionary containing the data the template</span>
  233. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-38"></a> <span class="c1"># uses for rendering.</span>
  234. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-39"></a> <span class="k">def</span> <span class="nf">render_template_to_string</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">template</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
  235. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-40"></a> <span class="sd">&quot;&quot;&quot;Renders template to a string using context. &quot;&quot;&quot;</span>
  236. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-41"></a> <span class="k">pass</span>
  237. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-42"></a>
  238. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-43"></a> <span class="k">def</span> <span class="nf">inject_directory</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">directory</span><span class="p">):</span>
  239. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-44"></a> <span class="sd">&quot;&quot;&quot;Injects the directory with the lowest priority in the</span>
  240. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-45"></a><span class="sd"> template search mechanism.&quot;&quot;&quot;</span>
  241. <a name="rest_code_5a519bdb6ea7424d9da26e9afd8e3eba-46"></a> <span class="k">pass</span>
  242. </pre><p>You can see a real example in <a class="reference external" href="https://github.com/getnikola/nikola/blob/master/nikola/plugins/template/jinja.py">the Jinja plugin</a></p>
  243. </section>
  244. <section id="task-plugins">
  245. <h2><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Task Plugins</a></h2>
  246. <p>If you want to do something that depends on the data in your site, you
  247. probably want to do a <code class="docutils literal">Task</code> plugin, which will make it be part of the
  248. <code class="docutils literal">nikola build</code> command. These are the currently available tasks, all
  249. provided by plugins:</p>
  250. <aside class="sidebar">
  251. <p class="sidebar-title">Other Tasks</p>
  252. <p>There are also <code class="docutils literal">LateTask</code> plugins, which are executed later,
  253. and <code class="docutils literal">TaskMultiplier</code> plugins that take a task and create
  254. more tasks out of it.</p>
  255. </aside>
  256. <pre class="code console"><a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-1"></a><span class="gp">$</span> nikola list
  257. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-2"></a><span class="go">Scanning posts....done!</span>
  258. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-3"></a><span class="go">copy_assets</span>
  259. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-4"></a><span class="go">copy_files</span>
  260. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-5"></a><span class="go">create_bundles</span>
  261. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-6"></a><span class="go">post_render</span>
  262. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-7"></a><span class="go">redirect</span>
  263. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-8"></a><span class="go">render_galleries</span>
  264. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-9"></a><span class="go">render_listings</span>
  265. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-10"></a><span class="go">render_pages</span>
  266. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-11"></a><span class="go">render_posts</span>
  267. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-12"></a><span class="go">render_site</span>
  268. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-13"></a><span class="go">render_sources</span>
  269. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-14"></a><span class="go">render_taxonomies</span>
  270. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-15"></a><span class="go">robots_file</span>
  271. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-16"></a><span class="go">scale_images</span>
  272. <a name="rest_code_fc9ffb7c69224daeb0a3e5d7b2feb52d-17"></a><span class="go">sitemap</span>
  273. </pre><p>These have access to the <code class="docutils literal">site</code> object which contains your timeline and
  274. your configuration.</p>
  275. <p>The critical bit of Task plugins is their <code class="docutils literal">gen_tasks</code> method, which <code class="docutils literal">yields</code>
  276. <a class="reference external" href="https://pydoit.org/tasks.html">doit tasks</a>.</p>
  277. <p>The details of how to handle dependencies, etc., are a bit too much for this
  278. document, so I'll just leave you with an example, the <code class="docutils literal">copy_assets</code> task.
  279. First the <code class="docutils literal">task_copy_assets.plugin</code> file, which you should copy and edit
  280. in the logical ways:</p>
  281. <pre class="code ini"><a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-1"></a><span class="k">[Core]</span>
  282. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-2"></a><span class="na">Name</span> <span class="o">=</span> <span class="s">copy_assets</span>
  283. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-3"></a><span class="na">Module</span> <span class="o">=</span> <span class="s">task_copy_assets</span>
  284. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-4"></a>
  285. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-5"></a><span class="k">[Documentation]</span>
  286. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-6"></a><span class="na">Author</span> <span class="o">=</span> <span class="s">Roberto Alsina</span>
  287. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-7"></a><span class="na">Version</span> <span class="o">=</span> <span class="s">0.1</span>
  288. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-8"></a><span class="na">Website</span> <span class="o">=</span> <span class="s">https://getnikola.com</span>
  289. <a name="rest_code_8abe88df87fb424cbe0e5131ed77debd-9"></a><span class="na">Description</span> <span class="o">=</span> <span class="s">Copy theme assets into output.</span>
  290. </pre><aside class="admonition note">
  291. <p class="admonition-title">Note</p>
  292. <p>If you want to publish your plugin on the Plugin Index, <a class="reference external" href="https://github.com/getnikola/plugins/blob/master/README.md">read
  293. the docs for the Index</a>
  294. (and the .plugin file examples and explanations).</p>
  295. </aside>
  296. <p>And the <code class="docutils literal">task_copy_assets.py</code> file, in its entirety:</p>
  297. <pre class="code python"><a name="rest_code_c033780b5b47427f9b622b01c7471f12-1"></a><span class="kn">import</span> <span class="nn">os</span>
  298. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-2"></a>
  299. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-3"></a><span class="kn">from</span> <span class="nn">nikola.plugin_categories</span> <span class="kn">import</span> <span class="n">Task</span>
  300. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-4"></a><span class="kn">from</span> <span class="nn">nikola</span> <span class="kn">import</span> <span class="n">utils</span>
  301. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-5"></a>
  302. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-6"></a><span class="c1"># Have to inherit Task to be a task plugin</span>
  303. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-7"></a><span class="k">class</span> <span class="nc">CopyAssets</span><span class="p">(</span><span class="n">Task</span><span class="p">):</span>
  304. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-8"></a> <span class="sd">&quot;&quot;&quot;Copy theme assets into output.&quot;&quot;&quot;</span>
  305. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-9"></a>
  306. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-10"></a> <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;copy_assets&quot;</span>
  307. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-11"></a>
  308. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-12"></a> <span class="c1"># This yields the tasks</span>
  309. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-13"></a> <span class="k">def</span> <span class="nf">gen_tasks</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
  310. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-14"></a> <span class="sd">&quot;&quot;&quot;Create tasks to copy the assets of the whole theme chain.</span>
  311. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-15"></a>
  312. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-16"></a><span class="sd"> If a file is present on two themes, use the version</span>
  313. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-17"></a><span class="sd"> from the &quot;youngest&quot; theme.</span>
  314. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-18"></a><span class="sd"> &quot;&quot;&quot;</span>
  315. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-19"></a>
  316. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-20"></a> <span class="c1"># I put all the configurations and data the plugin uses</span>
  317. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-21"></a> <span class="c1"># in a dictionary because utils.config_changed will</span>
  318. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-22"></a> <span class="c1"># make it so that if these change, this task will be</span>
  319. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-23"></a> <span class="c1"># marked out of date, and run again.</span>
  320. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-24"></a>
  321. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-25"></a> <span class="n">kw</span> <span class="o">=</span> <span class="p">{</span>
  322. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-26"></a> <span class="s2">&quot;themes&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">THEMES</span><span class="p">,</span>
  323. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-27"></a> <span class="s2">&quot;output_folder&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;OUTPUT_FOLDER&#39;</span><span class="p">],</span>
  324. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-28"></a> <span class="s2">&quot;filters&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;FILTERS&#39;</span><span class="p">],</span>
  325. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-29"></a> <span class="p">}</span>
  326. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-30"></a>
  327. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-31"></a> <span class="n">tasks</span> <span class="o">=</span> <span class="p">{}</span>
  328. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-32"></a> <span class="k">for</span> <span class="n">theme_name</span> <span class="ow">in</span> <span class="n">kw</span><span class="p">[</span><span class="s1">&#39;themes&#39;</span><span class="p">]:</span>
  329. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-33"></a> <span class="n">src</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">utils</span><span class="o">.</span><span class="n">get_theme_path</span><span class="p">(</span><span class="n">theme_name</span><span class="p">),</span> <span class="s1">&#39;assets&#39;</span><span class="p">)</span>
  330. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-34"></a> <span class="n">dst</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">kw</span><span class="p">[</span><span class="s1">&#39;output_folder&#39;</span><span class="p">],</span> <span class="s1">&#39;assets&#39;</span><span class="p">)</span>
  331. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-35"></a> <span class="k">for</span> <span class="n">task</span> <span class="ow">in</span> <span class="n">utils</span><span class="o">.</span><span class="n">copy_tree</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span>
  332. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-36"></a> <span class="k">if</span> <span class="n">task</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span> <span class="ow">in</span> <span class="n">tasks</span><span class="p">:</span>
  333. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-37"></a> <span class="k">continue</span>
  334. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-38"></a> <span class="n">tasks</span><span class="p">[</span><span class="n">task</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]]</span> <span class="o">=</span> <span class="n">task</span>
  335. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-39"></a> <span class="n">task</span><span class="p">[</span><span class="s1">&#39;uptodate&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">task</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;uptodate&#39;</span><span class="p">,</span> <span class="p">[])</span> <span class="o">+</span> \
  336. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-40"></a> <span class="p">[</span><span class="n">utils</span><span class="o">.</span><span class="n">config_changed</span><span class="p">(</span><span class="n">kw</span><span class="p">)]</span>
  337. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-41"></a> <span class="n">task</span><span class="p">[</span><span class="s1">&#39;basename&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>
  338. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-42"></a> <span class="c1"># If your task generates files, please do this.</span>
  339. <a name="rest_code_c033780b5b47427f9b622b01c7471f12-43"></a> <span class="k">yield</span> <span class="n">utils</span><span class="o">.</span><span class="n">apply_filters</span><span class="p">(</span><span class="n">task</span><span class="p">,</span> <span class="n">kw</span><span class="p">[</span><span class="s1">&#39;filters&#39;</span><span class="p">])</span>
  340. </pre></section>
  341. <section id="pagecompiler-plugins">
  342. <h2><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">PageCompiler Plugins</a></h2>
  343. <p>These plugins implement markup languages, they take sources for posts or pages and
  344. create HTML or other output files. A good example is <a class="reference external" href="https://github.com/getnikola/plugins/tree/master/v8/misaka">the misaka plugin</a> or the built-in
  345. compiler plugins.</p>
  346. <p>They must provide:</p>
  347. <dl class="simple">
  348. <dt><code class="docutils literal">compile</code></dt>
  349. <dd><p>Function that builds a file.</p>
  350. </dd>
  351. <dt><code class="docutils literal">create_post</code></dt>
  352. <dd><p>Function that creates an empty file with some metadata in it.</p>
  353. </dd>
  354. </dl>
  355. <p>If the compiler produces something other than HTML files, it should also implement <code class="docutils literal">extension</code> which
  356. returns the preferred extension for the output file.</p>
  357. <p>These plugins can also be used to extract metadata from a file. To do so, the
  358. plugin must set <code class="docutils literal">supports_metadata</code> to <code class="docutils literal">True</code> and implement <code class="docutils literal">read_metadata</code> that will return a dict containing the
  359. metadata contained in the file. Optionally, it may list <code class="docutils literal">metadata_conditions</code> (see <a class="reference internal" href="#metadataextractor-plugins">MetadataExtractor Plugins</a> below)</p>
  360. </section>
  361. <section id="metadataextractor-plugins">
  362. <h2><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">MetadataExtractor Plugins</a></h2>
  363. <p>Plugins that extract metadata from posts. If they are based on post content,
  364. they must implement <code class="docutils literal">_extract_metadata_from_text</code> (takes source of a post
  365. returns a dict of metadata). They may also implement
  366. <code class="docutils literal">split_metadata_from_text</code>, <code class="docutils literal">extract_text</code>. If they are based on filenames,
  367. they only need <code class="docutils literal">extract_filename</code>. If <code class="docutils literal">support_write</code> is set to True,
  368. <code class="docutils literal">write_metadata</code> must be implemented.</p>
  369. <p>Every extractor must be configured properly. The <code class="docutils literal">name</code>, <code class="docutils literal">source</code> (from the
  370. <code class="docutils literal">MetaSource</code> enum in <code class="docutils literal">metadata_extractors</code>) and <code class="docutils literal">priority</code>
  371. (<code class="docutils literal">MetaPriority</code>) fields are mandatory. There might also be a list of
  372. <code class="docutils literal">conditions</code> (tuples of <code class="docutils literal">MetaCondition, arg</code>), used to check if an
  373. extractor can provide metadata, a compiled regular expression used to split
  374. metadata (<code class="docutils literal">split_metadata_re</code>, may be <code class="docutils literal">None</code>, used by default
  375. <code class="docutils literal">split_metadata_from_text</code>), a list of <code class="docutils literal">requirements</code> (3-tuples: import
  376. name, pip name, friendly name), <code class="docutils literal">map_from</code> (name of <code class="docutils literal">METADATA_MAPPING</code> to
  377. use, if any) and <code class="docutils literal">supports_write</code> (whether the extractor supports writing
  378. metadata in the desired format).</p>
  379. <p>For more details, see the definition in <code class="docutils literal">plugin_categories.py</code> and default extractors in <code class="docutils literal">metadata_extractors.py</code>.</p>
  380. </section>
  381. <section id="restextension-plugins">
  382. <h2><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">RestExtension Plugins</a></h2>
  383. <p>Implement directives for reStructuredText, see <a class="reference external" href="https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/media.py">media.py</a> for a simple example.</p>
  384. <p>If your output depends on a config value, you need to make your post record a
  385. dependency on a pseudo-path, like this:</p>
  386. <pre class="code text"><a name="rest_code_9ac74e87bd9840bcb263f3d32ac5ffc4-1"></a>####MAGIC####CONFIG:OPTIONNAME
  387. </pre><p>Then, whenever the <code class="docutils literal">OPTIONNAME</code> option is changed in conf.py, the file will be rebuilt.</p>
  388. <p>If your directive depends or may depend on the whole timeline (like the
  389. <code class="docutils literal"><span class="pre">post-list</span></code> directive, where adding new posts to the site could make it
  390. stale), you should record a dependency on the pseudo-path
  391. <code class="docutils literal"><span class="pre">####MAGIC####TIMELINE</span></code>.</p>
  392. </section>
  393. <section id="markdownextension-plugins">
  394. <h2><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">MarkdownExtension Plugins</a></h2>
  395. <p>Implement Markdown extensions, see <a class="reference external" href="https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/markdown/mdx_nikola.py">mdx_nikola.py</a> for a simple example.</p>
  396. <p>Note that Python markdown extensions are often also available as separate
  397. packages. This is only meant to ship extensions along with Nikola.</p>
  398. </section>
  399. <section id="signalhandler-plugins">
  400. <h2><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">SignalHandler Plugins</a></h2>
  401. <p>These plugins extend the <code class="docutils literal">SignalHandler</code> class and connect to one or more
  402. signals via <a class="reference external" href="https://pythonhosted.org/blinker/">blinker</a>.</p>
  403. <p>The easiest way to do this is to reimplement <code class="docutils literal">set_site()</code> and just connect to
  404. whatever signals you want there.</p>
  405. <p>Currently Nikola emits the following signals:</p>
  406. <dl>
  407. <dt><code class="docutils literal">sighandlers_loaded</code></dt>
  408. <dd><p>Right after SignalHandler plugin activation.</p>
  409. </dd>
  410. <dt><code class="docutils literal">initialized</code></dt>
  411. <dd><p>When all tasks are loaded.</p>
  412. </dd>
  413. <dt><code class="docutils literal">configured</code></dt>
  414. <dd><p>When all the configuration file is processed. Note that plugins are activated before this is emitted.</p>
  415. </dd>
  416. <dt><code class="docutils literal">scanned</code></dt>
  417. <dd><p>After posts are scanned.</p>
  418. </dd>
  419. <dt><code class="docutils literal">new_post</code> / <code class="docutils literal">new_page</code></dt>
  420. <dd><p>When a new post is created, using the <code class="docutils literal">nikola new_post</code>/<code class="docutils literal">nikola new_page</code> commands. The signal
  421. data contains the path of the file, and the metadata file (if there is one).</p>
  422. </dd>
  423. <dt><code class="docutils literal">existing_post</code> / <code class="docutils literal">existing_page</code></dt>
  424. <dd><p>When a new post fails to be created due to a title conflict. Contains the same data as <code class="docutils literal">new_post</code>.</p>
  425. </dd>
  426. <dt><code class="docutils literal">deployed</code></dt>
  427. <dd><p>When the <code class="docutils literal">nikola deploy</code> command is run, and there is at least one new
  428. entry/post since <code class="docutils literal">last_deploy</code>. The signal data is of the form:</p>
  429. <pre class="literal-block">{
  430. 'last_deploy: # datetime object for the last deployed time,
  431. 'new_deploy': # datetime object for the current deployed time,
  432. 'clean': # whether there was a record of a last deployment,
  433. 'deployed': # all files deployed after the last deploy,
  434. 'undeployed': # all files not deployed since they are either future posts/drafts
  435. }</pre>
  436. </dd>
  437. <dt><code class="docutils literal">compiled</code></dt>
  438. <dd><p>When a post/page is compiled from its source to html, before anything else is done with it. The signal
  439. data is in the form:</p>
  440. <pre class="literal-block">{
  441. 'source': # the path to the source file
  442. 'dest': # the path to the cache file for the post/page
  443. 'post': # the Post object for the post/page
  444. }</pre>
  445. </dd>
  446. </dl>
  447. <p>One example is the <a class="reference external" href="https://github.com/getnikola/plugins/tree/master/v7/deploy_hooks">deploy_hooks plugin.</a></p>
  448. </section>
  449. <section id="configplugin-plugins">
  450. <h2><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">ConfigPlugin Plugins</a></h2>
  451. <p>Does nothing specific, can be used to modify the site object (and thus the config).</p>
  452. <p>Put all the magic you want in <code class="docutils literal">set_site()</code>, and don’t forget to run the one
  453. from <code class="docutils literal">super()</code>. Example plugin: <a class="reference external" href="https://github.com/getnikola/plugins/tree/master/v7/navstories">navstories</a></p>
  454. </section>
  455. <section id="commentsystem-plugins">
  456. <h2><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">CommentSystem Plugins</a></h2>
  457. <p>Can be used to add a new comment system. (It doesn’t do anything by itself.) It’s expected to provide templates named <code class="docutils literal">comment_helper_foo.tmpl</code>.</p>
  458. <p>Example plugin: <a class="reference external" href="https://github.com/getnikola/plugins/tree/master/v8/cactuscomments">cactuscomments</a></p>
  459. </section>
  460. <section id="shortcode-plugins">
  461. <h2><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">Shortcode Plugins</a></h2>
  462. <p>Shortcode Plugins are a simple way to create a custom shortcode handler.
  463. By default, the <code class="docutils literal">set_site</code> method will register the <code class="docutils literal">handler</code> method as a
  464. shortcode with the plugin’s <code class="docutils literal">name</code> as the shortcode name.</p>
  465. <p>See the <a class="reference internal" href="#shortcodes">Shortcodes</a> section for more details on shortcodes.</p>
  466. </section>
  467. <section id="postscanner-plugins">
  468. <h2><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">PostScanner Plugins</a></h2>
  469. <p>Get posts and pages from &quot;somewhere&quot; to be added to the timeline.
  470. There are currently two plugins for this: the built-in <code class="docutils literal">scan_posts</code>, and
  471. <code class="docutils literal">pkgindex_scan</code> (in the Plugin Index), which is used to treat .plugin/.theme
  472. + README.md as posts to generate the Plugin and Theme Indexes.</p>
  473. </section>
  474. </section>
  475. <section id="plugin-index">
  476. <h1><a class="toc-backref" href="#toc-entry-14" role="doc-backlink">Plugin Index</a></h1>
  477. <p>There is a <a class="reference external" href="https://plugins.getnikola.com/">plugin index</a>, which stores all
  478. of the plugins for Nikola people wanted to share with the world.</p>
  479. <p>You may want to read the <a class="reference external" href="https://github.com/getnikola/plugins/blob/master/README.md">README for the Index</a> if you want to
  480. publish your package there.</p>
  481. </section>
  482. <section id="path-link-resolution-mechanism">
  483. <h1><a class="toc-backref" href="#toc-entry-15" role="doc-backlink">Path/Link Resolution Mechanism</a></h1>
  484. <p>Any plugin can register a function using <code class="docutils literal">Nikola.register_path_handler</code> to
  485. allow resolution of paths and links. These are useful for templates, which
  486. can access them via <code class="docutils literal">_link</code>.</p>
  487. <p>For example, you can always get a link to the path for the feed of the &quot;foo&quot; tag
  488. by using <code class="docutils literal"><span class="pre">_link('tag_rss',</span> 'foo')</code> or the <code class="docutils literal"><span class="pre">link://tag_rss/foo</span></code> URL.</p>
  489. <p>Here's the relevant code from the tag plugin.</p>
  490. <pre class="code python"><a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-1"></a><span class="c1"># In set_site</span>
  491. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-2"></a><span class="n">site</span><span class="o">.</span><span class="n">register_path_handler</span><span class="p">(</span><span class="s1">&#39;tag_rss&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">tag_rss_path</span><span class="p">)</span>
  492. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-3"></a>
  493. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-4"></a><span class="c1"># And these always take name and lang as arguments and return a list of</span>
  494. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-5"></a><span class="c1"># path elements.</span>
  495. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-6"></a><span class="k">def</span> <span class="nf">tag_rss_path</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">lang</span><span class="p">):</span>
  496. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-7"></a> <span class="k">return</span> <span class="p">[</span><span class="n">_f</span> <span class="k">for</span> <span class="n">_f</span> <span class="ow">in</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;TRANSLATIONS&#39;</span><span class="p">][</span><span class="n">lang</span><span class="p">],</span>
  497. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-8"></a> <span class="bp">self</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;TAG_PATH&#39;</span><span class="p">],</span> <span class="bp">self</span><span class="o">.</span><span class="n">slugify_name</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">lang</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;.xml&quot;</span><span class="p">]</span> <span class="k">if</span>
  498. <a name="rest_code_c3b874e131b54f6e96535b5ef0c56564-9"></a> <span class="n">_f</span><span class="p">]</span>
  499. </pre></section>
  500. <section id="template-hooks">
  501. <h1><a class="toc-backref" href="#toc-entry-16" role="doc-backlink">Template Hooks</a></h1>
  502. <p>Plugins can use a hook system for adding stuff into templates. In order to use
  503. it, a plugin must register itself. The following hooks currently exist:</p>
  504. <ul class="simple">
  505. <li><p><code class="docutils literal">extra_head</code> (not equal to the config option!)</p></li>
  506. <li><p><code class="docutils literal">body_end</code> (not equal to the config option!)</p></li>
  507. <li><p><code class="docutils literal">page_header</code></p></li>
  508. <li><p><code class="docutils literal">menu</code></p></li>
  509. <li><p><code class="docutils literal">menu_alt</code> (right-side menu in bootstrap, after <code class="docutils literal">menu</code> in base)</p></li>
  510. <li><p><code class="docutils literal">page_footer</code></p></li>
  511. </ul>
  512. <p>For example, in order to register a script into <code class="docutils literal">extra_head</code>:</p>
  513. <pre class="code python"><a name="rest_code_85abaedb49c6458da061ed02e63e3471-1"></a><span class="c1"># In set_site</span>
  514. <a name="rest_code_85abaedb49c6458da061ed02e63e3471-2"></a><span class="n">site</span><span class="o">.</span><span class="n">template_hooks</span><span class="p">[</span><span class="s1">&#39;extra_head&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;&lt;script src=&quot;/assets/js/fancyplugin.js&quot;&gt;&#39;</span><span class="p">)</span>
  515. </pre><p>There is also another API available. It allows use of dynamically generated
  516. HTML:</p>
  517. <pre class="code python"><a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-1"></a><span class="c1"># In set_site</span>
  518. <a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-2"></a><span class="k">def</span> <span class="nf">generate_html_bit</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">ftype</span><span class="o">=</span><span class="s1">&#39;js&#39;</span><span class="p">):</span>
  519. <a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-3"></a> <span class="sd">&quot;&quot;&quot;Generate HTML for an asset.&quot;&quot;&quot;</span>
  520. <a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-4"></a> <span class="k">return</span> <span class="s1">&#39;&lt;script src=&quot;/assets/</span><span class="si">{t}</span><span class="s1">/</span><span class="si">{n}</span><span class="s1">.</span><span class="si">{t}</span><span class="s1">&quot;&gt;&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">n</span><span class="o">=</span><span class="n">name</span><span class="p">,</span> <span class="n">t</span><span class="o">=</span><span class="n">ftype</span><span class="p">)</span>
  521. <a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-5"></a>
  522. <a name="rest_code_3d80b5b30b83451486e9468e8cca60f5-6"></a><span class="n">site</span><span class="o">.</span><span class="n">template_hooks</span><span class="p">[</span><span class="s1">&#39;extra_head&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">generate_html_bit</span><span class="p">,</span> <span class="kc">False</span><span class="p">,</span> <span class="s1">&#39;fancyplugin&#39;</span><span class="p">,</span> <span class="n">ftype</span><span class="o">=</span><span class="s1">&#39;js&#39;</span><span class="p">)</span>
  523. </pre><p>The second argument to <code class="docutils literal">append()</code> is used to determine whether the function
  524. needs access to the current template context and the site. If it is set to
  525. <code class="docutils literal">True</code>, the function will also receive <code class="docutils literal">site</code> and <code class="docutils literal">context</code> keyword
  526. arguments. Example use:</p>
  527. <pre class="code python"><a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-1"></a><span class="c1"># In set_site</span>
  528. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-2"></a><span class="k">def</span> <span class="nf">greeting</span><span class="p">(</span><span class="n">addr</span><span class="p">,</span> <span class="n">endswith</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="n">site</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">context</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
  529. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-3"></a> <span class="sd">&quot;&quot;&quot;Greet someone.&quot;&quot;&quot;</span>
  530. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-4"></a> <span class="k">if</span> <span class="n">context</span><span class="p">[</span><span class="s1">&#39;lang&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;en&#39;</span><span class="p">:</span>
  531. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-5"></a> <span class="n">greet</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;Hello&#39;</span>
  532. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-6"></a> <span class="k">elif</span> <span class="n">context</span><span class="p">[</span><span class="s1">&#39;lang&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;es&#39;</span><span class="p">:</span>
  533. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-7"></a> <span class="n">greet</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;¡Hola&#39;</span>
  534. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-8"></a>
  535. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-9"></a> <span class="n">t</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39; BLOG_TITLE = </span><span class="si">{0}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s1">&#39;BLOG_TITLE&#39;</span><span class="p">](</span><span class="n">context</span><span class="p">[</span><span class="s1">&#39;lang&#39;</span><span class="p">]))</span>
  536. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-10"></a>
  537. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-11"></a> <span class="k">return</span> <span class="sa">u</span><span class="s1">&#39;&lt;h3&gt;</span><span class="si">{greet}</span><span class="s1"> </span><span class="si">{addr}{endswith}</span><span class="s1">&lt;/h3&gt;&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">greet</span><span class="o">=</span><span class="n">greet</span><span class="p">,</span> <span class="n">addr</span><span class="o">=</span><span class="n">addr</span><span class="p">,</span>
  538. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-12"></a> <span class="n">endswith</span><span class="o">=</span><span class="n">endswith</span><span class="p">)</span> <span class="o">+</span> <span class="n">t</span>
  539. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-13"></a>
  540. <a name="rest_code_3b60727dbf4e432d81b289c0645bfb85-14"></a><span class="n">site</span><span class="o">.</span><span class="n">template_hooks</span><span class="p">[</span><span class="s1">&#39;page_header&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">greeting</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;Nikola Tesla&#39;</span><span class="p">,</span> <span class="n">endswith</span><span class="o">=</span><span class="sa">u</span><span class="s1">&#39;!&#39;</span><span class="p">)</span>
  541. </pre><p>Dependencies for template hooks:</p>
  542. <ul class="simple">
  543. <li><p>if the input is a string, the string value, alongside arguments to <code class="docutils literal">append</code>, is used for calculating dependencies</p></li>
  544. <li><p>if the input is a callable, it attempts <code class="docutils literal">input.template_registry_identifier</code>, then <code class="docutils literal">input.__doc__</code>, and if neither is available, it uses a static string.</p></li>
  545. </ul>
  546. <p>Make sure to provide at least a docstring, or a identifier, to ensure rebuilds work properly.</p>
  547. </section>
  548. <section id="shortcodes">
  549. <h1><a class="toc-backref" href="#toc-entry-17" role="doc-backlink">Shortcodes</a></h1>
  550. <p>Some (hopefully all) markup compilers support shortcodes in these forms:</p>
  551. <pre class="code text"><a name="rest_code_81c68590ecd6426193834bc742049523-1"></a>{{% foo %}} # No arguments
  552. <a name="rest_code_81c68590ecd6426193834bc742049523-2"></a>{{% foo bar %}} # One argument, containing &quot;bar&quot;
  553. <a name="rest_code_81c68590ecd6426193834bc742049523-3"></a>{{% foo bar baz=bat %}} # Two arguments, one containing &quot;bar&quot;, one called &quot;baz&quot; containing &quot;bat&quot;
  554. <a name="rest_code_81c68590ecd6426193834bc742049523-4"></a>
  555. <a name="rest_code_81c68590ecd6426193834bc742049523-5"></a>{{% foo %}}Some text{{% /foo %}} # one argument called &quot;data&quot; containing &quot;Some text&quot;
  556. </pre><p>So, if you are creating a plugin that generates markup, it may be a good idea
  557. to register it as a shortcode in addition of to restructured text directive or
  558. markdown extension, thus making it available to all markup formats.</p>
  559. <p>To implement your own shortcodes from a plugin, you can create a plugin inheriting <code class="docutils literal">ShortcodePlugin</code>.
  560. By default, the <code class="docutils literal">set_site</code> method will register the <code class="docutils literal">handler</code> method as a
  561. shortcode with the plugin’s <code class="docutils literal">name</code> as the shortcode name. To have other
  562. shortcode names, you can call
  563. <code class="docutils literal">Nikola.register_shortcode(name, func)</code> with the following arguments:</p>
  564. <dl class="simple">
  565. <dt><code class="docutils literal">name</code>:</dt>
  566. <dd><p>Name of the shortcode (&quot;foo&quot; in the examples above)</p>
  567. </dd>
  568. <dt><code class="docutils literal">func</code>:</dt>
  569. <dd><p>A function that will handle the shortcode</p>
  570. </dd>
  571. </dl>
  572. <p>The shortcode handler <strong>must</strong> return a two-element tuple, <code class="docutils literal">(output, dependencies)</code></p>
  573. <dl class="simple">
  574. <dt><code class="docutils literal">output</code>:</dt>
  575. <dd><p>The text that will replace the shortcode in the document.</p>
  576. </dd>
  577. <dt><code class="docutils literal">dependencies</code>:</dt>
  578. <dd><p>A list of all the files on disk which will make the output be considered
  579. out of date. For example, if the shortcode uses a template, it should be
  580. the path to the template file.</p>
  581. </dd>
  582. </dl>
  583. <p>The shortcode handler <strong>must</strong> accept the following named arguments (or
  584. variable keyword arguments):</p>
  585. <dl class="simple">
  586. <dt><code class="docutils literal">site</code>:</dt>
  587. <dd><p>An instance of the Nikola class, to access site state</p>
  588. </dd>
  589. <dt><code class="docutils literal">data</code>:</dt>
  590. <dd><p>If the shortcut is used as opening/closing tags, it will be the text
  591. between them, otherwise <code class="docutils literal">None</code>.</p>
  592. </dd>
  593. <dt><code class="docutils literal">lang</code>:</dt>
  594. <dd><p>The current language.</p>
  595. </dd>
  596. </dl>
  597. <p>If the shortcode tag has arguments of the form <code class="docutils literal">foo=bar</code> they will be
  598. passed as named arguments. Everything else will be passed as positional
  599. arguments in the function call.</p>
  600. <p>So, for example:</p>
  601. <pre class="literal-block">{{% foo bar baz=bat beep %}}Some text{{% /foo %}}</pre>
  602. <p>Assuming you registered <code class="docutils literal">foo_handler</code> as the handler function for the
  603. shortcode named <code class="docutils literal">foo</code>, this will result in the following call when the above
  604. shortcode is encountered:</p>
  605. <pre class="literal-block">foo_handler(&quot;bar&quot;, &quot;beep&quot;, baz=&quot;bat&quot;, data=&quot;Some text&quot;, site=whatever)</pre>
  606. <section id="template-based-shortcodes">
  607. <h2><a class="toc-backref" href="#toc-entry-18" role="doc-backlink">Template-based Shortcodes</a></h2>
  608. <p>Another way to define a new shortcode is to add a template file to the
  609. <code class="docutils literal">shortcodes</code> directory of your site. The template file must have the
  610. shortcode name as the basename and the extension <code class="docutils literal">.tmpl</code>. For example, if you
  611. want to add a new shortcode named <code class="docutils literal">foo</code>, create the template file as
  612. <code class="docutils literal">shortcodes/foo.tmpl</code>.</p>
  613. <p>When the shortcode is encountered, the matching template will be rendered with
  614. its context provided by the arguments given in the shortcode. Keyword arguments
  615. are passed directly, i.e. the key becomes the variable name in the template
  616. namespace with a matching string value. Non-keyword arguments are passed as
  617. string values in a tuple named <code class="docutils literal">_args</code>. As for normal shortcodes with a
  618. handler function, <code class="docutils literal">site</code> and <code class="docutils literal">data</code> will be added to the keyword arguments.</p>
  619. <p>Example:</p>
  620. <p>The following shortcode:</p>
  621. <pre class="code text"><a name="rest_code_78887cdd58254883b05f3fd58cf55913-1"></a>{{% foo bar="baz" spam %}}
  622. </pre><p>With a template in <code class="docutils literal">shortcodes/foo.tmpl</code> with this content (using Jinja2
  623. syntax in this example)</p>
  624. <pre class="code jinja"><a name="rest_code_fb1d3a1ec39d459a889fc8c7fcc88c32-1"></a><span class="x">&lt;div class=&quot;</span><span class="cp">{{</span> <span class="nv">_args</span><span class="o">[</span><span class="m">0</span><span class="o">]</span> <span class="k">if</span> <span class="nv">_args</span> <span class="k">else</span> <span class="s1">&#39;ham&#39;</span> <span class="cp">}}</span><span class="x">&quot;&gt;</span><span class="cp">{{</span> <span class="nv">bar</span> <span class="cp">}}</span><span class="x">&lt;/div&gt;</span>
  625. </pre><p>Will result in this output</p>
  626. <pre class="code html"><a name="rest_code_13ea22a2fa9842d6af6fed3495660b25-1"></a><span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;spam&quot;</span><span class="p">&gt;</span>baz<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  627. </pre></section>
  628. </section>
  629. <section id="state-and-cache">
  630. <h1><a class="toc-backref" href="#toc-entry-19" role="doc-backlink">State and Cache</a></h1>
  631. <p>Sometimes your plugins will need to cache things to speed up further actions. Here are the conventions for that:</p>
  632. <ul class="simple">
  633. <li><p>If it's a file, put it somewhere in <code class="docutils literal"><span class="pre">self.site.config['CACHE_FOLDER']</span></code> (defaults to <code class="docutils literal">cache/</code>.</p></li>
  634. <li><p>If it's a value, use <code class="docutils literal">self.site.cache.set(key, value)</code> to set it and <code class="docutils literal">self.site.cache.get(key)</code> to get it.
  635. The key should be a string, the value should be json-encodable (so, be careful with datetime objects)</p></li>
  636. </ul>
  637. <p>The values and files you store there can <strong>and will</strong> be deleted sometimes by the user. They should always be
  638. things you can reconstruct without lossage. They are throwaways.</p>
  639. <p>On the other hand, sometimes you want to save something that is <strong>not</strong> a throwaway. These are things that may
  640. change the output, so the user should not delete them. We call that <strong>state</strong>. To save state:</p>
  641. <ul class="simple">
  642. <li><p>If it's a file, put it somewhere in the working directory. Try not to do that please.</p></li>
  643. <li><p>If it's a value, use <code class="docutils literal">self.site.state.set(key, value)</code> to set it and <code class="docutils literal">self.state.cache.get(key)</code> to get it.
  644. The key should be a string, the value should be json-encodable (so, be careful with datetime objects)</p></li>
  645. </ul>
  646. <p>The <code class="docutils literal">cache</code> and <code class="docutils literal">state</code> objects are rather simplistic, and that's intentional. They have no default values: if
  647. the key is not there, you will get <code class="docutils literal">None</code> and like it. They are meant to be both threadsafe, but hey, who can
  648. guarantee that sort of thing?</p>
  649. <p>There are no sections, and no access protection, so let's not use it to store passwords and such. Use responsibly.</p>
  650. </section>
  651. <section id="logging">
  652. <h1><a class="toc-backref" href="#toc-entry-20" role="doc-backlink">Logging</a></h1>
  653. <p>Plugins often need to produce messages to the screen. All plugins get a logger object (<code class="docutils literal">self.logger</code>) by default,
  654. configured to work with Nikola (logging level, colorful output, plugin name as the logger name). If you need, you can
  655. also use the global (<code class="docutils literal">nikola.utils.LOGGER</code>) logger, or you can instantiate custom loggers with
  656. <code class="docutils literal">nikola.utils.get_logger</code> or the <code class="docutils literal">nikola.log</code> module.</p>
  657. </section>
  658. <section id="template-and-dependency-injection">
  659. <h1><a class="toc-backref" href="#toc-entry-21" role="doc-backlink">Template and Dependency Injection</a></h1>
  660. <p>Plugins have access to two injection facilities.</p>
  661. <p>If your plugin needs custom templates for its features (adding pages, displaying stuff, etc.), you can put them in the
  662. <code class="docutils literal">templates/mako</code> and <code class="docutils literal">templates/jinja</code> subfolders in your plugin’s folder. Note that those templates have a very low
  663. priority, so that users can override your plugin’s templates with their own.</p>
  664. <p>If your plugin needs to inject dependencies, the <code class="docutils literal">inject_dependency(target, dependency)</code> function can be used to add a
  665. <code class="docutils literal">dependency</code> for tasks which basename == <code class="docutils literal">target</code>. This facility should be limited to cases which really need it,
  666. consider other facilities first (eg. adding post dependencies).</p>
  667. </section>