# mkdocs-toggle-sidebar-plugin
[](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
This package allows you to toggle the left (navigation) and right (table of contents) sidebars on a couple of MkDocs themes such as:
- [Material for MkDocs](https://github.com/squidfunk/mkdocs-material): `material`
- Builtin themes: `mkdocs`, `readthedocs`
You can play around with it and these themes on the [test page](https://mkdocs-toggle-sidebar.six-two.dev).
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.
## Usage
### Setup
First install the PyPI package:
```bash
pip install mkdocs-toggle-sidebar-plugin
```
Add something like the following to your `mkdocs.yml`:
```yaml
plugins:
- search
- toggle-sidebar
```
### Key bindings
The plugin adds the following key bindings:
Key | Action
--- | ---
`b` | toggle **b**oth (TOC and navigation)
`m` | toggle navigation **m**enu
`t` | toggle **T**OC
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.
### Configuration options
You can overwrite the defaults like this:
```yaml
plugins:
- search
- toggle-sidebar:
async: False
debug: True
enabled: True
inline: False
javascript: ./toggle-sidebar.js
show_navigation_by_default: False
show_toc_by_default: False
theme: material
toggle_button: all
```
The following options exist:
Option | Type | Default value | Description
--- | ---| --- | ---
async | `bool` | `False` | Asynchronously load the JavaScript file created by the plugin
debug | `bool` | `False` | Show some debug messages during mkdocs build (for example related to theme detection)
enabled | `bool` | `True` | Can be used to disable the plugin. Usually used in combination with environment variables like `enabled: !ENV [TOGGLE_SIDEBAR, false]` as described in [mkdocs's docs](https://www.mkdocs.org/user-guide/configuration/#enabled-option)
inline | `bool` | `False` | Instead of storing the javascript code in the file specified by `javascript`, it is directly copied into each page. Slightly increases page size, but can improve load times a little bit and reduce flickering on page (re-)load
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
theme | `str` | `auto` | Used for theme detection. With `auto`, the plugin tries to automatically detect the theme. But you can also force it to use a specific theme preset that you know will work. Currently supported values: `material`/`ansible`, `mkdocs`, `readthedocs`.
toggle_button | `str` | `"none"` | Can be set to show a toggle button (see below)
#### Toggle button
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.
### Exported API functions
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.
## Theme support
Below shows the latest themes that I have tested.
The table is not updated regularly, but the plugin should generally work for other theme versions too.
Theme | Theme version | Plugin version | Status
--- | --- | --- | ---
mkdocs-ansible | 25.6.0 | 0.0.6 | works
mkdocs-material | 9.6.14 | 0.0.4+ | works
mkdocs (default) | 1.6.1 | 0.0.4+ | works
readthedocs | 1.6.1 | 0.0.4+ | works
Just open an issue / PR if you use a strange theme or the info above is not up-to-date anymore.
### Note to self
Test `material` theme:
```bash
./serve.sh
```
Test `mkdocs` theme:
```bash
./serve.sh --theme mkdocs
```
Test `mkdocs`, `readthedocs` and `material` themes:
```bash
./build.sh
python3 -m http.server --directory './public/'
```
Test oldest python version supported by me (3.9):
```bash
docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:3.9 ./serve.sh
```
Test newest available python version (currently 3.13):
```bash
docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:latest ./serve.sh
```
## Notable changes
### Version 0.0.8
- Fixed toggle button not shown in certain window dimensions in Material theme (see #11)
### Version 0.0.7
- Fixed sidebar not hidden in material's blog mode (see #9). Thank you @ZnPdCo for finding and fixing the issue.
### Version 0.0.6
- Fixed toggle button appearing delayed on slow loading pages (see #6)
- Fixed behavior when using Material's `navigation.instant` feature (see #5)
- Added `inline` option that prevents page flickering on reload (see #4). It is now enabled by default and async is disabled by default, to prevent the flickering. To revert to the old behavior you can set `async: True` and `inline: False` in the plugin's config in your `mkdocs.yml`
- Added `theme` option that allows you to override theme detection (see #3)
- Added support for `ansible` theme (see #3)
- Added fallback to check `theme.extra.base_theme` from `mkdocs.yml` when other theme detection logic fails (see #3)
- Added `debug` option
### Version 0.0.5
- Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
### Version 0.0.4
- Export API via `MkdocsToggleSidebarPlugin` object.
This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
- Added `toggle_button` option and implemented it for Material theme.
### Version 0.0.3
- Changed internal API:
- Element hiding/restyling is now done via CSS, so it is easier to undo. You should no longer have problems on devices with small screens (like phones) having broken layouts.
### Version 0.0.2
- Added support for `mkdocs` and `readthedocs` theme.
### Version 0.0.1
- Prototype with `mkdocs-material` implementation.
Raw data
{
"_id": null,
"home_page": "https://github.com/six-two/mkdocs-toggle-sidebar-plugin",
"name": "mkdocs-toggle-sidebar-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "six-two",
"author_email": "pip@six-two.dev",
"download_url": "https://files.pythonhosted.org/packages/04/a2/b4851f24fd3d2fe963f5d9f4b01a360cf3b9c0b5d928f8f1d9d50b02bba2/mkdocs_toggle_sidebar_plugin-0.0.8.tar.gz",
"platform": null,
"description": "# mkdocs-toggle-sidebar-plugin\n\n[](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)\n\n\n\nThis package allows you to toggle the left (navigation) and right (table of contents) sidebars on a couple of MkDocs themes such as:\n\n- [Material for MkDocs](https://github.com/squidfunk/mkdocs-material): `material`\n- Builtin themes: `mkdocs`, `readthedocs`\n\nYou can play around with it and these themes on the [test page](https://mkdocs-toggle-sidebar.six-two.dev).\n\nThe settings are stored using the `localStorage` object, so that it will persist between pages.\n\nI 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.\n\n\n## Usage\n\n### Setup\n\nFirst install the PyPI package:\n```bash\npip install mkdocs-toggle-sidebar-plugin\n```\n\nAdd something like the following to your `mkdocs.yml`:\n```yaml\nplugins:\n- search\n- toggle-sidebar\n```\n\n### Key bindings\n\nThe plugin adds the following key bindings:\n\nKey | Action\n--- | ---\n`b` | toggle **b**oth (TOC and navigation)\n`m` | toggle navigation **m**enu\n`t` | toggle **T**OC\n\nFor some themes like `readthedocs` navigation and TOC are combined.\nIn this case the state of TOC is ignored, and only calls for navigation (or all) are interpreted.\n\n### Configuration options\n\nYou can overwrite the defaults like this:\n\n```yaml\nplugins:\n- search\n- toggle-sidebar:\n async: False\n debug: True\n enabled: True\n inline: False\n javascript: ./toggle-sidebar.js\n show_navigation_by_default: False\n show_toc_by_default: False\n theme: material\n toggle_button: all\n```\n\nThe following options exist:\n\nOption | Type | Default value | Description\n--- | ---| --- | ---\nasync | `bool` | `False` | Asynchronously load the JavaScript file created by the plugin\ndebug | `bool` | `False` | Show some debug messages during mkdocs build (for example related to theme detection)\nenabled | `bool` | `True` | Can be used to disable the plugin. Usually used in combination with environment variables like `enabled: !ENV [TOGGLE_SIDEBAR, false]` as described in [mkdocs's docs](https://www.mkdocs.org/user-guide/configuration/#enabled-option)\ninline | `bool` | `False` | Instead of storing the javascript code in the file specified by `javascript`, it is directly copied into each page. Slightly increases page size, but can improve load times a little bit and reduce flickering on page (re-)load\njavascript | `str` | `\"assets/javascripts/toggle-sidebar.js\"` | The path where to store the output file\nshow_navigation_by_default | `bool` | `True` | Whether to show the navigation by default\nshow_toc_by_default | `bool` | `True` | Whether to show the table of contents by default\ntheme | `str` | `auto` | Used for theme detection. With `auto`, the plugin tries to automatically detect the theme. But you can also force it to use a specific theme preset that you know will work. Currently supported values: `material`/`ansible`, `mkdocs`, `readthedocs`.\ntoggle_button | `str` | `\"none\"` | Can be set to show a toggle button (see below)\n\n\n#### Toggle button\n\nWhen 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.\nIt is usually in the nav or the top bar.\nClicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).\nBy leaving the field empty or setting it to `none`, no button is added.\n\n### Exported API functions\n\nThis plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.\nYou 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`.\n\nIn short there are:\n\n- `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`\n- `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`\n- `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`\n- `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`\n- `MkdocsToggleSidebarPlugin.toggleTocVisibility()`\n- `MkdocsToggleSidebarPlugin.toggleAllVisibility()`\n\nThe names and parameters should be self-explanatory.\n\n## Theme support\n\nBelow shows the latest themes that I have tested.\nThe table is not updated regularly, but the plugin should generally work for other theme versions too.\n\nTheme | Theme version | Plugin version | Status\n--- | --- | --- | ---\nmkdocs-ansible | 25.6.0 | 0.0.6 | works\nmkdocs-material | 9.6.14 | 0.0.4+ | works\nmkdocs (default) | 1.6.1 | 0.0.4+ | works\nreadthedocs | 1.6.1 | 0.0.4+ | works\n\nJust open an issue / PR if you use a strange theme or the info above is not up-to-date anymore.\n\n### Note to self\n\nTest `material` theme:\n```bash\n./serve.sh\n```\n\nTest `mkdocs` theme:\n```bash\n./serve.sh --theme mkdocs\n```\n\nTest `mkdocs`, `readthedocs` and `material` themes:\n```bash\n./build.sh\npython3 -m http.server --directory './public/'\n```\n\nTest oldest python version supported by me (3.9):\n```bash\ndocker run --rm -it -v \"$PWD:/share\" -w \"/share\" -p 8000:8000 --entrypoint=bash python:3.9 ./serve.sh\n```\n\nTest newest available python version (currently 3.13):\n```bash\ndocker run --rm -it -v \"$PWD:/share\" -w \"/share\" -p 8000:8000 --entrypoint=bash python:latest ./serve.sh\n```\n\n\n## Notable changes\n\n### Version 0.0.8\n\n- Fixed toggle button not shown in certain window dimensions in Material theme (see #11)\n\n### Version 0.0.7\n\n- Fixed sidebar not hidden in material's blog mode (see #9). Thank you @ZnPdCo for finding and fixing the issue.\n\n### Version 0.0.6\n\n- Fixed toggle button appearing delayed on slow loading pages (see #6)\n- Fixed behavior when using Material's `navigation.instant` feature (see #5)\n- Added `inline` option that prevents page flickering on reload (see #4). It is now enabled by default and async is disabled by default, to prevent the flickering. To revert to the old behavior you can set `async: True` and `inline: False` in the plugin's config in your `mkdocs.yml`\n- Added `theme` option that allows you to override theme detection (see #3)\n- Added support for `ansible` theme (see #3)\n- Added fallback to check `theme.extra.base_theme` from `mkdocs.yml` when other theme detection logic fails (see #3)\n- Added `debug` option\n\n### Version 0.0.5\n\n- Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.\n\n### Version 0.0.4\n\n- Export API via `MkdocsToggleSidebarPlugin` object.\n This lets you create custom buttons or key bindings to hide, show or toggle the side bars.\n- Added `toggle_button` option and implemented it for Material theme.\n\n### Version 0.0.3\n\n- Changed internal API:\n - Element hiding/restyling is now done via CSS, so it is easier to undo. You should no longer have problems on devices with small screens (like phones) having broken layouts.\n\n### Version 0.0.2\n\n- Added support for `mkdocs` and `readthedocs` theme.\n\n### Version 0.0.1\n\n- Prototype with `mkdocs-material` implementation.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Add keybindings to toggle the navigation and table of contents sidebars",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/six-two/mkdocs-toggle-sidebar-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aaa9ca5774f416baade721172d60e0cfbed2e271222cafee205d79f948275d9b",
"md5": "39c967734f21f962fdea65874604b080",
"sha256": "bec2d4db2be77e2e7d6bf52f05541803a1688839228aea12555db9d1f8db68c2"
},
"downloads": -1,
"filename": "mkdocs_toggle_sidebar_plugin-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39c967734f21f962fdea65874604b080",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13642,
"upload_time": "2025-08-21T17:47:12",
"upload_time_iso_8601": "2025-08-21T17:47:12.980013Z",
"url": "https://files.pythonhosted.org/packages/aa/a9/ca5774f416baade721172d60e0cfbed2e271222cafee205d79f948275d9b/mkdocs_toggle_sidebar_plugin-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "04a2b4851f24fd3d2fe963f5d9f4b01a360cf3b9c0b5d928f8f1d9d50b02bba2",
"md5": "c538b6167d33b670de09939a767815d3",
"sha256": "a640fa60b6485012c5ecd24e927132eec71410ffa16b38ff44cb9c5be49e0a92"
},
"downloads": -1,
"filename": "mkdocs_toggle_sidebar_plugin-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "c538b6167d33b670de09939a767815d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13905,
"upload_time": "2025-08-21T17:47:14",
"upload_time_iso_8601": "2025-08-21T17:47:14.364100Z",
"url": "https://files.pythonhosted.org/packages/04/a2/b4851f24fd3d2fe963f5d9f4b01a360cf3b9c0b5d928f8f1d9d50b02bba2/mkdocs_toggle_sidebar_plugin-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 17:47:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "six-two",
"github_project": "mkdocs-toggle-sidebar-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "babel",
"specs": [
[
"==",
"2.17.0"
]
]
},
{
"name": "backrefs",
"specs": [
[
"==",
"5.9"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.7.14"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.2"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.8"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "ghp-import",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "importlib-metadata",
"specs": [
[
"==",
"8.7.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.6"
]
]
},
{
"name": "markdown",
"specs": [
[
"==",
"3.8.2"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "mergedeep",
"specs": [
[
"==",
"1.3.4"
]
]
},
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "mkdocs-get-deps",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.6.15"
]
]
},
{
"name": "mkdocs-material-extensions",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"25.0"
]
]
},
{
"name": "paginate",
"specs": [
[
"==",
"0.5.7"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.8"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.19.2"
]
]
},
{
"name": "pymdown-extensions",
"specs": [
[
"==",
"10.16"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "pyyaml-env-tag",
"specs": [
[
"==",
"1.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.5.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.23.0"
]
]
}
],
"lcname": "mkdocs-toggle-sidebar-plugin"
}
JSON
