This Sphinx theme was very much inspired by (i.o.w. ripped off of) mdBook.
If you don’t like this theme, no problem, Sphinx has several Builtin themes to choose from and you can find a large list of third-party Sphinx themes at https://sphinx-themes.org/. You can also search for Sphinx themes on PyPI, GitLab and Github.
The following list has been driving the development of this theme. Those are the goals, but that doesn’t necessarily mean that any of them has been reached (to a sufficient degree) yet.
If you have suggestions how to come closer to these goals, please create an issue or – even better! – a pull request at https://github.com/mgeier/insipid-sphinx-theme/.
The most important thing is your content. It shouldn’t be outshined by some flashy theme. The theme is supposed to stay in the background and out of the way.
This theme uses only very few (and only locally available) fonts, very few (and quite dull) colors and just a handful of simple symbols.
Most navigational tools can be hidden (and are in fact hidden by default), providing a maximum of screen real estate for and a minimum of distraction from your content. Only if your browser window is extremely wide, the sidebar will be shown on the initial visit. This can be configured with
Help needed! There are some
aria-labels here and there, but the accessibility could certainly be improved in many places.
This theme should work well on (reasonably modern) mobile devices. Considerable care has been taken to make sure all the screen space is available for content and not obstructed by ornamental junk.
The default settings should be perfectly fine for most people. But doesn’t everyone sometimes like to be special? Many features can be switched on and off (see Configuration), and thanks to Sphinx’s great flexibility, you can fine-tune and individualize virtually every aspect of the theme, see Customization for details.
- support for right-to-left languages
Help needed! For now, there are no special arrangements in place except for a measly
- support for all Sphinx features
The largest part of this documentation (starting at Showcases) is a showcase of (hopefully) all things that can be generated with Sphinx (aside from arbitrary “raw” HTML). If you find something that isn’t supported (or not shown in the docs), please let us know!
- back to the
This theme is derived from Sphinx’s
basictheme), and no extension-specific Python code is ever executed (you can check the source code of
First of all, the
insipid theme tries to not disable any features
that Sphinx (and its
basic theme, see basic Settings) already has.
Here’s a little selection of features, some of them provided by Sphinx itself,
some added by the
- auto-hiding topbar
The goal is to maximize (vertical) screen space and to get out of the way. Therefore, the topbar disappears when scrolling down. When scrolling up, or when hovering over (or touching) the top part of the screen, it re-appears.
The topbar contains some useful icons (see
right_buttons) as well as the title of the current page. When clicking on said title, the page is scrolled to the top and the title of the parent document is displayed. Clicking on that brings you to the parent document.
- resizable sidebar
In addition to toggling its visibility, the width of the sidebar can also be interactively changed by users. The new width (and whether the sidebar is visible or not) is stored in the browser’s “local storage”, which means it will be remembered for the next visit.
The default width can be configured with the theme option
sidebarwidth, the content of the sidebar can be configured with
On devices with a touchscreen, the sidebar can be opened/closed with a swipe right/left gesture.
- keyboard navigation
This is one of the features that’s provided by Sphinx, but several third-party themes have inadvertently disabled it.
You can switch between pages using the left and right arrow keys. This feature can be disabled with
In addition to the left/right arrow keys, several key combinations are provided using the
accesskeyHTML feature. The way to use these keyboard shortcuts depends on the browser and the operating system, typically involving holding the Alt key, often combined with the Shift or the Control key. For details, see e.g. MDN.
The following access keys are available in many Sphinx themes: N for the next page; P for the previous page; U for up (to the parent page); I for the index. In addition to these, the
insipidtheme provides S to show/hide the search field and M for showing/hiding the sidebar (i.e. the menu).
- fullscreen mode
When supported by the browser (and when not overridden with
right_buttons), the topbar contains an icon for switching into (and out of) fullscreen mode.
Navigating to another page will typically exit fullscreen mode.
- translatable UI
All strings used in the user interface (including
aria-labels) are translatable and they will be automatically replaced by their translations when a supported
languagesetting is used.
- support for https://readthedocs.org/
The RTD “badge” (for selecting versions, languages etc.) is incorporated into the bottom of the
insipidsidebar (instead of floating around in the bottom right corner of the page).
Furthermore, a link to the connected Bitbucket/Github/GitLab repository is automatically displayed in the topbar. This can be disabled by overriding
html_copy_sourceis set to
False, a “show source” link to the appropriate version of the page source on Bitbucket/Github/GitLab is shown in the footer of each page. The link can be disabled by setting