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

mkdocs-toggle-sidebar-plugin-0.0.2/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include src/mkdocs_toggle_sidebar_plugin/*.js

{mkdocs-toggle-sidebar-plugin-0.0.1/src/mkdocs_toggle_sidebar_plugin.egg-info → mkdocs-toggle-sidebar-plugin-0.0.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.1
-Summary: TODO
+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
@@ -16,13 +16,21 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# mkdocs-crosslink-plugin
+# 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 add links to other MkDocs sites (or sites created with similar page generator).
+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
 
@@ -47,20 +55,37 @@ The plugin adds the following key bindings:
 Key   | Action
 ---   | ---
 ++b++ | toggle **b**oth (TOC and navigation)
-++m++ | toggle navigation menu
-++t++ | toggle TOC
+++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.1         | not yet implemented
+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.
+- Prototype with `mkdocs-material` implementation.

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

@@ -0,0 +1,73 @@
+# 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.1 → mkdocs-toggle-sidebar-plugin-0.0.2}/setup.cfg

@@ -1,9 +1,9 @@
 [metadata]
 name = mkdocs-toggle-sidebar-plugin
-version = 0.0.1
+version = 0.0.2
 author = six-two
 author_email = pip@six-two.dev
-description = TODO
+description = Add keybindings to toggle the table of contents and menu sidebars on some MkDocs themes
 long_description = file: README.md
 long_description_content_type = text/markdown
 url = https://github.com/six-two/mkdocs-toggle-sidebar-plugin

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

@@ -1,10 +1,14 @@
 import os
+import logging
 # pip dependency
 from mkdocs.plugins import BasePlugin
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.config.base import Config
 from mkdocs.config.config_options import Type, ExtraScriptValue
 
+LOGGER = logging.getLogger("mkdocs.plugins.toggle-sidebar")
+SCRIPT_DIR = os.path.dirname(__file__)
+
 class PluginConfig(Config):
     enabled = Type(bool, default=True)
     show_toc_by_default = Type(bool, default=True)
@@ -19,7 +23,17 @@ class Plugin(BasePlugin[PluginConfig]):
         Called once when the config is loaded.
         It will make modify the config and initialize this plugin.
         """
+        self.theme_function_definitions = None
         if self.config.enabled:
+            theme_name = config.theme.name or "mkdocs"
+            theme_path = os.path.join(SCRIPT_DIR, f"{theme_name}.js")
+            if os.path.exists(theme_path):
+                with open(theme_path) as f:
+                    self.theme_function_definitions = f.read()
+            else:
+                LOGGER.warning(f"[toggle-sidebar] Theme '{theme_name}' is not (yet) supported. Hint:\n1. Try updating the plugin to the latest version: pip install -U mkdocs-toggle-sidebar-plugin\n2. Check if an issue for this theme exists: https://github.com/six-two/mkdocs-toggle-sidebar-plugin/issues\n3. If no issue exists feel free to open one. Please put the theme name and path where to download it in the issue")
+
+        if self.theme_function_definitions:
             custom_script = ExtraScriptValue(self.config.javascript)
             if self.config.async_:
                 custom_script.async_ = True
@@ -29,7 +43,7 @@ class Plugin(BasePlugin[PluginConfig]):
 
 
     def on_post_build(self, config: MkDocsConfig) -> None:
-        if self.config.enabled:
+        if self.theme_function_definitions:
             target_path = os.path.join(config.site_dir, self.config.javascript)
             if os.path.exists(target_path):
                 # The file exists. This probably means, that the user wanted to override the default file
@@ -39,12 +53,12 @@ class Plugin(BasePlugin[PluginConfig]):
                 # Make sure that the folder exists
                 parent_dir = os.path.dirname(target_path)
                 os.makedirs(parent_dir, exist_ok=True)
-
+                
                 # Copy the file, while also editing it on the fly
-                current_dir = os.path.dirname(__file__)
-                asset_path = os.path.join(current_dir, "toggle-sidebar.js")
+                asset_path = os.path.join(SCRIPT_DIR, "toggle-sidebar.js")
                 with open(asset_path) as f:
                     data = f.read()
+                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")
                 with open(target_path, "w") as f:

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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,60 @@
+(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.1 → mkdocs-toggle-sidebar-plugin-0.0.2/src/mkdocs_toggle_sidebar_plugin.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.1
-Summary: TODO
+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
@@ -16,13 +16,21 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# mkdocs-crosslink-plugin
+# 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 add links to other MkDocs sites (or sites created with similar page generator).
+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
 
@@ -47,20 +55,37 @@ The plugin adds the following key bindings:
 Key   | Action
 ---   | ---
 ++b++ | toggle **b**oth (TOC and navigation)
-++m++ | toggle navigation menu
-++t++ | toggle TOC
+++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.1         | not yet implemented
+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.
+- Prototype with `mkdocs-material` implementation.

{mkdocs-toggle-sidebar-plugin-0.0.1 → mkdocs-toggle-sidebar-plugin-0.0.2}/src/mkdocs_toggle_sidebar_plugin.egg-info/SOURCES.txt

@@ -4,6 +4,9 @@ README.md
 pyproject.toml
 setup.cfg
 src/mkdocs_toggle_sidebar_plugin/__init__.py
+src/mkdocs_toggle_sidebar_plugin/material.js
+src/mkdocs_toggle_sidebar_plugin/mkdocs.js
+src/mkdocs_toggle_sidebar_plugin/readthedocs.js
 src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js
 src/mkdocs_toggle_sidebar_plugin.egg-info/PKG-INFO
 src/mkdocs_toggle_sidebar_plugin.egg-info/SOURCES.txt

mkdocs-toggle-sidebar-plugin-0.0.1/MANIFEST.in

@@ -1,2 +0,0 @@
-include README.md
-include src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js

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

@@ -1,48 +0,0 @@
-# mkdocs-crosslink-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 add links to other MkDocs sites (or sites created with similar page generator).
-
-## 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 menu
-++t++ | toggle TOC
-
-## Theme support
-
-Theme            | Theme version |Plugin version | Status
----              | ---           | ---           | ---
-mkdocs-material  | 9.1.21        | 0.0.1         | works
-mkdocs (default) | 1.5.2         | 0.0.1         | not yet implemented
-
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
-
-## Notable changes
-
-### Version 0.0.1
-
-Prototype with `mkdocs-material` implementation.

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

@@ -1,61 +0,0 @@
-(function() {
-    const setVisibility = (query_string, show) => {
-        for (let element of document.querySelectorAll(query_string)) {
-            element.style.display = show ? "block" : "none";
-        }
-    }
-
-    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 setTocVisibility = (visible) => {
-        setVisibility("div.md-sidebar.md-sidebar--secondary", visible);
-        saveBool("TOC", visible);
-    }
-    
-    const setNavigationVisibility = (visible) => {
-        setVisibility("div.md-sidebar.md-sidebar--primary", visible);
-        saveBool("NAVIGATION", visible);
-    }
-
-    const toggleTableOfContents = () => {
-        const isShown = loadBool("TOC", TOC_DEFAULT_PLACEHOLDER);
-        setTocVisibility(!isShown)
-    }
-
-    const toggleNavigation = () => {
-        console.debug("Toggling table-of-contents sitebar");
-        const isShown = loadBool("NAVIGATION", NAVIGATION_DEFAULT_PLACEHOLDER);
-        setNavigationVisibility(!isShown);
-    }
-
-    // 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 (key.type === "t") {
-                key.claim();
-                toggleTableOfContents();
-            } else if (key.type === "m") {
-                key.claim();
-                toggleNavigation();
-            } else if (key.type === "b") {
-                key.claim();
-                toggleNavigation();
-                toggleTableOfContents();
-            }
-        }
-    });
-
-    setTocVisibility(loadBool("TOC", TOC_DEFAULT_PLACEHOLDER));
-    setNavigationVisibility(loadBool("NAVIGATION", NAVIGATION_DEFAULT_PLACEHOLDER));
-}());