mkdocs-toggle-sidebar-plugin 0.0.2__tar.gz → 0.0.4__tar.gz

mkdocs_toggle_sidebar_plugin-0.0.4/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.1
+Name: mkdocs-toggle-sidebar-plugin
+Version: 0.0.4
+Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
+Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
+Author: six-two
+Author-email: pip@six-two.dev
+License: MIT License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4.0
+
+# mkdocs-toggle-sidebar-plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/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.
+
+### 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.
+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.
+
+### Note to self
+
+Test mkdocs-material theme:
+```bash
+./serve.sh
+```
+
+Test mkdocs theme:
+```bash
+./serve.sh --theme mkdocs
+```
+
+## Notable changes
+
+### 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.

mkdocs_toggle_sidebar_plugin-0.0.4/README.md

@@ -0,0 +1,115 @@
+# mkdocs-toggle-sidebar-plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/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.
+
+### 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.
+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.
+
+### Note to self
+
+Test mkdocs-material theme:
+```bash
+./serve.sh
+```
+
+Test mkdocs theme:
+```bash
+./serve.sh --theme mkdocs
+```
+
+## Notable changes
+
+### 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.

{mkdocs-toggle-sidebar-plugin-0.0.2 → mkdocs_toggle_sidebar_plugin-0.0.4}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-toggle-sidebar-plugin
-version = 0.0.2
+version = 0.0.4
 author = six-two
 author_email = pip@six-two.dev
 description = Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes

{mkdocs-toggle-sidebar-plugin-0.0.2 → mkdocs_toggle_sidebar_plugin-0.0.4}/src/mkdocs_toggle_sidebar_plugin/__init__.py

@@ -1,18 +1,21 @@
 import os
 import logging
 # pip dependency
-from mkdocs.plugins import BasePlugin
+from mkdocs.plugins import BasePlugin, get_plugin_logger
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.config.base import Config
 from mkdocs.config.config_options import Type, ExtraScriptValue
+from mkdocs.exceptions import PluginError
 
-LOGGER = logging.getLogger("mkdocs.plugins.toggle-sidebar")
+LOGGER = get_plugin_logger(__name__)
 SCRIPT_DIR = os.path.dirname(__file__)
+ALLOWED_TOGGLE_BUTTON_VALUES = ["none", "navigation", "toc", "all"]
 
 class PluginConfig(Config):
     enabled = Type(bool, default=True)
     show_toc_by_default = Type(bool, default=True)
     show_navigation_by_default = Type(bool, default=True)
+    toggle_button = Type(str, default="none")
     async_ = Type(bool, default=True)
     javascript = Type(str, default="assets/javascripts/toggle-sidebar.js")
 
@@ -39,6 +42,9 @@ class Plugin(BasePlugin[PluginConfig]):
                 custom_script.async_ = True
             
             config.extra_javascript.append(custom_script)
+        
+        if self.config.toggle_button not in ALLOWED_TOGGLE_BUTTON_VALUES:
+            raise PluginError(f"Unexpected value for 'toggle_button': '{self.config.toggle_button}'. Allowed values are {', '.join(ALLOWED_TOGGLE_BUTTON_VALUES)}")
         return config
 
 
@@ -61,6 +67,7 @@ class Plugin(BasePlugin[PluginConfig]):
                 data = data.replace("THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER", self.theme_function_definitions)
                 data = data.replace("TOC_DEFAULT_PLACEHOLDER", "true" if self.config.show_toc_by_default else "false")
                 data = data.replace("NAVIGATION_DEFAULT_PLACEHOLDER", "true" if self.config.show_toc_by_default else "false")
+                data = data.replace("TOGGLE_BUTTON_PLACEHOLDER", self.config.toggle_button)
                 with open(target_path, "w") as f:
                     f.write(data)
 

mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin/material.js

