mkdocs-toggle-sidebar-plugin 0.0.3__tar.gz → 0.0.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. {mkdocs-toggle-sidebar-plugin-0.0.3/src/mkdocs_toggle_sidebar_plugin.egg-info → mkdocs_toggle_sidebar_plugin-0.0.5}/PKG-INFO +44 -5
  2. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/README.md +42 -3
  3. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/setup.cfg +2 -2
  4. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin/__init__.py +9 -2
  5. mkdocs_toggle_sidebar_plugin-0.0.5/src/mkdocs_toggle_sidebar_plugin/material.js +67 -0
  6. mkdocs_toggle_sidebar_plugin-0.0.5/src/mkdocs_toggle_sidebar_plugin/mkdocs.js +69 -0
  7. mkdocs_toggle_sidebar_plugin-0.0.5/src/mkdocs_toggle_sidebar_plugin/readthedocs.js +67 -0
  8. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js +53 -0
  9. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5/src/mkdocs_toggle_sidebar_plugin.egg-info}/PKG-INFO +44 -5
  10. mkdocs-toggle-sidebar-plugin-0.0.3/src/mkdocs_toggle_sidebar_plugin/material.js +0 -32
  11. mkdocs-toggle-sidebar-plugin-0.0.3/src/mkdocs_toggle_sidebar_plugin/mkdocs.js +0 -36
  12. mkdocs-toggle-sidebar-plugin-0.0.3/src/mkdocs_toggle_sidebar_plugin/readthedocs.js +0 -33
  13. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/LICENSE +0 -0
  14. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/MANIFEST.in +0 -0
  15. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/pyproject.toml +0 -0
  16. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin.egg-info/SOURCES.txt +0 -0
  17. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin.egg-info/dependency_links.txt +0 -0
  18. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin.egg-info/entry_points.txt +0 -0
  19. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin.egg-info/requires.txt +0 -0
  20. {mkdocs-toggle-sidebar-plugin-0.0.3 → mkdocs_toggle_sidebar_plugin-0.0.5}/src/mkdocs_toggle_sidebar_plugin.egg-info/top_level.txt +0 -0
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: mkdocs-toggle-sidebar-plugin
3
- Version: 0.0.3
4
- Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
3
+ Version: 0.0.5
4
+ Summary: Add keybindings to toggle the navigation and table of contents sidebars
5
5
  Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
6
6
  Author: six-two
7
7
  Author-email: pip@six-two.dev
@@ -61,13 +61,42 @@ Key | Action
61
61
  `m` | toggle navigation **m**enu
62
62
  `t` | toggle **T**OC
63
63
 
64
+ For some themes like `readthedocs` navigation and TOC are combined.
65
+ In this case the state of TOC is ignored, and only calls for navigation (or all) are interpreted.
66
+
67
+ ### Toggle button
68
+
69
+ 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.
70
+ It is usually in the nav or the top bar.
71
+ Clicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).
72
+ By leaving the field empty or setting it to `none`, no button is added.
73
+
74
+ ### Exported API functions
75
+
76
+ This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
77
+ 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`.
78
+
79
+ In short there are:
80
+
81
+ - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
82
+ - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
83
+ - `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
84
+ - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
85
+ - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
86
+ - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
87
+
88
+ The names and parameters should be self-explanatory.
89
+
64
90
  ## Theme support
65
91
 
92
+ Below shows the latest themes that I have tested.
93
+ They are not updated that often, and the plugin should generally work for other of theme versions too.
94
+
66
95
  Theme | Theme version | Plugin version | Status
67
96
  --- | --- | --- | ---
68
- mkdocs-material | 9.1.21 | 0.0.1 | works
69
- mkdocs (default) | 1.5.2 | 0.0.2 | works
70
- readthedocs | 1.5.2 | 0.0.2 | works
97
+ mkdocs-material | 9.5.34 | 0.0.4 | works
98
+ mkdocs (default) | 1.6.1 | 0.0.4 | works
99
+ readthedocs | 1.6.1 | 0.0.4 | works
71
100
 
72
101
  Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
73
102
 
@@ -85,6 +114,16 @@ Test mkdocs theme:
85
114
 
86
115
  ## Notable changes
87
116
 
117
+ ### Version 0.0.5
118
+
119
+ - Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
120
+
121
+ ### Version 0.0.4
122
+
123
+ - Export API via `MkdocsToggleSidebarPlugin` object.
124
+ This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
125
+ - Added `toggle_button` option and implemented it for Material theme.
126
+
88
127
  ### Version 0.0.3
