=============
Configuration
=============

The NervProject theme webpage is composed of a fixed header, a sidebar and main content area.

The ``util`` folder contains Jinja2 snippets to be *included*,
from main templates. Those can be easily replaced by theme users.

To change site/page structure you should *extend* pages and give new implementations for Jinja2 **blocks**.

Jinja2 templates and blocks are organized as follow:



Config values
=============

``html_logo``
^^^^^^^^^^^^^

If defined shows an image instead of project name on page top-left (link to index page).

.. code-block:: python

   html_logo = '_static/myproject-logo.png'


``html_sidebars``
^^^^^^^^^^^^^^^^^

By default the *sidebars* include only: searchbox and a global TOC tree.
See docs on `html_sidebars <http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars>`_.

.. code-block:: python

  html_sidebars = {'**': ['util/searchbox.html', 'util/sidetoc.html']}


``html_css_files``
^^^^^^^^^^^^^^^^^^

Adds custom CSS files to the theme

.. code-block:: python

    # Here we assume that the file is at _static/css/custom.css
    html_css_files = ["css/custom.css"]

``html_external_links``
^^^^^^^^^^^^^^^^^^^^^^^

If provided, creates external links (e.g. Github) in the top right corner:

.. code-block:: python

   html_theme_options = {
       "logoalt": project,
       "social": [
           ('iconset', 'icon', 'text', 'link'),
       ],
       "twitter_user": "",
       "mastodon_user": "@user@instance",
       "fathom": {
           'url': 'example.org',
           'id': 'FATHOM',
       },
       'isso': {
           'prefix': '/isso',
           'url': baseurl + '/isso',
           'require_author': "true",
           'lang': 'fr',
           'reply_to_self': "true",
           'require_author': "true",
           'require_email': "false",
           'reply_notif': "true",
           'max_comments_top': 20,
           'max_comments_nested': 20,
           'reveal_on_click': 20,
           'avatar': "true",
           'vote': "false",
           'vote_levels': "",
           'feed': "true",
       },
       "license": {
           'type': 'CC',
           'subtype': 'BY-SA',
           'version': '4.0',
           'url': 'https://creativecommons.org/licenses/by-sa/4.0/legalcode'
       }
   }
   html_sidebars = {
       '**': [
           'about.html',
           'postcard.html', 'util/sidetoc.html',
           'recentposts.html', 'tagcloud.html',
           'categories.html',  'archives.html',
           'social.html',
           'util/searchbox.html',
       ],
   }

Templates
=========


``layout.html``
^^^^^^^^^^^^^^^

Blocks on HTML head:

- ``htmltitle`` - HTML page title
- ``css`` - include theme's CSS files
- ``scripts`` - include theme's javascript files
- ``extrahead`` - empty by default, to be used by theme users


Blocks on HTML body:

``container`` - whole visible page

* ``header`` - fixed header (includes ``util/navbar.html``)

  - ``navbar.html`` - apart from home-link includes ``util/navlinks.html`` & ``util/extlinks.html``

* ``sidebar``

  - ``side_links`` - includes ``util/navlinks.html`` & ``util/extlinks.html``
  - include all templates listed on ``html_sidebars`` config

* ``document``

  - ``body_header`` - includes ``util/bodyheader.html``
  - ``body`` - main content generated from ReST documents
  - ``footer`` - includes ``util/pagenav.html`` & ``util/footer.html``


``util/navbar.html``
^^^^^^^^^^^^^^^^^^^^

Header content. Left side contains *home-link* with name.

Right side contains links from ``util/navlinks.html`` and ``util/extlinks.html``.


``util/navlinks.html``
^^^^^^^^^^^^^^^^^^^^^^

Links taken from TOCs defined on master document.


``util/extlinks.html``
^^^^^^^^^^^^^^^^^^^^^^

External links defined by theme's user.


``util/searchbox.html``
^^^^^^^^^^^^^^^^^^^^^^^

Form to perform site search.

``util/sidetoc.html``
^^^^^^^^^^^^^^^^^^^^^

Navigation from toctree.


``util/bodyheader.html``
^^^^^^^^^^^^^^^^^^^^^^^^

Breadcrumbs and page navigation.

``util/pagenav.html``
^^^^^^^^^^^^^^^^^^^^^

Links for previous/next page.


``util/footer.html``
^^^^^^^^^^^^^^^^^^^^

Copyright information.

``ui/src/vuepress/styles/config.less``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This file contains the four sub-themes color schemes.
You can fork and rebuild a theme from scratch changing
this file, or using CSS priority rules to override
values.