@@ -0,0 +1,61 @@
+const setCombinedVisibility = (showNavigation, showTOC) => {
+    let style = `
+.mkdocs-toggle-sidebar-button {
+    cursor: pointer;
+    margin-right: 5px;
+    margin-left: 1rem;
+}
+
+/*
+Hide the button when on mobile (and menu us shown as hamburger menu anyways).
+The exact max-width is taken from the styling of the 'body > header > nav > a' element
+*/
+
+@media screen and (max-width: 76.1875em) {
+    .mkdocs-toggle-sidebar-button {
+        display: none;
+    }
+}
+`;
+    if (!showTOC) {
+        style += `
+div.md-sidebar.md-sidebar--secondary {
+    display: none;
+}
+`;
+    }
+
+    if (!showNavigation) {
+        style += `
+div.md-sidebar.md-sidebar--primary {
+    display: none;
+}
+`
+    }
+
+    return style;
+}
+
+const addToggleButton = (toggleNavigation, toggleTOC) => {
+    const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
+    toggleBtn.classList.add("md-icon");
+  
+    const titleElement = document.querySelector(".md-header__title");
+    if (titleElement) {
+        titleElement.parentNode.insertBefore(toggleBtn, titleElement.nextSibling);  
+    } else {
+        console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
+    }
+}
+
+const registerKeyboardEventHandler = () => {
+    // Custom key handlers: SEE https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=key+bind#docsjavascriptsshortcutsjs
+    keyboard$.subscribe(key => {
+        if (key.mode === "global") {
+            if (coreEventListenerLogic(key.type)) {
+                // event handled, stop propagation
+                key.claim();
+            }
+        }
+    });
+}

mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin/mkdocs.js