89
128
 
90
129
  - Changed internal API:
@@ -42,13 +42,42 @@ Key | Action
42
42
  `m` | toggle navigation **m**enu
43
43
  `t` | toggle **T**OC
44
44
 
45
+ For some themes like `readthedocs` navigation and TOC are combined.
46
+ In this case the state of TOC is ignored, and only calls for navigation (or all) are interpreted.
47
+
48
+ ### Toggle button
49
+
50
+ 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.
51
+ It is usually in the nav or the top bar.
52
+ Clicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).
53
+ By leaving the field empty or setting it to `none`, no button is added.
54
+
55
+ ### Exported API functions
56
+
57
+ This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
58
+ 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`.
59
+
60
+ In short there are:
61
+
62
+ - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
63
+ - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
64
+ - `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
65
+ - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
66
+ - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
67
+ - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
68
+
69
+ The names and parameters should be self-explanatory.
70
+
45
71
  ## Theme support
46
72
 
73
+ Below shows the latest themes that I have tested.
74
+ They are not updated that often, and the plugin should generally work for other of theme versions too.
75
+
47
76
  Theme | Theme version | Plugin version | Status
48
77
  --- | --- | --- | ---
49
- mkdocs-material | 9.1.21 | 0.0.1 | works
50
- mkdocs (default) | 1.5.2 | 0.0.2 | works
51
- readthedocs | 1.5.2 | 0.0.2 | works
78
+ mkdocs-material | 9.5.34 | 0.0.4 | works
79
+ mkdocs (default) | 1.6.1 | 0.0.4 | works
80
+ readthedocs | 1.6.1 | 0.0.4 | works
52
81
 
53
82
  Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
54
83
 
@@ -66,6 +95,16 @@ Test mkdocs theme:
66
95
 
67
96
  ## Notable changes
68
97
 
98
+ ### Version 0.0.5
99
+
100
+ - Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
101
+
102
+ ### Version 0.0.4
103
+
104
+ - Export API via `MkdocsToggleSidebarPlugin` object.
105
+ This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
106
+ - Added `toggle_button` option and implemented it for Material theme.
107
+
69
108
  ### Version 0.0.3
70
109
 
71
110
  - Changed internal API:
@@ -1,9 +1,9 @@
1
1
  [metadata]
2
2
  name = mkdocs-toggle-sidebar-plugin
3
- version = 0.0.3
3
+ version = 0.0.5
4
4
  author = six-two
5
5
  author_email = pip@six-two.dev
6
- description = Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
6
+ description = Add keybindings to toggle the navigation and table of contents sidebars
7
7
  long_description = file: README.md
8
8
  long_description_content_type = text/markdown
9
9
  url = https://github.com/six-two/mkdocs-toggle-sidebar-plugin
@@ -1,18 +1,21 @@
1
1
  import os
2
2
  import logging
3
3
  # pip dependency
4
- from mkdocs.plugins import BasePlugin
4
+ from mkdocs.plugins import BasePlugin, get_plugin_logger
5
5
  from mkdocs.config.defaults import MkDocsConfig
6
6
  from mkdocs.config.base import Config
7
7
  from mkdocs.config.config_options import Type, ExtraScriptValue
8
+ from mkdocs.exceptions import PluginError
8
9
 
9
- LOGGER = logging.getLogger("mkdocs.plugins.toggle-sidebar")
10
+ LOGGER = get_plugin_logger(__name__)
10
11
  SCRIPT_DIR = os.path.dirname(__file__)
12
+ ALLOWED_TOGGLE_BUTTON_VALUES = ["none", "navigation", "toc", "all"]
11
13
 
12
14
  class PluginConfig(Config):
13
15
  enabled = Type(bool, default=True)
14
16
  show_toc_by_default = Type(bool, default=True)
15
17
  show_navigation_by_default = Type(bool, default=True)
18
+ toggle_button = Type(str, default="none")
16
19
  async_ = Type(bool, default=True)
17
20
  javascript = Type(str, default="assets/javascripts/toggle-sidebar.js")
18
21
 
@@ -39,6 +42,9 @@ class Plugin(BasePlugin[PluginConfig]):
39
42
  custom_script.async_ = True
40
43
 
41
44
  config.extra_javascript.append(custom_script)
