mkdocs-toggle-sidebar-plugin 0.0.8__tar.gz → 0.0.9__tar.gz

{mkdocs_toggle_sidebar_plugin-0.0.8/src/mkdocs_toggle_sidebar_plugin.egg-info → mkdocs_toggle_sidebar_plugin-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.8
+Version: 0.0.9
 Summary: Add keybindings to toggle the navigation and table of contents sidebars
 Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
 Author: six-two
@@ -84,6 +84,10 @@ plugins:
     show_toc_by_default: False
     theme: material
     toggle_button: all
+    button_toggle_both_tooltip: Toggle Navigation and Table of Contents
+    button_toggle_nav_tooltip: Toggle Navigation
+    button_toggle_toc_tooltip: Toggle Table of Contents
+    button_toggle_icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"></path></svg>'
 ```
 
 The following options exist:
@@ -99,6 +103,10 @@ show_navigation_by_default | `bool` | `True` | Whether to show the navigation by
 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)
+button_toggle_both_tooltip | `str` | `"Toggle Navigation and Table of Contents"` | Tooltip to show when `toggle_button` is `both`
+button_toggle_nav_tooltip | `str` | `"Toggle Navigation"` | Tooltip to show when `toggle_button` is `navigation`
+button_toggle_toc_tooltip | `str` | `"Toggle Table of Contents"` | Tooltip to show when `toggle_button` is `toc`
+button_toggle_icon | `str` | SVG of hamburger menu (three vertical bars on top of each other) | SVG to show for the toggle button. Should be 24px by 24px in size. 
 
 
 #### Toggle button
@@ -108,6 +116,16 @@ 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.
 
+You can set a custom icon for the button, using the `button_toggle_icon` configuration.
+The icon should be a 24px square SVG file.
+
+The tooltip shown when hovering over the button can also be changed.
+Depending on which value you set in `toggle_button`, a different option is used:
+
+- If `toggle_button` is `all`, then `button_toggle_both_tooltip` is used.
+- If `toggle_button` is `navigation`, then `button_toggle_nav_tooltip` is used.
+- If `toggle_button` is `toc`, then `button_toggle_toc_tooltip` is used.
+
 ### Exported API functions
 
 This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
@@ -117,7 +135,7 @@ In short there are:
 
 - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
 - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
-- `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
+- `MkdocsToggleSidebarPlugin.setAllVisibility(showNavigation: bool, showTOC: bool)`
 - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
@@ -169,6 +187,10 @@ docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash
 
 ## Notable changes
 
+### Version 0.0.9
+
+- Added `button_toggle_both_tooltip`, `button_toggle_nav_tooltip`, `button_toggle_toc_tooltip` and `button_toggle_icon` options for customizing the toggle button (see #12)
+
 ### Version 0.0.8
 
 - Fixed toggle button not shown in certain window dimensions in Material theme (see #11)

{mkdocs_toggle_sidebar_plugin-0.0.8 → mkdocs_toggle_sidebar_plugin-0.0.9}/README.md

@@ -62,6 +62,10 @@ plugins:
     show_toc_by_default: False
     theme: material
     toggle_button: all
+    button_toggle_both_tooltip: Toggle Navigation and Table of Contents
+    button_toggle_nav_tooltip: Toggle Navigation
+    button_toggle_toc_tooltip: Toggle Table of Contents
+    button_toggle_icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"></path></svg>'
 ```
 
 The following options exist:
@@ -77,6 +81,10 @@ show_navigation_by_default | `bool` | `True` | Whether to show the navigation by
 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)
+button_toggle_both_tooltip | `str` | `"Toggle Navigation and Table of Contents"` | Tooltip to show when `toggle_button` is `both`
+button_toggle_nav_tooltip | `str` | `"Toggle Navigation"` | Tooltip to show when `toggle_button` is `navigation`
+button_toggle_toc_tooltip | `str` | `"Toggle Table of Contents"` | Tooltip to show when `toggle_button` is `toc`
+button_toggle_icon | `str` | SVG of hamburger menu (three vertical bars on top of each other) | SVG to show for the toggle button. Should be 24px by 24px in size. 
 
 
 #### Toggle button
@@ -86,6 +94,16 @@ 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.
 
+You can set a custom icon for the button, using the `button_toggle_icon` configuration.
+The icon should be a 24px square SVG file.
+
+The tooltip shown when hovering over the button can also be changed.
+Depending on which value you set in `toggle_button`, a different option is used:
+
+- If `toggle_button` is `all`, then `button_toggle_both_tooltip` is used.
+- If `toggle_button` is `navigation`, then `button_toggle_nav_tooltip` is used.
+- If `toggle_button` is `toc`, then `button_toggle_toc_tooltip` is used.
+
 ### Exported API functions
 
 This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
@@ -95,7 +113,7 @@ In short there are:
 
 - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
 - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
-- `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
+- `MkdocsToggleSidebarPlugin.setAllVisibility(showNavigation: bool, showTOC: bool)`
 - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
@@ -147,6 +165,10 @@ docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash
 
 ## Notable changes
 
+### Version 0.0.9
+
+- Added `button_toggle_both_tooltip`, `button_toggle_nav_tooltip`, `button_toggle_toc_tooltip` and `button_toggle_icon` options for customizing the toggle button (see #12)
+
 ### Version 0.0.8
 
 - Fixed toggle button not shown in certain window dimensions in Material theme (see #11)

{mkdocs_toggle_sidebar_plugin-0.0.8 → mkdocs_toggle_sidebar_plugin-0.0.9}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-toggle-sidebar-plugin
-version = 0.0.8
+version = 0.0.9
 author = six-two
 author_email = pip@six-two.dev
 description = Add keybindings to toggle the navigation and table of contents sidebars

{mkdocs_toggle_sidebar_plugin-0.0.8 → mkdocs_toggle_sidebar_plugin-0.0.9}/src/mkdocs_toggle_sidebar_plugin/__init__.py

@@ -1,10 +1,12 @@
+import json
 import os
 import urllib.parse
+import xml.etree.ElementTree as ET
 # pip dependency
 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.config.config_options import Type
 from mkdocs.exceptions import PluginError
 
 LOGGER = get_plugin_logger(__name__)
@@ -16,6 +18,7 @@ THEME_COMPATIBILITY = {
 }
 # May not always be accurate, this is just for a more helpful error message
 KNOWN_THEME_NAMES = ["material", "mkdocs", "readthedocs"] + list(THEME_COMPATIBILITY.keys())
+DEFAULT_TOGGLE_BUTTON_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"></path></svg>'
 
 class PluginConfig(Config):
     enabled = Type(bool, default=True)
@@ -27,6 +30,10 @@ class PluginConfig(Config):
     javascript = Type(str, default="assets/javascripts/toggle-sidebar.js")
     debug = Type(bool, default=False)
     inline = Type(bool, default=False)
+    button_toggle_both_tooltip = Type(str, default="Toggle Navigation and Table of Contents")
+    button_toggle_nav_tooltip = Type(str, default="Toggle Navigation")
+    button_toggle_toc_tooltip = Type(str, default="Toggle Table of Contents")
+    button_toggle_icon = Type(str, default=DEFAULT_TOGGLE_BUTTON_ICON)
 
 
 def is_known_theme(theme_name: str) -> bool:
@@ -49,14 +56,22 @@ def get_base_url_by_url(url: str):
         return './'
     return url.count('/') * '../'
 
+def escape_for_javascript_string(value: str) -> str:
+    # JSON escaping should be save for text added to a double quote (") JavaScript string
+    return json.dumps(value)
+
 class Plugin(BasePlugin[PluginConfig]):
     def on_config(self, config: MkDocsConfig, **kwargs) -> MkDocsConfig:
         """
         Called once when the config is loaded.
         It will make modify the config and initialize this plugin.
         """
+        # This will raise an exception or print a warning if something is missconfigured
+        self.validate_config_options()
+
         self.theme_function_definitions = None
         self.inline_javascript = None
+        
         if self.config.enabled:
             theme_name = self.config.theme
             # Default to automatically determining the theme
@@ -89,9 +104,29 @@ class Plugin(BasePlugin[PluginConfig]):
                 # We cache it for performance reasons
                 self.inline_javascript = f"<script>{self.get_toggle_sidebar_javascript(config)}</script>"
         
+        return config
+    
+    def validate_config_options(self) -> None:
         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
+
+        try:
+            root = ET.fromstring(self.config.button_toggle_icon)
+            width = root.get("width", "").replace("px", "")
+            height = root.get("height", "").replace("px", "")
+            # check size of SVG
+            if width and width != "24":
+                LOGGER.warning(f"button_toggle_icon should have a width of 24, but has {width}")
+            if height and height != "24":
+                LOGGER.warning(f"button_toggle_icon should have a height of 24, but has {height}")
+            # If width and height are not set, fall abck to viewbox
+            if not width and not height:
+                viewBox = root.get("viewBox", "")
+                if viewBox != "0 0 24 24":
+                    LOGGER.warning(f"button_toggle_icon should have a size of 24x24, but has a viewbox of {viewBox} and no explicit size")
+
+        except Exception as ex:
+            LOGGER.error(f"Failed to parse and validate SVG button_toggle_icon: {ex}")
 
     def debug(self, message: str) -> None:
         if self.config.debug:
@@ -136,8 +171,13 @@ class Plugin(BasePlugin[PluginConfig]):
 
         with open(asset_path) as f:
             data = f.read()
-        data = data.replace("THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER", self.theme_function_definitions)
+
+        data = data.replace("THEME_DEPENDENT_FUNCTION_DEFINITION_PLACEHOLDER", self.theme_function_definitions or "")
         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)
-        return data
+        data = data.replace("BUTTON_TOGGLE_ICON_PLACEHOLDER", escape_for_javascript_string(self.config.button_toggle_icon))
+        data = data.replace("BUTTON_TOGGLE_BOTH_TOOLTIP_PLACEHOLDER", escape_for_javascript_string(self.config.button_toggle_both_tooltip))
+        data = data.replace("BUTTON_TOGGLE_NAV_TOOLTIP_PLACEHOLDER", escape_for_javascript_string(self.config.button_toggle_nav_tooltip))
+        data = data.replace("BUTTON_TOGGLE_TOC_TOOLTIP_PLACEHOLDER", escape_for_javascript_string(self.config.button_toggle_toc_tooltip))
+        return data

{mkdocs_toggle_sidebar_plugin-0.0.8 → mkdocs_toggle_sidebar_plugin-0.0.9}/src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js

@@ -88,13 +88,13 @@
     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>`;
+        toggleBtn.innerHTML = BUTTON_TOGGLE_ICON_PLACEHOLDER;
         if (toggleNavigation && toggleTOC) {
-            toggleBtn.title = "Toggle Navigation and Table of Contents";
+            toggleBtn.title = BUTTON_TOGGLE_BOTH_TOOLTIP_PLACEHOLDER;
         } else if (toggleNavigation) {
-            toggleBtn.title = "Toggle Navigation";
+            toggleBtn.title = BUTTON_TOGGLE_NAV_TOOLTIP_PLACEHOLDER;
         } else if (toggleTOC) {
-            toggleBtn.title = "Toggle Table of Contents";
+            toggleBtn.title = BUTTON_TOGGLE_TOC_TOOLTIP_PLACEHOLDER;
         }
         toggleBtn.addEventListener("click", () => toggleVisibility(toggleNavigation, toggleTOC));
         return toggleBtn;

{mkdocs_toggle_sidebar_plugin-0.0.8 → mkdocs_toggle_sidebar_plugin-0.0.9/src/mkdocs_toggle_sidebar_plugin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-toggle-sidebar-plugin
-Version: 0.0.8
+Version: 0.0.9
 Summary: Add keybindings to toggle the navigation and table of contents sidebars
 Home-page: https://github.com/six-two/mkdocs-toggle-sidebar-plugin
 Author: six-two
@@ -84,6 +84,10 @@ plugins:
     show_toc_by_default: False
     theme: material
     toggle_button: all
+    button_toggle_both_tooltip: Toggle Navigation and Table of Contents
+    button_toggle_nav_tooltip: Toggle Navigation
+    button_toggle_toc_tooltip: Toggle Table of Contents
+    button_toggle_icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"></path></svg>'
 ```
 
 The following options exist:
@@ -99,6 +103,10 @@ show_navigation_by_default | `bool` | `True` | Whether to show the navigation by
 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)
+button_toggle_both_tooltip | `str` | `"Toggle Navigation and Table of Contents"` | Tooltip to show when `toggle_button` is `both`
+button_toggle_nav_tooltip | `str` | `"Toggle Navigation"` | Tooltip to show when `toggle_button` is `navigation`
+button_toggle_toc_tooltip | `str` | `"Toggle Table of Contents"` | Tooltip to show when `toggle_button` is `toc`
+button_toggle_icon | `str` | SVG of hamburger menu (three vertical bars on top of each other) | SVG to show for the toggle button. Should be 24px by 24px in size. 
 
 
 #### Toggle button
@@ -108,6 +116,16 @@ 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.
 
+You can set a custom icon for the button, using the `button_toggle_icon` configuration.
+The icon should be a 24px square SVG file.
+
+The tooltip shown when hovering over the button can also be changed.
+Depending on which value you set in `toggle_button`, a different option is used:
+
+- If `toggle_button` is `all`, then `button_toggle_both_tooltip` is used.
+- If `toggle_button` is `navigation`, then `button_toggle_nav_tooltip` is used.
+- If `toggle_button` is `toc`, then `button_toggle_toc_tooltip` is used.
+
 ### Exported API functions
 
 This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
@@ -117,7 +135,7 @@ In short there are:
 
 - `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
 - `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
-- `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
+- `MkdocsToggleSidebarPlugin.setAllVisibility(showNavigation: bool, showTOC: bool)`
 - `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
 - `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
@@ -169,6 +187,10 @@ docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash
 
 ## Notable changes
 
+### Version 0.0.9
+
+- Added `button_toggle_both_tooltip`, `button_toggle_nav_tooltip`, `button_toggle_toc_tooltip` and `button_toggle_icon` options for customizing the toggle button (see #12)
+
 ### Version 0.0.8
 
 - Fixed toggle button not shown in certain window dimensions in Material theme (see #11)