@@ -0,0 +1,69 @@
+const setCombinedVisibility = (showNavigation, showTOC) => {
+    let style = `
+.mkdocs-toggle-sidebar-container {
+    margin: auto 0;
+}
+
+.mkdocs-toggle-sidebar-button {
+    cursor: pointer;
+    width: 1.5em;
+    padding-bottom: 2px;
+}
+
+.mkdocs-toggle-sidebar-button svg {
+    fill: white;
+}
+`;
+
+    if (!showTOC) {
+        style += `
+div.col-md-3 {
+    display: none;
+}
+
+div.col-md-9 {
+    max-width: 100%;
+    flex-basis: 100%;
+}
+`;
+    }
+
+    if (!showNavigation) {
+        style += `
+ul.navbar-nav:nth-child(1) {
+    display: none;
+}
+`
+    }
+
+    return style;
+}
+
+const addToggleButton = (toggleNavigation, toggleTOC) => {
+    const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
+    const li = document.createElement("li");
+    li.className = "nav-item mkdocs-toggle-sidebar-container";
+    li.append(toggleBtn);
+  
+    let titleElement = document.querySelector("#navbar-collapse > ul.nav.navbar-nav.ms-md-auto");
+    if (!titleElement) {
+        // This worked in older versions, but not anymore. Since the default check failed, maybe we are in an old version?
+        titleElement = document.querySelector("#navbar-collapse > ul.nav.navbar-nav.ml-auto");
+    }
+    if (titleElement) {
+        titleElement.insertBefore(li, titleElement.firstChild);
+    } else {
+        console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
+    }
+}
+
+const registerKeyboardEventHandler = () => {
+    // Native HTML key event handling
+    document.addEventListener("keydown", (event => {
+        if (coreEventListenerLogic(event.key)) {
+            // event handled, stop propagation
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }));
+}

mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin/readthedocs.js

@@ -0,0 +1,67 @@
+const setCombinedVisibility = (showNavigation, showTOC) => {
+    // Navigation and TOC are merged so we just pick one of the values and trust them
+    // @TODO: add support for combined bars in toggle-sidebar.js?
+    let style = `
+.mkdocs-toggle-sidebar-button {
+    cursor: pointer;
+    width: 1em;
+    fill: darkgray;
+    display: flex;
+    margin-right: 5px;
+}
+
+/* Hide toggle button in mobile view */
+@media screen and (max-width: 768px) {
+    .wy-breadcrumbs > li.mkdocs-toggle-sidebar-container {
+        display: none;
+    }
+}
+`;
+    if (!showNavigation) {
+        // We can not hide the contents in mobile view, since then the hamburger menu would be empty
+        style += `
+@media screen and (min-width: 768px) {
+    section.wy-nav-content-wrap {
+        margin-left: 0px;
+    }
+
+    nav.wy-nav-side, div.rst-versions {
+        display: none;
+    }
+
+    div.wy-nav-content {
+        max-width: 1100px;
+    }
+}
+`;
+    }
+
+    return style;
+    
+}
+
+const addToggleButton = (toggleNavigation, toggleTOC) => {
+    const toggleBtn = createDefaultToggleButton(toggleNavigation, toggleTOC);
+    toggleBtn.title = "Toggle Navigation"; // There is only one real sidebar, so we use this name for consistency
+    const li = document.createElement("li");
+    li.className = "mkdocs-toggle-sidebar-container";
+    li.append(toggleBtn);
+
+    const titleElement = document.querySelector("ul.wy-breadcrumbs");
+    if (titleElement) {
+        titleElement.insertBefore(li, titleElement.firstChild);  
+    } else {
+        console.warn(TOGGLE_BUTTON_REFERENCE_ELEMENT_NOT_FOUND_WARNING);
+    }
+}
+
+const registerKeyboardEventHandler = () => {
+    // Native HTML key event handling
+    document.addEventListener("keydown", (event => {
+        if (coreEventListenerLogic(event.key)) {
+            // event handled, stop propagation
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }));
+}

mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js

@@ -0,0 +1,122 @@
+(function() {
+    const customDynamicStyle = document.createElement("style");
+    document.head.appendChild(customDynamicStyle);
+
+    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.";
+
+    const loadBool = (name, default_value) => {
+        const value = localStorage.getItem(`TOGGLE_SIDEBAR_${name}`);
+        if (value == null) {
+            return default_value;
+        } else {
+            return value == "1";
+        }
+    }
+
+    const loadNavigationState = () => loadBool("NAVIGATION", NAVIGATION_DEFAULT_PLACEHOLDER);
+    const loadTocState = () => loadBool("TOC", TOC_DEFAULT_PLACEHOLDER);
+
+    const saveBool = (name, value) => {
+        localStorage.setItem(`TOGGLE_SIDEBAR_${name}`, value ? "1" : "0");
+    }
+
+    const toggleVisibility = (toggleNavigation, toggleTOC) => {
+        let newNavigation = loadNavigationState();
+        let newTOC = loadTocState();
+        
+        if (toggleNavigation) {
+            newNavigation = !newNavigation;
+            saveBool("NAVIGATION", newNavigation);
+        }
+        if (toggleTOC) {
+            newTOC = !newTOC;
+            saveBool("TOC", newTOC);
+        }
+        
+        _setVisibility(newNavigation, newTOC);
+    }
+
+    const _setVisibility = (newNavigation, newTOC) => {
+        console.debug(`Setting new visibility: navigation=${newNavigation}, TOC=${newTOC}`);
+        // combine this into one operation, so that it is more efficient (for toggling both) and easier to code with dynamic CSS generation
+        customDynamicStyle.innerHTML = setCombinedVisibility(newNavigation, newTOC);
+    }
+
+    // START OF INCLUDE
+    // This gets replaced with the definitions of: 
+    // - setCombinedVisibility(showNavigation: bool, showTOC: bool) -> string (dynamic CSS)
+    // - registerKeyboardEventHandler() -> void
+    THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER
+    // END OF INCLUDE
+
+    // argument: string, returns true if the key was handled and the event should be marked as already handled
+    const coreEventListenerLogic = (keyChar) => {
+        if (keyChar === "t") {
+            toggleVisibility(false, true);
+            return true;
+        } else if (keyChar === "m") {
+            toggleVisibility(true, false);
+            return true;
+        } else if (keyChar === "b") {
+            toggleVisibility(true, true);
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    window.addEventListener("load", () => {
+        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)");
+
+        const toggle_button = "TOGGLE_BUTTON_PLACEHOLDER";
+        if (toggle_button == "none") {
+            // do nothing
+        } else if (toggle_button == "navigation") {
+            addToggleButton(true, false);
+        } else if (toggle_button == "toc") {
+            addToggleButton(false, true);
+        } else if (toggle_button == "all") {
+            addToggleButton(true, true);
+        } else {
+            console.error(`[mkdocs-toggle-sidebar-plugin] Unknown value for toggle_button: '${toggleButtonType}'`);
+        }
+
+        registerKeyboardEventHandler();
+        customDynamicStyle.innerHTML = setCombinedVisibility(loadNavigationState(), loadTocState());
+    });
+
+    const createDefaultToggleButton = (toggleNavigation, toggleTOC) => {
+        const toggleBtn = document.createElement("div");
+        toggleBtn.className = "mkdocs-toggle-sidebar-button";
+        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>`;
+        if (toggleNavigation && toggleTOC) {
+            toggleBtn.title = "Toggle Navigation and Table of Contents";
+        } else if (toggleNavigation) {
+            toggleBtn.title = "Toggle Navigation";
+        } else if (toggleTOC) {
+            toggleBtn.title = "Toggle Table of Contents";
+        }
+        toggleBtn.addEventListener("click", () => toggleVisibility(toggleNavigation, toggleTOC));
+        return toggleBtn;
+    };
+
+    // Export functions that the user can call to modify the state
+    window.MkdocsToggleSidebarPlugin = {
+        setNavigationVisibility: (show) => {
+            saveBool("NAVIGATION", show);
+            _setVisibility(show, loadTocState());
+        },
+        setTocVisibility: (show) => {
+            saveBool("TOC", show);
+            _setVisibility(loadNavigationState(), show);
+        },
+        setAllVisibility: (showNavigation, showTOC) => {
+            saveBool("NAVIGATION", showNavigation);
+            saveBool("TOC", showTOC);
+            _setVisibility(showNavigation, showTOC);
+        },
+        toggleNavigationVisibility: () => toggleVisibility(true, false),
+        toggleTocVisibility: () => toggleVisibility(false, true),
+        toggleAllVisibility: () => toggleVisibility(true, true)
+    };
+}());

mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.1
+Name: mkdocs-toggle-sidebar-plugin
+Version: 0.0.4
+Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
+Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
+Author: six-two
+Author-email: pip@six-two.dev
+License: MIT License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4.0
+
+# mkdocs-toggle-sidebar-plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/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.
+
+### 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.
+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.
+
+### Note to self
+
+Test mkdocs-material theme:
+```bash
+./serve.sh
+```
+
+Test mkdocs theme:
+```bash
+./serve.sh --theme mkdocs
+```
+
+## Notable changes
+
+### 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.

mkdocs-toggle-sidebar-plugin-0.0.2/PKG-INFO

@@ -1,91 +0,0 @@
-Metadata-Version: 2.1
-Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.2
-Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
-Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
-Author: six-two
-Author-email: pip@six-two.dev
-License: MIT License
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-# mkdocs-toggle-sidebar-plugin
-
-[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
-![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
-![Python versions](https://img.shields.io/pypi/pyversions/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`
-
-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
-
-## Theme support
-
-Theme            | Theme version | Plugin version | Status
----              | ---           | ---            | ---
-mkdocs-material  | 9.1.21        | 0.0.1          | works
-mkdocs (default) | 1.5.2         | 0.0.2          | works
-readthedocs      | 1.5.2         | 0.0.2          | works
-
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
-
-### Note to self
-
-Test mkdocs-material theme:
-```bash
-./serve.sh
-```
-
-Test mkdocs theme:
-```bash
-./serve.sh --theme mkdocs
-```
-
-## Notable changes
-
-### Version 0.0.2
-
-- Added support for `mkdocs` and `readthedocs` theme.
-
-### Version 0.0.1
-
-- Prototype with `mkdocs-material` implementation.

mkdocs-toggle-sidebar-plugin-0.0.2/README.md

@@ -1,73 +0,0 @@
-# mkdocs-toggle-sidebar-plugin
-
-[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
-![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
-![Python versions](https://img.shields.io/pypi/pyversions/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`
-
-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
-
-## Theme support
-
-Theme            | Theme version | Plugin version | Status
----              | ---           | ---            | ---
-mkdocs-material  | 9.1.21        | 0.0.1          | works
-mkdocs (default) | 1.5.2         | 0.0.2          | works
-readthedocs      | 1.5.2         | 0.0.2          | works
-
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
-
-### Note to self
-
-Test mkdocs-material theme:
-```bash
-./serve.sh
-```
-
-Test mkdocs theme:
-```bash
-./serve.sh --theme mkdocs
-```
-
-## Notable changes
-
-### Version 0.0.2
-
-- Added support for `mkdocs` and `readthedocs` theme.
-
-### Version 0.0.1
-
-- Prototype with `mkdocs-material` implementation.

mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin/material.js

@@ -1,25 +0,0 @@
-const setVisibility = (query_string, show) => {
-    for (let element of document.querySelectorAll(query_string)) {
-        element.style.display = show ? "block" : "none";
-    }
-}
-
-const setTocVisibility = (visible) => {
-    setVisibility("div.md-sidebar.md-sidebar--secondary", visible);
-}
-
-const setNavigationVisibility = (visible) => {
-    setVisibility("div.md-sidebar.md-sidebar--primary", visible);
-}
-
-const registerKeyboardEventHandler = () => {
-    // Custom key handlers: SEE https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=key+bind#docsjavascriptsshortcutsjs
-    keyboard$.subscribe(key => {
-        if (key.mode === "global") {
-            if (coreEventListenerLogic(key.type)) {
-                // event handled, stop propagation
-                key.claim();
-            }
-        }
-    });
-}

mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin/mkdocs.js

@@ -1,28 +0,0 @@
-const setVisibility = (query_string, show) => {
-    for (let element of document.querySelectorAll(query_string)) {
-        element.style.display = show ? "" : "none";
-    }
-}
-
-const setTocVisibility = (visible) => {
-    setVisibility("div.col-md-3", visible);
-    // Fix the page limitation when removing TOC
-    const main_div = document.querySelector("div.col-md-9");
-    main_div.style.maxWidth = visible ? "75%" : "100%";
-    main_div.style.flexBasis = visible ? "75%" : "100%";
-}
-
-const setNavigationVisibility = (visible) => {
-    setVisibility("ul.navbar-nav:nth-child(1)", visible);
-}
-
-const registerKeyboardEventHandler = () => {
-    // Native HTML key event handling
-    document.addEventListener("keydown", (event => {
-        if (coreEventListenerLogic(event.key)) {
-            // event handled, stop propagation
-            event.preventDefault();
-            event.stopPropagation();
-        }
-    }));
-}

mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin/readthedocs.js

@@ -1,27 +0,0 @@
-const setVisibility = (query_string, show) => {
-    for (let element of document.querySelectorAll(query_string)) {
-        element.style.display = show ? "" : "none";
-    }
-}
-
-const setTocVisibility = (visible) => {
-    setVisibility("nav.wy-nav-side", visible);
-    document.querySelector("div.wy-nav-content").style.maxWidth = visible ? "800px" : "1100px";
-    document.querySelector("section.wy-nav-content-wrap").style.marginLeft = visible ? "300px" : "0px";
-}
-
-const setNavigationVisibility = (visible) => {
-    // TOC and Navigation are merged / in one panel. So we just do nothing
-    // setTocVisibility(visible);
-}
-
-const registerKeyboardEventHandler = () => {
-    // Native HTML key event handling
-    document.addEventListener("keydown", (event => {
-        if (coreEventListenerLogic(event.key)) {
-            // event handled, stop propagation
-            event.preventDefault();
-            event.stopPropagation();
-        }
-    }));
-}

mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js

@@ -1,60 +0,0 @@
-(function() {
-    const loadBool = (name, default_value) => {
-        const value = localStorage.getItem(`TOGGLE_SIDEBAR_${name}`);
-        if (value == null) {
-            return default_value;
-        } else {
-            return value == "1";
-        }
-    }
-
-    const saveBool = (name, value) => {
-        localStorage.setItem(`TOGGLE_SIDEBAR_${name}`, value ? "1" : "0");
-    }
-
-    const toggleTableOfContents = () => {
-        console.debug("Toggling table-of-contents sidebar");
-        const isShown = loadBool("TOC", TOC_DEFAULT_PLACEHOLDER);
-        setTocVisibility(!isShown);
-        saveBool("TOC", !isShown);
-    }
-
-    const toggleNavigation = () => {
-        console.debug("Toggling navigation sidebar");
-        const isShown = loadBool("NAVIGATION", NAVIGATION_DEFAULT_PLACEHOLDER);
-        setNavigationVisibility(!isShown);
-        saveBool("NAVIGATION", !isShown);
-    }
-
-    // START OF INCLUDE
-    // This gets replaced with the definitions of: 
-    // - setTocVisibility(bool) -> void
-    // - setNavigationVisibility(bool) -> void
-    // - registerKeyboardEventHandler() -> void
-    THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER
-    // END OF INCLUDE
-
-    // argument: string, returns true if the key was handled and the event should be marked as already handled
-    const coreEventListenerLogic = (keyChar) => {
-        if (keyChar === "t") {
-            toggleTableOfContents();
-            return true;
-        } else if (keyChar === "m") {
-            toggleNavigation();
-            return true;
-        } else if (keyChar === "b") {
-            toggleNavigation();
-            toggleTableOfContents();
-            return true;
-        } else {
-            return false;
-        }
-    }
-
-    window.addEventListener("load", () => {
-        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)");
-        registerKeyboardEventHandler();
-        setTocVisibility(loadBool("TOC", TOC_DEFAULT_PLACEHOLDER));
-        setNavigationVisibility(loadBool("NAVIGATION", NAVIGATION_DEFAULT_PLACEHOLDER));
-    });
-}());

mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin.egg-info/PKG-INFO

@@ -1,91 +0,0 @@
-Metadata-Version: 2.1
-Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.2
-Summary: Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
-Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
-Author: six-two
-Author-email: pip@six-two.dev
-License: MIT License
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-# mkdocs-toggle-sidebar-plugin
-
-[![PyPI version](https://img.shields.io/pypi/v/mkdocs-toggle-sidebar-plugin)](https://pypi.org/project/mkdocs-toggle-sidebar-plugin/)
-![License](https://img.shields.io/pypi/l/mkdocs-toggle-sidebar-plugin)
-![Python versions](https://img.shields.io/pypi/pyversions/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`
-
-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
-
-## Theme support
-
-Theme            | Theme version | Plugin version | Status
----              | ---           | ---            | ---
-mkdocs-material  | 9.1.21        | 0.0.1          | works
-mkdocs (default) | 1.5.2         | 0.0.2          | works
-readthedocs      | 1.5.2         | 0.0.2          | works
-
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
-
-### Note to self
-
-Test mkdocs-material theme:
-```bash
-./serve.sh
-```
-
-Test mkdocs theme:
-```bash
-./serve.sh --theme mkdocs
-```
-
-## Notable changes
-
-### Version 0.0.2
-
-- Added support for `mkdocs` and `readthedocs` theme.
-
-### Version 0.0.1
-
-- Prototype with `mkdocs-material` implementation.