45
+
46
+ if self.config.toggle_button not in ALLOWED_TOGGLE_BUTTON_VALUES:
47
+ raise PluginError(f"Unexpected value for 'toggle_button': '{self.config.toggle_button}'. Allowed values are {', '.join(ALLOWED_TOGGLE_BUTTON_VALUES)}")
42
48
  return config
43
49
 
44
50
 
@@ -61,6 +67,7 @@ class Plugin(BasePlugin[PluginConfig]):
61
67
  data = data.replace("THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER", self.theme_function_definitions)
62
68
  data = data.replace("TOC_DEFAULT_PLACEHOLDER", "true" if self.config.show_toc_by_default else "false")
63
69
  data = data.replace("NAVIGATION_DEFAULT_PLACEHOLDER", "true" if self.config.show_toc_by_default else "false")
70
+ data = data.replace("TOGGLE_BUTTON_PLACEHOLDER", self.config.toggle_button)
64
71
  with open(target_path, "w") as f:
65
72
  f.write(data)
66
73
 
@@ -0,0 +1,67 @@
1
+ const setCombinedVisibility = (showNavigation, showTOC) => {
2
+ // Hide the button when on mobile (and menu us shown as hamburger menu anyways).
3
+ // The exact max-width is taken from the styling of the 'body > header > nav > a' element
4
+
5
+ let style = `
6
+ .mkdocs-toggle-sidebar-button {
7
+ cursor: pointer;
8
+ margin-right: 5px;
9
+ margin-left: 1rem;
10
+ }
11
+
12
+ @media screen and (max-width: 76.1875em) {
13
+ .mkdocs-toggle-sidebar-button {
14
+ display: none;
15
+ }
16
+ }
17
+ `;
18
+ // The TOC has a different break point than the navigation.
19
+ // It can be seen on the nav.md-nav--secondary:nth-child(1) element (60em)
20
+ // If the screen is smaller, it is shown in the navigation section if you click the nested hamburger menu
21
+ if (!showTOC) {
22
+ style += `
23
+ @media screen and (min-width: 60em) {
24
+ div.md-sidebar.md-sidebar--secondary {
25
+ display: none;
26
+ }
27
+ }
28
+ `;
29
+ }
30
+
31
+ // We always have to show the navigation in mobile view, otherwise the hamburger menu is broken
32
+ if (!showNavigation) {
33
+ style += `
34
+ @media screen and (min-width: 76.1875em) {
35
+ div.md-sidebar.md-sidebar--primary {
36
+ display: none;
37
+ }
38
+ }
39
+ `;
40
+ }
41
+
42
+ return style;
43
+ }
44
+
45
+ const addToggleButton = (toggleNavigation, toggleTOC) => {
46
+ const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
47
+ toggleBtn.classList.add("md-icon");
48
+
49
+ const titleElement = document.querySelector(".md-header__title");
50
+ if (titleElement) {
51
+ titleElement.parentNode.insertBefore(toggleBtn, titleElement.nextSibling);
52
+ } else {
53
+ console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
54
+ }
55
+ }
56
+
57
+ const registerKeyboardEventHandler = () => {
58
+ // Custom key handlers: SEE https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=key+bind#docsjavascriptsshortcutsjs
59
+ keyboard$.subscribe(key => {
60
+ if (key.mode === "global") {
61
+ if (coreEventListenerLogic(key.type)) {
62
+ // event handled, stop propagation
63
+ key.claim();
64
+ }
65
+ }
66
+ });
67
+ }
@@ -0,0 +1,69 @@
1
+ const setCombinedVisibility = (showNavigation, showTOC) => {
2
+ let style = `
3
+ .mkdocs-toggle-sidebar-container {
4
+ margin: auto 0;
5
+ }
6
+
7
+ .mkdocs-toggle-sidebar-button {
8
+ cursor: pointer;
9
+ width: 1.5em;
10
+ padding-bottom: 2px;
11
+ }
12
+
13
+ .mkdocs-toggle-sidebar-button svg {
14
+ fill: white;
15
+ }
16
+ `;
17
+
18
+ if (!showTOC) {
19
+ style += `
20
+ div.col-md-3 {
21
+ display: none;
22
+ }
23
+
24
+ div.col-md-9 {
25
+ max-width: 100%;
26
+ flex-basis: 100%;
27
+ }
28
+ `;
29
+ }
30
+
31
+ if (!showNavigation) {
32
+ style += `
33
+ ul.navbar-nav:nth-child(1) {
34
+ display: none;
35
+ }
36
+ `
37
+ }
38
+
39
+ return style;
40
+ }
41
+
42
+ const addToggleButton = (toggleNavigation, toggleTOC) => {
43
+ const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
44
+ const li = document.createElement("li");
45
+ li.className = "nav-item mkdocs-toggle-sidebar-container";
46
+ li.append(toggleBtn);
47
+
48
+ let titleElement = document.querySelector("#navbar-collapse > ul.nav.navbar-nav.ms-md-auto");
49
+ if (!titleElement) {
50
+ // This worked in older versions, but not anymore. Since the default check failed, maybe we are in an old version?
51
+ titleElement = document.querySelector("#navbar-collapse > ul.nav.navbar-nav.ml-auto");
52
+ }
53
+ if (titleElement) {
54
+ titleElement.insertBefore(li, titleElement.firstChild);
55
+ } else {
56
+ console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
57
+ }
58
+ }
59
+
60
+ const registerKeyboardEventHandler = () => {
61
+ // Native HTML key event handling
62
+ document.addEventListener("keydown", (event => {
63
+ if (coreEventListenerLogic(event.key)) {
64
+ // event handled, stop propagation
65
+ event.preventDefault();
66
+ event.stopPropagation();
67
+ }
68
+ }));
69
+ }
@@ -0,0 +1,67 @@
1
+ const setCombinedVisibility = (showNavigation, showTOC) => {
2
+ // Navigation and TOC are merged so we just pick one of the values and trust them
3
+ // @TODO: add support for combined bars in toggle-sidebar.js?
4
+ let style = `
5
+ .mkdocs-toggle-sidebar-button {
6
+ cursor: pointer;
7
+ width: 1em;
8
+ fill: darkgray;
9
+ display: flex;
10
+ margin-right: 5px;
11
+ }
12
+
13
+ /* Hide toggle button in mobile view */
14
+ @media screen and (max-width: 768px) {
15
+ .wy-breadcrumbs > li.mkdocs-toggle-sidebar-container {
16
+ display: none;
17
+ }
18
+ }
19
+ `;
20
+ if (!showNavigation) {
21
+ // We can not hide the contents in mobile view, since then the hamburger menu would be empty
22
+ style += `
23
+ @media screen and (min-width: 768px) {
24
+ section.wy-nav-content-wrap {
25
+ margin-left: 0px;
26
+ }
27
+
28
+ nav.wy-nav-side, div.rst-versions {
29
+ display: none;
30
+ }
31
+
32
+ div.wy-nav-content {
33
+ max-width: 1100px;
34
+ }
35
+ }
36
+ `;
37
+ }
38
+
39
+ return style;
40
+
41
+ }
42
+
43
+ const addToggleButton = (toggleNavigation, toggleTOC) => {
44
+ const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
45
+ toggleBtn.title = "Toggle Navigation"; // There is only one real sidebar, so we use this name for consistency
46
+ const li = document.createElement("li");
47
+ li.className = "mkdocs-toggle-sidebar-container";
48
+ li.append(toggleBtn);
49
+
50
+ const titleElement = document.querySelector("ul.wy-breadcrumbs");
51
+ if (titleElement) {
52
+ titleElement.insertBefore(li, titleElement.firstChild);
53
+ } else {
54
+ console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
55
+ }
56
+ }
57
+
58
+ const registerKeyboardEventHandler = () => {
59
+ // Native HTML key event handling
60
+ document.addEventListener("keydown", (event => {
61
+ if (coreEventListenerLogic(event.key)) {
62
+ // event handled, stop propagation
63
+ event.preventDefault();
64
+ event.stopPropagation();
65
+ }
66
+ }));
67
+ }
@@ -2,6 +2,7 @@
2
2
  const customDynamicStyle = document.createElement("style");
