This package allows you to toggle the left (navigation) and right (table of contents) sidebars on a couple of MkDocs themes such as:
material
mkdocs
, readthedocs
You can play around with it and these themes on the test page.
The settings are stored using the localStorage
object, so that it will persist between pages.
I wrote it after getting frustrated by the browser's Find in page
function matching way to many links in the navigation sidebar instead of searching in the actual page's content.
First install the PyPI package:
pip install mkdocs-toggle-sidebar-plugin
Add something like the following to your mkdocs.yml
:
plugins:
- search
- toggle-sidebar
The plugin adds the following key bindings:
Key | Action |
---|---|
b |
toggle both (TOC and navigation) |
m |
toggle navigation menu |
t |
toggle TOC |
For some themes like readthedocs
navigation and TOC are combined.
In this case the state of TOC is ignored, and only calls for navigation (or all) are interpreted.
You can overwrite the defaults like this:
plugins:
- search
- toggle-sidebar:
async: False
javascript: ./toggle-sidebar.js
show_navigation_by_default: False
show_toc_by_default: False
toggle_button: all
The following options exist:
Option | Type | Default value | Description |
---|---|---|---|
async | bool |
True |
Asynchronously load the JavaScript file created by the plugin |
javascript | str |
"assets/javascripts/toggle-sidebar.js" |
The path where to store the output file |
show_navigation_by_default | bool |
True |
Whether to show the navigation by default |
show_toc_by_default | bool |
True |
Whether to show the table of contents by default |
toggle_button | str |
"none" |
Can be set to show a toggle button (see below) |
When you set the toggle_button
option to navigation
, toc
or all
, it will add a button that looks like a hamburger menu (three horizontal bars) on a theme-dependent location.
It is usually in the nav or the top bar.
Clicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).
By leaving the field empty or setting it to none
, no button is added.
This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
You can see how they are called in docs/javascript-functions.md
and how they are defined in src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js
.
In short there are:
MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)
MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)
MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)
MkdocsToggleSidebarPlugin.toggleNavigationVisibility()
MkdocsToggleSidebarPlugin.toggleTocVisibility()
MkdocsToggleSidebarPlugin.toggleAllVisibility()
The names and parameters should be self-explanatory.
Below shows the latest themes that I have tested. They are not updated that often, and the plugin should generally work for other of theme versions too.
Theme | Theme version | Plugin version | Status |
---|---|---|---|
mkdocs-material | 9.5.34 | 0.0.4 | works |
mkdocs (default) | 1.6.1 | 0.0.4 | works |
readthedocs | 1.6.1 | 0.0.4 | works |
Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
Test mkdocs-material theme:
./serve.sh
Test mkdocs theme:
./serve.sh --theme mkdocs
MkdocsToggleSidebarPlugin
object.
This lets you create custom buttons or key bindings to hide, show or toggle the side bars.toggle_button
option and implemented it for Material theme.mkdocs
and readthedocs
theme.mkdocs-material
implementation.