Themes and extensions

Themes and extensions#

We learned the hard way that maintaining the design and features of documentation is a lot of work. To make all documentation maintainable, we use actively developed themes and extensions to build the documentation.

Themes#

When customizing the theme, we use Sphinx Book Theme, which in turn depends on PyData Sphinx Theme. See their documentation for features, tips, and tricks that you might want to include in your documentation.

We minimize the customizations of these themes as much as possible. The one large customization is the search filter by part of the documentation, implemented in modifcations to the templates, _static/searchtools.js, and the CSS file _static/custom.css.

Extensions#

We use several MyST and Sphinx extensions to enhance the presentation of Plone documentation.

MyST#

  • deflist supports definition lists.

  • linkify identifies "bare" web URLs and adds hyperlinks.

  • colon_fence supports the use of three colons ::: as delimiters to denote code fences, instead of three backticks ```.

  • substitution supports the use of substitutions with Jinja2.

  • html_image supports the use of HTML <img> tags.

Sphinx#

Contents