3
3
  document.head.appendChild(customDynamicStyle);
4
4
 
5
+ const TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING = "[mkdocs-toggle-sidebar-plugin] Reference element for inserting 'toggle_button' not found. This version of the plugin may not be compatible with this version of the theme. Try updating both to the latest version. If that fails, you can open an GitHub issue.";
5
6
 
6
7
  const loadBool = (name, default_value) => {
7
8
  const value = localStorage.getItem(`TOGGLE_SIDEBAR_${name}`);
@@ -32,6 +33,10 @@
32
33
  saveBool("TOC", newTOC);
33
34
  }
34
35
 
36
+ _setVisibility(newNavigation, newTOC);
37
+ }
38
+
39
+ const _setVisibility = (newNavigation, newTOC) => {
35
40
  console.debug(`Setting new visibility: navigation=${newNavigation}, TOC=${newTOC}`);
36
41
  // combine this into one operation, so that it is more efficient (for toggling both) and easier to code with dynamic CSS generation
37
42
  customDynamicStyle.innerHTML = setCombinedVisibility(newNavigation, newTOC);
@@ -63,7 +68,55 @@
63
68
  window.addEventListener("load", () => {
64
69
  console.log("The mkdocs-toggle-sidebar-plugin is installed. It adds the following key bindings:\n T -> toggle table of contents sidebar\n M -> toggle navigation menu sidebar\n B -> toggle both sidebars (TOC and navigation)");
65
70
 
71
+ const toggle_button = "TOGGLE_BUTTON_PLACEHOLDER";
72
+ if (toggle_button == "none") {
73
+ // do nothing
74
+ } else if (toggle_button == "navigation") {
75
+ addToggleButton(true, false);
76
+ } else if (toggle_button == "toc") {
77
+ addToggleButton(false, true);
78
+ } else if (toggle_button == "all") {
79
+ addToggleButton(true, true);
80
+ } else {
81
+ console.error(`[mkdocs-toggle-sidebar-plugin] Unknown value for toggle_button: '${toggleButtonType}'`);
82
+ }
83
+
66
84
  registerKeyboardEventHandler();
67
85
  customDynamicStyle.innerHTML = setCombinedVisibility(loadNavigationState(), loadTocState());
68
86
  });
87
+
88
+ const createDefaultToggleButton = (toggleNavigation, toggleTOC) => {
89
+ const toggleBtn = document.createElement("div");
90
+ toggleBtn.className = "mkdocs-toggle-sidebar-button";
91
+ toggleBtn.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"></path></svg>`;
92
+ if (toggleNavigation && toggleTOC) {
93
+ toggleBtn.title = "Toggle Navigation and Table of Contents";
94
+ } else if (toggleNavigation) {
95
+ toggleBtn.title = "Toggle Navigation";
96
+ } else if (toggleTOC) {
97
+ toggleBtn.title = "Toggle Table of Contents";
98
+ }
99
+ toggleBtn.addEventListener("click", () => toggleVisibility(toggleNavigation, toggleTOC));
100
+ return toggleBtn;
101
+ };
102
+
103
+ // Export functions that the user can call to modify the state
104
+ window.MkdocsToggleSidebarPlugin = {
105
+ setNavigationVisibility: (show) => {
106
+ saveBool("NAVIGATION", show);
107
+ _setVisibility(show, loadTocState());
108
+ },
109
+ setTocVisibility: (show) => {
110
+ saveBool("TOC", show);
111
+ _setVisibility(loadNavigationState(), show);
112
+ },
113
+ setAllVisibility: (showNavigation, showTOC) => {
114
+ saveBool("NAVIGATION", showNavigation);
115
+ saveBool("TOC", showTOC);
116
+ _setVisibility(showNavigation, showTOC);
117
+ },
118
+ toggleNavigationVisibility: () => toggleVisibility(true, false),
119
+ toggleTocVisibility: () => toggleVisibility(false, true),
120
+ toggleAllVisibility: () => toggleVisibility(true, true)
121
+ };
69
122
  }());
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: mkdocs-toggle-sidebar-plugin
3
- Version: 0.0.3
4
- Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
3
+ Version: 0.0.5
4
+ Summary: Add keybindings to toggle the navigation and table of contents sidebars
5
5
  Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
