123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450 |
- <dl class="docinfo simple">
- <dt class="version">Version<span class="colon">:</span></dt>
- <dd class="version">8.2.3</dd>
- <dt class="author">Author<span class="colon">:</span></dt>
- <dd class="author"><p>Roberto Alsina <<a class="reference external" href="mailto:ralsina@netmanagers.com.ar">ralsina@netmanagers.com.ar</a>></p></dd>
- </dl>
- <nav class="contents alert alert-primary float-md-right" id="contents" role="doc-toc">
- <p class="topic-title">Contents</p>
- <ul class="simple">
- <li><p><a class="reference internal" href="#the-structure" id="toc-entry-1">The Structure</a></p></li>
- <li><p><a class="reference internal" href="#theme-meta-files" id="toc-entry-2">Theme meta files</a></p></li>
- <li><p><a class="reference internal" href="#templates" id="toc-entry-3">Templates</a></p></li>
- <li><p><a class="reference internal" href="#built-in-templates" id="toc-entry-4">Built-in templates</a></p></li>
- <li><p><a class="reference internal" href="#variables-available-in-templates" id="toc-entry-5">Variables available in templates</a></p></li>
- <li><p><a class="reference internal" href="#customizing-themes-to-user-color-preference-colorizing-category-names" id="toc-entry-6">Customizing themes to user color preference, colorizing category names</a></p></li>
- <li><p><a class="reference internal" href="#identifying-and-customizing-different-kinds-of-pages-with-a-shared-template" id="toc-entry-7">Identifying and customizing different kinds of pages with a shared template</a></p></li>
- <li><p><a class="reference internal" href="#messages-and-translations" id="toc-entry-8">Messages and Translations</a></p></li>
- <li><p><a class="reference internal" href="#less-and-sass" id="toc-entry-9">LESS and Sass</a></p></li>
- </ul>
- </nav>
- <p class="lead">This document is a reference about themes. If you want a tutorial, please read
- <a class="reference external" href="/pages/creating-a-theme.html">Creating a Theme</a>. If you’re looking for a ready-made
- theme for your site, check out the <a class="reference external" href="https://themes.getnikola.com/">Themes Index</a>.</p>
- <section id="the-structure">
- <h1><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">The Structure</a></h1>
- <p>Themes are located in the <code class="docutils literal">themes</code> folder where Nikola is installed, and in the <code class="docutils literal">themes</code> folder
- of your site, one folder per theme. The folder name is the theme name.</p>
- <p>A Nikola theme consists of the following folders (they are <em>all</em> optional):</p>
- <dl>
- <dt>assets</dt>
- <dd><p>This is where you would put your CSS, JavaScript and image files. It will be copied
- into <code class="docutils literal">output/assets</code> when you build the site, and the templates will contain
- references to them. The default subdirectories are <code class="docutils literal">css</code>, <code class="docutils literal">js</code>, <code class="docutils literal">xml</code>
- and <code class="docutils literal">fonts</code> (Bootstrap).</p>
- <p>The included themes use <a class="reference external" href="https://getbootstrap.com/">Bootstrap</a>,
- <a class="reference external" href="https://feimosi.github.io/baguetteBox.js/">baguetteBox</a>, <a class="reference external" href="https://flickr.github.io/justified-layout/">Justified Layout by Flickr</a> and <a class="reference external" href="https://moment.github.io/luxon/">Luxon</a>, so they are in assets, along with CSS files for
- syntax highlighting, reStructuredText and Jupyter, as well as a minified
- copy of jQuery.</p>
- <p>If you want to base your theme on other frameworks (or on no framework at all)
- just remember to put there everything you need for deployment. (Not all of
- the listed assets are used by <code class="docutils literal">base</code>)</p>
- </dd>
- <dt>templates</dt>
- <dd><p>This contains the templates used to generate the pages. While Nikola will use a
- certain set of template names by default, you can add others for specific parts
- of your site.</p>
- </dd>
- <dt>messages</dt>
- <dd><p>Nikola tries to be multilingual. This is where you put the strings for your theme
- so that it can be translated into other languages.</p>
- </dd>
- <dt>less, sass</dt>
- <dd><p>Files to be compiled into CSS using LESS and Sass (both require plugins)</p>
- </dd>
- </dl>
- <p>This mandatory file:</p>
- <dl class="simple">
- <dt><theme>.theme</dt>
- <dd><p>An INI file containing theme meta data. The file format is described in
- detail below, in the <a class="reference internal" href="#theme-meta-files">Theme meta files</a> section.</p>
- </dd>
- </dl>
- <p>And these optional files:</p>
- <dl>
- <dt>parent, engine</dt>
- <dd><p>One-line text files that contain the names of parent and engine themes,
- respectively. Those are needed for older versions (Nikola v7.8.5 and
- older).</p>
- </dd>
- <dt>bundles</dt>
- <dd><p>A <a class="reference external" href="https://docs.python.org/3/library/configparser.html">config</a> file
- containing a list of files to be turned into bundles. For example:</p>
- <pre class="code ini"><a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-1"></a><span class="na">assets/css/all.css</span><span class="o">=</span><span class="s"></span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-2"></a><span class="s"> bootstrap.min.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-3"></a><span class="s"> rst_base.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-4"></a><span class="s"> nikola_rst.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-5"></a><span class="s"> code.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-6"></a><span class="s"> baguetteBox.min.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-7"></a><span class="s"> theme.css,</span>
- <a name="rest_code_1e62c0f8635c468a9e9e465b2eb0939e-8"></a><span class="s"> custom.css,</span>
- </pre><p>This creates a file called "assets/css/all.css" in your output that is the
- combination of all the other file paths, relative to the output file.
- This makes the page much more efficient because it avoids multiple connections to the server,
- at the cost of some extra difficult debugging.</p>
- <p>Bundling applies to CSS and JS files.</p>
- <p>Templates should use either the bundle or the individual files based on the <code class="docutils literal">use_bundles</code>
- variable, which in turn is set by the <code class="docutils literal">USE_BUNDLES</code> option.</p>
- </dd>
- </dl>
- </section>
- <section id="theme-meta-files">
- <h1><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Theme meta files</a></h1>
- <p>As of Nikola v7.8.6, Nikola uses meta files for themes. Those are INI files,
- with the same name as your theme, and a <code class="docutils literal">.theme</code> extension, eg.
- <code class="docutils literal">bootstrap3.theme</code>. Here is an example, from the bootstrap3 theme:</p>
- <pre class="code ini"><a name="rest_code_929f518a59e14434bd6c9df89e29e59d-1"></a><span class="k">[Theme]</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-2"></a><span class="na">engine</span> <span class="o">=</span> <span class="s">mako</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-3"></a><span class="na">parent</span> <span class="o">=</span> <span class="s">base</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-4"></a><span class="na">author</span> <span class="o">=</span> <span class="s">The Nikola Contributors</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-5"></a><span class="na">author_url</span> <span class="o">=</span> <span class="s">https://getnikola.com/</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-6"></a><span class="na">based_on</span> <span class="o">=</span> <span class="s">Bootstrap 3 <https://getbootstrap.com/></span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-7"></a><span class="na">license</span> <span class="o">=</span> <span class="s">MIT</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-8"></a><span class="na">tags</span> <span class="o">=</span> <span class="s">bootstrap</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-9"></a>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-10"></a><span class="k">[Family]</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-11"></a><span class="na">family</span> <span class="o">=</span> <span class="s">bootstrap3</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-12"></a><span class="na">jinja_version</span> <span class="o">=</span> <span class="s">bootstrap3-jinja</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-13"></a><span class="na">variants</span> <span class="o">=</span> <span class="s">bootstrap3-gradients, bootstrap3-gradients-jinja</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-14"></a>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-15"></a><span class="k">[Nikola]</span>
- <a name="rest_code_929f518a59e14434bd6c9df89e29e59d-16"></a><span class="na">bootswatch</span> <span class="o">=</span> <span class="s">True</span>
- </pre><p>The following keys are currently supported:</p>
- <ul>
- <li><p><code class="docutils literal">Theme</code> — contains information about the theme.</p>
- <ul>
- <li><p><code class="docutils literal">engine</code> — engine used by the theme. Should be <code class="docutils literal">mako</code> or <code class="docutils literal">jinja</code>.</p></li>
- <li><p><code class="docutils literal">parent</code> — the parent theme. Any resources missing in this theme, will be
- looked up in the parent theme (and then in the grandparent, etc).</p>
- <p>The parent is so you don’t have to create a full theme each time: just
- create an empty theme, set the parent, and add the bits you want modified.
- You <strong>must</strong> define a parent, otherwise many features won’t work due to
- missing templates, messages, and assets.</p>
- <p>The following settings are recommended:</p>
- <ul class="simple">
- <li><p>If your theme uses Bootstrap 3, inherit the <code class="docutils literal">bootstrap3</code> theme.</p></li>
- <li><p>If your theme uses Jinja as a template engine, inherit <code class="docutils literal"><span class="pre">base-jinja</span></code>
- or <code class="docutils literal"><span class="pre">bootstrap3-jinja</span></code></p></li>
- <li><p>In any other case, inherit <code class="docutils literal">base</code>.</p></li>
- </ul>
- </li>
- <li><p><code class="docutils literal">author</code>, <code class="docutils literal">author_url</code> — used to identify theme author.</p></li>
- <li><p><code class="docutils literal">based_on</code> — optional list of inspirations, frameworks, etc. used in the
- theme. Should be comma-separated, the format <code class="docutils literal">Name <URL></code> is recommended.</p></li>
- <li><p><code class="docutils literal">license</code> — theme license. Pick MIT if you have no preference.</p></li>
- <li><p><code class="docutils literal">tags</code> — optional list of tags (comma-separated) to describe the theme.</p></li>
- </ul>
- </li>
- <li><p><code class="docutils literal">Family</code> — contains information about other related themes. All values
- optional. (Do not use unless you have related themes.)</p>
- <ul class="simple">
- <li><p><code class="docutils literal">family</code> — the name of the main theme in a family, which is also used as
- the family name.</p></li>
- <li><p><code class="docutils literal">mako_version</code>, <code class="docutils literal">jinja_version</code> — name of the mako/jinja version of the
- theme.</p></li>
- <li><p><code class="docutils literal">variants</code> — comma-separated list of stylistic variants (other than the
- mako/jinja version listed above)</p></li>
- </ul>
- </li>
- <li><p><code class="docutils literal">Nikola</code> — Nikola-specific information, currently optional.</p>
- <ul class="simple">
- <li><p><code class="docutils literal">bootswatch</code> — whether or not theme supports Bootswatch styling (optional,
- defaults to False)</p></li>
- <li><p><code class="docutils literal">ignored_assets</code> — comma-separated list of assets to ignore (relative to
- the <code class="docutils literal">assets/</code> directory, eg. <code class="docutils literal">css/theme.css</code>)</p></li>
- </ul>
- </li>
- </ul>
- </section>
- <section id="templates">
- <h1><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Templates</a></h1>
- <p>In templates there is a number of files whose name ends in <code class="docutils literal">.tmpl</code>. Those are the
- theme’s page templates. They are done using the <a class="reference external" href="https://www.makotemplates.org">Mako</a>
- or <a class="reference external" href="http://jinja.pocoo.org">Jinja2</a> template languages. If you want to do a theme, you
- should learn one first. What engine is used by the theme is declared in the <code class="docutils literal">engine</code> file.</p>
- <aside class="admonition tip">
- <p class="admonition-title">Tip</p>
- <p>If you are using Mako templates, and want some extra speed when building the site
- you can install Beaker and <a class="reference external" href="https://docs.makotemplates.org/en/latest/caching.html">make templates be cached</a></p>
- </aside>
- <p>Both template engines have a nifty concept of template inheritance. That means that a
- template can inherit from another and only change small bits of the output. For example,
- <code class="docutils literal">base.tmpl</code> defines the whole layout for a page but has only a placeholder for content
- so <code class="docutils literal">post.tmpl</code> only define the content, and the layout is inherited from <code class="docutils literal">base.tmpl</code>.</p>
- <p>Another concept is theme inheritance. You do not need to duplicate all the
- default templates in your theme — you can just override the ones you want
- changed, and the rest will come from the parent theme. (Every theme needs a
- parent.)</p>
- <p>Apart from the <a class="reference internal" href="#built-in-templates">built-in templates</a> listed below, you can add other templates for specific
- pages, which the user can then use in his <code class="docutils literal">POSTS</code> or <code class="docutils literal">PAGES</code> option in
- <code class="docutils literal">conf.py</code>. Also, you can specify a custom template to be used by a post or
- page via the <code class="docutils literal">template</code> metadata, and custom templates can be added in the
- <code class="docutils literal">templates/</code> folder of your site.</p>
- <p>If you want to modify (override) a built-in template, use <code class="docutils literal">nikola theme <span class="pre">-c</span>
- <span class="pre"><name>.tmpl</span></code>. This command will copy the specified template file to the
- <code class="docutils literal">templates/</code> directory of your currently used theme.</p>
- <p>Keep in mind that your theme is <em>yours</em>, so you can require whatever data you
- want (eg. you may depend on specific custom <code class="docutils literal">GLOBAL_CONTEXT</code> variables, or
- post meta attributes). You don’t need to keep the same theme structure as the
- default themes do (although many of those names are hardcoded). Inheriting from
- at least <code class="docutils literal">base</code> (or <code class="docutils literal"><span class="pre">base-jinja</span></code>) is heavily recommended, but not strictly
- required (unless you want to share it on the Themes Index).</p>
- </section>
- <section id="built-in-templates">
- <h1><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Built-in templates</a></h1>
- <p>These are the templates that come with the included themes:</p>
- <dl>
- <dt><code class="docutils literal">base.tmpl</code></dt>
- <dd><p>This template defines the basic page layout for the site. It’s mostly plain HTML
- but defines a few blocks that can be re-defined by inheriting templates.</p>
- <p>It has some separate pieces defined in <code class="docutils literal">base_helper.tmpl</code>,
- <code class="docutils literal">base_header.tmpl</code> and <code class="docutils literal">base_footer.tmpl</code> so they can be
- easily overridden.</p>
- </dd>
- <dt><code class="docutils literal">index.tmpl</code></dt>
- <dd><p>Template used to render the multipost indexes. The posts are in a <code class="docutils literal">posts</code> variable.
- Some functionality is in the <code class="docutils literal">index_helper.tmpl</code> helper template.</p>
- </dd>
- <dt><code class="docutils literal">archive_navigation_helper.tmpl</code> (internal)</dt>
- <dd><p>Code that implements archive navigation (previous/up/next). Included by
- archive templates.</p>
- </dd>
- <dt><code class="docutils literal">archiveindex.tmpl</code></dt>
- <dd><p>Used to display archives, if <code class="docutils literal">ARCHIVES_ARE_INDEXES</code> is True.
- By default, it just inherits <code class="docutils literal">index.tmpl</code>, with added archive navigation
- and feeds.</p>
- </dd>
- <dt><code class="docutils literal">author.tmpl</code></dt>
- <dd><p>Used to display author pages.</p>
- </dd>
- <dt><code class="docutils literal">authorindex.tmpl</code></dt>
- <dd><p>Used to display author indexes, if <code class="docutils literal">AUTHOR_PAGES_ARE_INDEXES</code> is True.
- By default, it just inherits <code class="docutils literal">index.tmpl</code>, with added feeds.</p>
- </dd>
- <dt><code class="docutils literal">comments_helper.tmpl</code> (internal)</dt>
- <dd><p>This template handles comments. You should probably never touch it :-)
- It uses a bunch of helper templates, one for each supported comment system
- (all of which start with <code class="docutils literal">comments_helper</code>)</p>
- </dd>
- <dt><code class="docutils literal">ui_helper.tmpl</code>, <code class="docutils literal">pagination_helper.tmpl</code></dt>
- <dd><p>These templates help render specific UI items, and can be tweaked as needed.</p>
- </dd>
- <dt><code class="docutils literal">gallery.tmpl</code></dt>
- <dd><p>Template used for image galleries. Interesting data includes:</p>
- <ul class="simple">
- <li><p><code class="docutils literal">post</code>: A post object, containing descriptive <code class="docutils literal">post.text()</code> for the gallery.</p></li>
- <li><p><code class="docutils literal">crumbs</code>: A list of <code class="docutils literal">link, crumb</code> to implement breadcrumbs.</p></li>
- <li><p><code class="docutils literal">folders</code>: A list of folders to implement hierarchical gallery navigation.</p></li>
- <li><p><code class="docutils literal">enable_comments</code>: To enable/disable comments in galleries.</p></li>
- <li><p><code class="docutils literal">thumbnail_size</code>: The <code class="docutils literal">THUMBNAIL_SIZE</code> option.</p></li>
- <li><p><code class="docutils literal">photo_array</code>: a list of dictionaries, each containing:</p>
- <ul>
- <li><p><code class="docutils literal">url</code>: URL for the full-sized image.</p></li>
- <li><p><code class="docutils literal">url_thumb</code>: URL for the thumbnail.</p></li>
- <li><p><code class="docutils literal">title</code>: The title of the image.</p></li>
- <li><p><code class="docutils literal">size</code>: A dict containing <code class="docutils literal">w</code> and <code class="docutils literal">h</code>, the real size of the thumbnail.</p></li>
- </ul>
- </li>
- <li><p><code class="docutils literal">photo_array_json</code>: a JSON dump of photo_array, used by the
- <code class="docutils literal"><span class="pre">justified-layout</span></code> script</p></li>
- </ul>
- </dd>
- <dt><code class="docutils literal">list.tmpl</code></dt>
- <dd><p>Template used to display generic lists of links, which it gets in <code class="docutils literal">items</code>,
- a list of <em>(text, link, count)</em> elements.</p>
- </dd>
- <dt><code class="docutils literal">list_post.tmpl</code></dt>
- <dd><p>Template used to display generic lists of posts, which it gets in <code class="docutils literal">posts</code>.</p>
- </dd>
- <dt><code class="docutils literal">listing.tmpl</code></dt>
- <dd><p>Used to display code listings.</p>
- </dd>
- <dt><code class="docutils literal">math_helper.tmpl</code> (internal)</dt>
- <dd><p>Used to add MathJax/KaTeX code to pages.</p>
- </dd>
- <dt><code class="docutils literal">post.tmpl</code></dt>
- <dd><p>Template used by default for blog posts, gets the data in a <code class="docutils literal">post</code> object
- which is an instance of the Post class. Some functionality is in the
- <code class="docutils literal">post_helper.tmpl</code> and <code class="docutils literal">post_header.tmpl</code> templates.</p>
- </dd>
- <dt><code class="docutils literal">post_list_directive.tmpl</code></dt>
- <dd><p>Template used by the <code class="docutils literal">post_list</code> reStructuredText directive.</p>
- </dd>
- <dt><code class="docutils literal">page.tmpl</code></dt>
- <dd><p>Used for pages that are not part of a blog, usually a cleaner, less
- intrusive layout than <code class="docutils literal">post.tmpl</code>, but same parameters.</p>
- </dd>
- <dt><code class="docutils literal">tag.tmpl</code></dt>
- <dd><p>Used to show the contents of a single tag or category.</p>
- </dd>
- <dt><code class="docutils literal">tagindex.tmpl</code></dt>
- <dd><p>Used to show the contents of a single tag or category, if <code class="docutils literal">TAG_PAGES_ARE_INDEXES</code> is True.
- By default, it just inherits <code class="docutils literal">index.tmpl</code>, with added feeds and some
- extra features.</p>
- </dd>
- <dt><code class="docutils literal">tags.tmpl</code></dt>
- <dd><p>Used to display the list of tags and categories.</p>
- </dd>
- </dl>
- </section>
- <section id="variables-available-in-templates">
- <h1><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Variables available in templates</a></h1>
- <p>The full, complete list of variables available in templates is maintained in a separate
- document: <a class="reference external" href="https://getnikola.com/template-variables.html">Template variables</a></p>
- </section>
- <section id="customizing-themes-to-user-color-preference-colorizing-category-names">
- <h1><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">Customizing themes to user color preference, colorizing category names</a></h1>
- <p>The user’s preference for theme color is exposed in templates as
- <code class="docutils literal">theme_color</code> set in the <code class="docutils literal">THEME_COLOR</code> option.</p>
- <p>This theme color is exposed to the browser in default themes — some browsers
- might use this color in the user interface (eg. Chrome on Android in light mode
- displays the toolbar in this color).</p>
- <p>Nikola also comes with support for auto-generating colors similar to a base
- color. This can be used with <code class="docutils literal">theme_color</code> and eg. category names. This
- feature is exposed to templates as two functions: <code class="docutils literal">colorize_str(string,
- hex_color, presets)</code> and <code class="docutils literal">colorize_str_from_base_color(string, hex_color)</code>.
- If you want to display the category name in the color, first define a list of
- overrides in your <code class="docutils literal">conf.py</code> file:</p>
- <pre class="code python"><a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-1"></a><span class="c1"># end of conf.py</span>
- <a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-2"></a><span class="n">GLOBAL_CONTEXT</span> <span class="o">=</span> <span class="p">{</span>
- <a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-3"></a> <span class="s2">"category_colors"</span><span class="p">:</span> <span class="p">{</span>
- <a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-4"></a> <span class="s2">"Blue"</span><span class="p">:</span> <span class="s2">"#0000FF"</span>
- <a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-5"></a> <span class="p">}</span>
- <a name="rest_code_e1e6e214a9724e84bd4409ca879f1410-6"></a><span class="p">}</span>
- </pre><p>With that definition, you can now use <code class="docutils literal">colorize_str</code> in your templates like this:</p>
- <pre class="code html+mako"><a name="rest_code_fba7b12c95374a1cbb5c15eb884d099c-1"></a><span class="c"><!-- Mako --></span>
- <a name="rest_code_fba7b12c95374a1cbb5c15eb884d099c-2"></a><span class="p"><</span><span class="nt">span</span> <span class="na">style</span><span class="o">=</span><span class="s">"background-color: </span><span class="cp">${</span><span class="n">colorize_str</span><span class="p">(</span><span class="n">post</span><span class="o">.</span><span class="n">meta</span><span class="p">(</span><span class="s1">'category'</span><span class="p">),</span> <span class="n">theme_color</span><span class="p">,</span> <span class="n">category_colors</span><span class="p">)</span><span class="cp">}</span><span class="s">"</span><span class="p">></span><span class="cp">${</span><span class="n">post</span><span class="o">.</span><span class="n">meta</span><span class="p">(</span><span class="s1">'category'</span><span class="p">)</span><span class="cp">}</span><span class="p"></</span><span class="nt">span</span><span class="p">></span>
- </pre><pre class="code html+jinja"><a name="rest_code_61d83b94de6c4f51b3b59b3a4baf9b50-1"></a><span class="c"><!-- Jinja2 --></span>
- <a name="rest_code_61d83b94de6c4f51b3b59b3a4baf9b50-2"></a><span class="p"><</span><span class="nt">span</span> <span class="na">style</span><span class="o">=</span><span class="s">"background-color: </span><span class="cp">{{</span> <span class="nv">colorize_str</span><span class="o">(</span><span class="nv">post.meta</span><span class="o">(</span><span class="s1">'category'</span><span class="o">),</span> <span class="nv">theme_color</span><span class="o">,</span> <span class="nv">category_colors</span><span class="o">)</span> <span class="cp">}}</span><span class="s">"</span><span class="p">></span><span class="cp">{{</span> <span class="nv">post.meta</span><span class="o">(</span><span class="s1">'category'</span><span class="o">)</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">span</span><span class="p">></span>
- </pre><p>Note that the category named “Blue” will be displyed in #0000FF due to the
- override specified in your config; other categories will have an auto-generated
- color visually similar to your theme color.</p>
- <p>Hex color values, like that returned by the theme or string colorization can be
- altered in the HSL colorspace through the function
- <code class="docutils literal">color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)</code>.
- Adjustments are given in values between 1.0 and -1.0. For example, the theme
- color can be made lighter using this code:</p>
- <pre class="code html+mako"><a name="rest_code_09d4261e8af8487ab07c92c3b2b9d794-1"></a><span class="c"><!-- Mako --></span>
- <a name="rest_code_09d4261e8af8487ab07c92c3b2b9d794-2"></a><span class="p"><</span><span class="nt">span</span> <span class="na">style</span><span class="o">=</span><span class="s">"color: </span><span class="cp">${</span><span class="n">color_hsl_adjust_hex</span><span class="p">(</span><span class="n">theme_color</span><span class="p">,</span> <span class="n">adjust_l</span><span class="o">=</span><span class="mf">0.05</span><span class="p">)</span><span class="cp">}</span><span class="s">"</span><span class="p">></span>
- </pre><pre class="code html+jinja"><a name="rest_code_11fca1d7d4a942dd8dce2c8624ac1e9c-1"></a><span class="c"><!-- Jinja2 --></span>
- <a name="rest_code_11fca1d7d4a942dd8dce2c8624ac1e9c-2"></a><span class="p"><</span><span class="nt">span</span> <span class="na">style</span><span class="o">=</span><span class="s">"color: </span><span class="cp">{{</span> <span class="nv">color_hsl_adjust_hex</span><span class="o">(</span><span class="nv">theme_color</span><span class="o">,</span> <span class="nv">adjust_l</span><span class="o">=</span><span class="m">0.05</span><span class="o">)</span> <span class="cp">}}</span><span class="s">"</span><span class="p">></span>
- </pre></section>
- <section id="identifying-and-customizing-different-kinds-of-pages-with-a-shared-template">
- <h1><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Identifying and customizing different kinds of pages with a shared template</a></h1>
- <p>Nikola provides a <code class="docutils literal">pagekind</code> in each template contexts that can be used to
- modify shared templates based on the context it’s being used. For example,
- the <code class="docutils literal">base_helper.tmpl</code> is used in all pages, <code class="docutils literal">index.tmpl</code> is used in
- many contexts and you may want to add or remove something from only one of
- these contexts.</p>
- <p>Example of conditionally loading different resources on all index pages
- (archives, author pages, and tag pages), and others again to the front page
- and in every post pages:</p>
- <pre class="code html+mako"><a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-1"></a><span class="c"><!-- Mako --></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-2"></a><span class="p"><</span><span class="nt">head</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-3"></a> …
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-4"></a> <span class="cp">%</span> <span class="k">if</span> <span class="s1">'index'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-5"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/multicolumn.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-6"></a> <span class="cp">%</span><span class="k"> endif</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-7"></a> <span class="cp">%</span> <span class="k">if</span> <span class="s1">'front_page'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-8"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/fancy_homepage.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-9"></a> <span class="p"><</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">"/assets/js/post_carousel.js"</span><span class="p">></</span><span class="nt">script</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-10"></a> <span class="cp">%</span><span class="k"> endif</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-11"></a> <span class="cp">%</span> <span class="k">if</span> <span class="s1">'post_page'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-12"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/article.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-13"></a> <span class="p"><</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">"/assets/js/comment_system.js"</span><span class="p">></</span><span class="nt">script</span><span class="p">></span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-14"></a> <span class="cp">%</span><span class="k"> endif</span>
- <a name="rest_code_8477a412a8d044dfa96ede312ef0d4d8-15"></a><span class="p"></</span><span class="nt">head</span><span class="p">></span>
- </pre><pre class="code html+jinja"><a name="rest_code_c83f454f264a4909ac8903c54f97d97d-1"></a><span class="c"><!-- Jinja2 --></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-2"></a><span class="p"><</span><span class="nt">head</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-3"></a> …
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-4"></a> <span class="cp">{%</span> <span class="k">if</span> <span class="s1">'index'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-5"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/multicolumn.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-6"></a> <span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-7"></a> <span class="cp">{%</span> <span class="k">if</span> <span class="s1">'front_page'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-8"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/fancy_homepage.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-9"></a> <span class="p"><</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">"/assets/js/post_carousel.js"</span><span class="p">></</span><span class="nt">script</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-10"></a> <span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-11"></a> <span class="cp">{%</span> <span class="k">if</span> <span class="s1">'post_page'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-12"></a> <span class="p"><</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"/assets/css/article.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-13"></a> <span class="p"><</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">"/assets/js/comment_system.js"</span><span class="p">></</span><span class="nt">script</span><span class="p">></span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-14"></a> <span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
- <a name="rest_code_c83f454f264a4909ac8903c54f97d97d-15"></a><span class="p"></</span><span class="nt">head</span><span class="p">></span>
- </pre><p>Promoting visits to the front page when visiting other filtered
- <code class="docutils literal">index.tmpl</code> page variants such as author pages and tag pages. This
- could have been included in <code class="docutils literal">index.tmpl</code> or maybe in <code class="docutils literal">base.tmpl</code>
- depending on what you want to achieve.</p>
- <pre class="code html+mako"><a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-1"></a><span class="c"><!-- Mako --></span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-2"></a><span class="cp">%</span> <span class="k">if</span> <span class="s1">'index'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-3"></a> <span class="cp">%</span> <span class="k">if</span> <span class="s1">'author_page'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-4"></a> <span class="p"><</span><span class="nt">p</span><span class="p">></span>These posts were written by <span class="cp">${</span><span class="n">author</span><span class="cp">}</span>. See posts by all
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-5"></a> authors on the <span class="p"><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>front page<span class="p"></</span><span class="nt">a</span><span class="p">></span>.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-6"></a> <span class="cp">%</span> <span class="k">elif</span> <span class="s1">'tag_page'</span> <span class="ow">in</span> <span class="n">pagekind</span><span class="p">:</span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-7"></a> <span class="p"><</span><span class="nt">p</span><span class="p">></span>This is a filtered selection of posts tagged “<span class="cp">${</span><span class="n">tag</span><span class="cp">}</span>”, visit
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-8"></a> the <span class="p"><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>front page<span class="p"></</span><span class="nt">a</span><span class="p">></span> to see all posts.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-9"></a> <span class="cp">%</span><span class="k"> endif</span>
- <a name="rest_code_c1bfafa3138941eab0bf9d2de02c820d-10"></a><span class="cp">%</span><span class="k"> endif</span>
- </pre><pre class="code html+jinja"><a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-1"></a><span class="c"><!-- Jinja2 --></span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-2"></a><span class="cp">{%</span> <span class="k">if</span> <span class="s1">'index'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-3"></a> <span class="cp">{%</span> <span class="k">if</span> <span class="s1">'author_page'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-4"></a> <span class="p"><</span><span class="nt">p</span><span class="p">></span>These posts were written by <span class="cp">{{</span> <span class="nv">author</span> <span class="cp">}}</span>. See posts by all
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-5"></a> authors on the <span class="p"><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>front page<span class="p"></</span><span class="nt">a</span><span class="p">></span>.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-6"></a> <span class="cp">{%</span> <span class="k">elif</span> <span class="s1">'tag_page'</span> <span class="k">in</span> <span class="nv">pagekind</span> <span class="cp">%}</span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-7"></a> <span class="p"><</span><span class="nt">p</span><span class="p">></span>This is a filtered selection of posts tagged “<span class="cp">{{</span> <span class="nv">tag</span> <span class="cp">}}</span>”, visit
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-8"></a> the <span class="p"><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>front page<span class="p"></</span><span class="nt">a</span><span class="p">></span> to see all posts.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-9"></a> <span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
- <a name="rest_code_611dcf30e7d4429a95ab119bf2981fdd-10"></a><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
- </pre><p>List of page kinds provided by default plugins:</p>
- <ul class="simple">
- <li><p>front_page</p></li>
- <li><p>index</p></li>
- <li><p>index, archive_page</p></li>
- <li><p>index, author_page</p></li>
- <li><p>index, main_index</p></li>
- <li><p>index, tag_page</p></li>
- <li><p>list</p></li>
- <li><p>list, archive_page</p></li>
- <li><p>list, author_page</p></li>
- <li><p>list, tag_page</p></li>
- <li><p>list, tags_page</p></li>
- <li><p>post_page</p></li>
- <li><p>page_page</p></li>
- <li><p>story_page</p></li>
- <li><p>listing</p></li>
- <li><p>generic_page</p></li>
- <li><p>gallery_front</p></li>
- <li><p>gallery_page</p></li>
- </ul>
- </section>
- <section id="messages-and-translations">
- <h1><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Messages and Translations</a></h1>
- <p>The included themes are translated into a variety of languages. You can add your own translation
- at <a class="reference external" href="https://www.transifex.com/projects/p/nikola/">https://www.transifex.com/projects/p/nikola/</a></p>
- <p>If you want to create a theme that has new strings, and you want those strings to be translatable,
- then your theme will need a custom <code class="docutils literal">messages</code> folder.</p>
- </section>
- <section id="less-and-sass">
- <h1><a class="reference external" href="http://lesscss.org/">LESS</a> and <a class="reference external" href="https://sass-lang.com/">Sass</a></h1>
- <aside class="admonition note">
- <p class="admonition-title">Note</p>
- <p>The LESS and Sass compilers were moved to the Plugins Index in
- Nikola v7.0.0.</p>
- </aside>
- <p>If you want to use those CSS extensions, you can — just store your files
- in the <code class="docutils literal">less</code> or <code class="docutils literal">sass</code> directory of your theme.</p>
- <p>In order to have them work, you need to create a list of <code class="docutils literal">.less</code> or
- <code class="docutils literal"><span class="pre">.scss/.sass</span></code> files to compile — the list should be in a file named
- <code class="docutils literal">targets</code> in the respective directory (<code class="docutils literal">less</code>/<code class="docutils literal">sass</code>).</p>
- <p>The files listed in the <code class="docutils literal">targets</code> file will be passed to the respective
- compiler, which you have to install manually (<code class="docutils literal">lessc</code> which comes from
- the Node.js package named <code class="docutils literal">less</code> or <code class="docutils literal">sass</code> from a Ruby package aptly
- named <code class="docutils literal">sass</code>). Whatever the compiler outputs will be saved as a CSS
- file in your rendered site, with the <code class="docutils literal">.css</code> extension.</p>
- <aside class="admonition note">
- <p class="admonition-title">Note</p>
- <p>Conflicts may occur if you have two files with the same base name
- but a different extension. Pay attention to how you name your files
- or your site won’t build! (Nikola will tell you what’s wrong when
- this happens)</p>
- </aside>
- </section>
|