6
6
  Author: six-two
7
7
  Author-email: pip@six-two.dev
@@ -61,13 +61,42 @@ Key | Action
61
61
  `m` | toggle navigation **m**enu
62
62
  `t` | toggle **T**OC
63
63
 
64
+ For some themes like `readthedocs` navigation and TOC are combined.
65
+ In this case the state of TOC is ignored, and only calls for navigation (or all) are interpreted.
66
+
67
+ ### Toggle button
68
+
69
+ 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.
70
+ It is usually in the nav or the top bar.
71
+ Clicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).
72
+ By leaving the field empty or setting it to `none`, no button is added.
73
+
74
+ ### Exported API functions
75
+
76
+ This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
77
+ 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`.
78
+
79
+ In short there are:
80
+
81
+ - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
82
+ - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
83
+ - `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
84
+ - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
85
+ - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
86
+ - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
87
+
88
+ The names and parameters should be self-explanatory.
89
+
64
90
  ## Theme support
65
91
 
92
+ Below shows the latest themes that I have tested.
93
+ They are not updated that often, and the plugin should generally work for other of theme versions too.
94
+
66
95
  Theme | Theme version | Plugin version | Status
67
96
  --- | --- | --- | ---
68
- mkdocs-material | 9.1.21 | 0.0.1 | works
69
- mkdocs (default) | 1.5.2 | 0.0.2 | works
70
- readthedocs | 1.5.2 | 0.0.2 | works
97
+ mkdocs-material | 9.5.34 | 0.0.4 | works
98
+ mkdocs (default) | 1.6.1 | 0.0.4 | works
99
+ readthedocs | 1.6.1 | 0.0.4 | works
71
100
 
72
101
  Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
73
102
 
@@ -85,6 +114,16 @@ Test mkdocs theme:
85
114
 
86
115
  ## Notable changes
87
116
 
117
+ ### Version 0.0.5
118
+
119
+ - Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
120
+
121
+ ### Version 0.0.4
122
+
123
+ - Export API via `MkdocsToggleSidebarPlugin` object.
124
+ This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
125
+ - Added `toggle_button` option and implemented it for Material theme.
126
+
88
127
  ### Version 0.0.3
89
128
 
90
129
  - Changed internal API:
@@ -1,32 +0,0 @@
1
- const setCombinedVisibility = (showNavigation, showTOC) => {
2
- let style = "";
3
- if (!showTOC) {
4
- style += `
5
- div.md-sidebar.md-sidebar--secondary {
6
- display: none;
7
- }
8
- `;
9
- }
10
-
11
- if (!showNavigation) {
12
- style += `
13
- div.md-sidebar.md-sidebar--primary {
14
- display: none;
15
- }
16
- `
17
- }
18
-
19
- return style;
20
- }
21
-
22
- const registerKeyboardEventHandler = () => {
23
- // Custom key handlers: SEE https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=key+bind#docsjavascriptsshortcutsjs
24
- keyboard$.subscribe(key => {
25
- if (key.mode === "global") {
26
- if (coreEventListenerLogic(key.type)) {
27
- // event handled, stop propagation
28
- key.claim();
29
- }
30
- }
31
- });
32
- }
@@ -1,36 +0,0 @@
1
- const setCombinedVisibility = (showNavigation, showTOC) => {
2
- let style = "";
3
- if (!showTOC) {
4
- style += `
5
- div.col-md-3 {
6
- display: none;
7
- }
8
-
9
- div.col-md-9 {
10
- max-width: 100%;
11
- flex-basis: 100%;
12
- }
13
- `;
14
- }
15
-
16
- if (!showNavigation) {
17
- style += `
18
- ul.navbar-nav:nth-child(1) {
19
- display: none;
20
- }
21
- `
22
- }
23
-
24
- return style;
25
- }
26
-
27
- const registerKeyboardEventHandler = () => {
28
- // Native HTML key event handling
29
- document.addEventListener("keydown", (event => {
30
- if (coreEventListenerLogic(event.key)) {
31
- // event handled, stop propagation
32
- event.preventDefault();
33
- event.stopPropagation();
34
- }
35
- }));
36
- }
@@ -1,33 +0,0 @@
1
- const setCombinedVisibility = (showNavigation, showTOC) => {
2
- // Navigation and TOC are merged so we just pick one of the values and trust them
3
- // @TODO: add support for combined bars in toggle-sidebar.js?
4
- if (showNavigation) {
5
- return "";
6
- } else {
7
- return `
8
- section.wy-nav-content-wrap {
9
- margin-left: 0px;
10
- }
11
-
12
- nav.wy-nav-side, div.rst-versions {
13
- display: none;
14
- }
15
-
16
- div.wy-nav-content {
17
- max-width: 1100px;
18
- }
19
- `;
20
- }
21
-
22
- }
23
-
24
- const registerKeyboardEventHandler = () => {
25
- // Native HTML key event handling
26
- document.addEventListener("keydown", (event => {
27
- if (coreEventListenerLogic(event.key)) {
28
- // event handled, stop propagation
29
- event.preventDefault();
30
- event.stopPropagation();
31
- }
32
- }));
33
- }