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

{mkdocs_toggle_sidebar_plugin-0.0.4/src/mkdocs_toggle_sidebar_plugin.egg-info → mkdocs_toggle_sidebar_plugin-0.0.6}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 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
+Version: 0.0.6
+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
 Author-email: pip@six-two.dev
@@ -12,10 +12,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: mkdocs>=1.5.0
+Dynamic: license-file
 
 # mkdocs-toggle-sidebar-plugin
 
@@ -64,7 +67,41 @@ Key   | Action
 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
+### Configuration options
+
+You can overwrite the defaults like this:
+
+```yaml
+plugins:
+- search
+- toggle-sidebar:
+    async: False
+    debug: True
+    enabled: True
+    inline: False
+    javascript: ./toggle-sidebar.js
+    show_navigation_by_default: False
+    show_toc_by_default: False
+    theme: material
+    toggle_button: all
+```
+
+The following options exist:
+
+Option | Type | Default value | Description
+--- | ---| --- | ---
+async | `bool` | `False` | Asynchronously load the JavaScript file created by the plugin
+debug | `bool` | `False` | Show some debug messages during mkdocs build (for example related to theme detection)
+enabled | `bool` | `True` | Can be used to disable the plugin. Usually used in combination with environment variables like `enabled: !ENV [TOGGLE_SIDEBAR, false]` as described in [mkdocs's docs](https://www.mkdocs.org/user-guide/configuration/#enabled-option)
+inline | `bool` | `True` | Instead of storing the javascript code in the file specified by `javascript`, it is directly copied into each page. Slightly increases page size, but can improve load times a little bit and reduce flickering on page (re-)load
+javascript | `str` | `"assets/javascripts/toggle-sidebar.js"` | The path where to store the output file
+show_navigation_by_default | `bool` | `True` | Whether to show the navigation by default
+show_toc_by_default | `bool` | `True` | Whether to show the table of contents by default
+theme | `str` | `auto` | Used for theme detection. With `auto`, the plugin tries to automatically detect the theme. But you can also force it to use a specific theme preset that you know will work. Currently supported values: `material`/`ansible`, `mkdocs`, `readthedocs`.
+toggle_button | `str` | `"none"` | Can be set to show a toggle button (see below)
+
+
+#### Toggle button
 
 When you set the `toggle_button` option to `navigation`, `toc` or `all`, it will add a button that looks like a hamburger menu (three horizontal bars) on a theme-dependent location.
 It is usually in the nav or the top bar.
@@ -90,35 +127,67 @@ 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.
+The table is not updated regularly, but the plugin should generally work for other 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
+mkdocs-ansible   | 25.6.0        | 0.0.6          | works
+mkdocs-material  | 9.6.14        | 0.0.4+         | works
+mkdocs (default) | 1.6.1         | 0.0.4+         | works
+readthedocs      | 1.6.1         | 0.0.4+         | works
 
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
+Just open an issue / PR if you use a strange theme or the info above is not up-to-date anymore.
 
 ### Note to self
 
-Test mkdocs-material theme:
+Test `material` theme:
 ```bash
 ./serve.sh
 ```
 
-Test mkdocs theme:
+Test `mkdocs` theme:
 ```bash
 ./serve.sh --theme mkdocs
 ```
 
+Test `mkdocs`, `readthedocs` and `material` themes:
+```bash
+./build.sh
+python3 -m http.server --directory './public/'
+```
+
+Test oldest python version supported by me (3.9):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:3.9 ./serve.sh
+```
+
+Test newest available python version (currently 3.13):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:latest ./serve.sh
+```
+
+
 ## Notable changes
 
+### Version 0.0.6
+
+- Fixed toggle button appearing delayed on slow loading pages (see #6)
+- Fixed behavior when using Material's `navigation.instant` feature (see #5)
+- Added `inline` option that prevents page flickering on reload (see #4). It is now enabled by default and async is disabled by default, to prevent the flickering. To revert to the old behavior you can set `async: True` and `inline: False` in the plugin's config in your `mkdocs.yml`
+- Added `theme` option that allows you to override theme detection (see #3)
+- Added support for `ansible` theme (see #3)
+- Added fallback to check `theme.extra.base_theme` from `mkdocs.yml` when other theme detection logic fails (see #3)
+- Added `debug` option
+
+### Version 0.0.5
+
+- Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
+
 ### Version 0.0.4
 
 - Export API via `MkdocsToggleSidebarPlugin` object.
     This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
-- Added `toggle_button` option and implemented it for Material theme
+- Added `toggle_button` option and implemented it for Material theme.
 
 ### Version 0.0.3
 

mkdocs_toggle_sidebar_plugin-0.0.6/README.md

@@ -0,0 +1,181 @@
+# 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.
+
+### Configuration options
+
+You can overwrite the defaults like this:
+
+```yaml
+plugins:
+- search
+- toggle-sidebar:
+    async: False
+    debug: True
+    enabled: True
+    inline: False
+    javascript: ./toggle-sidebar.js
+    show_navigation_by_default: False
+    show_toc_by_default: False
+    theme: material
+    toggle_button: all
+```
+
+The following options exist:
+
+Option | Type | Default value | Description
+--- | ---| --- | ---
+async | `bool` | `False` | Asynchronously load the JavaScript file created by the plugin
+debug | `bool` | `False` | Show some debug messages during mkdocs build (for example related to theme detection)
+enabled | `bool` | `True` | Can be used to disable the plugin. Usually used in combination with environment variables like `enabled: !ENV [TOGGLE_SIDEBAR, false]` as described in [mkdocs's docs](https://www.mkdocs.org/user-guide/configuration/#enabled-option)
+inline | `bool` | `True` | Instead of storing the javascript code in the file specified by `javascript`, it is directly copied into each page. Slightly increases page size, but can improve load times a little bit and reduce flickering on page (re-)load
+javascript | `str` | `"assets/javascripts/toggle-sidebar.js"` | The path where to store the output file
+show_navigation_by_default | `bool` | `True` | Whether to show the navigation by default
+show_toc_by_default | `bool` | `True` | Whether to show the table of contents by default
+theme | `str` | `auto` | Used for theme detection. With `auto`, the plugin tries to automatically detect the theme. But you can also force it to use a specific theme preset that you know will work. Currently supported values: `material`/`ansible`, `mkdocs`, `readthedocs`.
+toggle_button | `str` | `"none"` | Can be set to show a toggle button (see below)
+
+
+#### Toggle button
+
+When you set the `toggle_button` option to `navigation`, `toc` or `all`, it will add a button that looks like a hamburger menu (three horizontal bars) on a theme-dependent location.
+It is usually in the nav or the top bar.
+Clicking the button will toggle the navigation, table of contents, or both (depending on the supplied value).
+By leaving the field empty or setting it to `none`, no button is added.
+
+### Exported API functions
+
+This plugin exposes some JavaScript functions, that can show, hide or toggle the visibility of the sidebars.
+You can see how they are called in `docs/javascript-functions.md` and how they are defined in `src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js`.
+
+In short there are:
+
+- `MkdocsToggleSidebarPlugin.setNavigationVisibility(show: bool)`
+- `MkdocsToggleSidebarPlugin.setTocVisibility(show: bool)`
+- `MkdocsToggleSidebarPlugin.setAllVisibility: (showNavigation: bool, showTOC: bool)`
+- `MkdocsToggleSidebarPlugin.toggleNavigationVisibility()`
+- `MkdocsToggleSidebarPlugin.toggleTocVisibility()`
+- `MkdocsToggleSidebarPlugin.toggleAllVisibility()`
+
+The names and parameters should be self-explanatory.
+
+## Theme support
+
+Below shows the latest themes that I have tested.
+The table is not updated regularly, but the plugin should generally work for other theme versions too.
+
+Theme            | Theme version | Plugin version | Status
+---              | ---           | ---            | ---
+mkdocs-ansible   | 25.6.0        | 0.0.6          | works
+mkdocs-material  | 9.6.14        | 0.0.4+         | works
+mkdocs (default) | 1.6.1         | 0.0.4+         | works
+readthedocs      | 1.6.1         | 0.0.4+         | works
+
+Just open an issue / PR if you use a strange theme or the info above is not up-to-date anymore.
+
+### Note to self
+
+Test `material` theme:
+```bash
+./serve.sh
+```
+
+Test `mkdocs` theme:
+```bash
+./serve.sh --theme mkdocs
+```
+
+Test `mkdocs`, `readthedocs` and `material` themes:
+```bash
+./build.sh
+python3 -m http.server --directory './public/'
+```
+
+Test oldest python version supported by me (3.9):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:3.9 ./serve.sh
+```
+
+Test newest available python version (currently 3.13):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:latest ./serve.sh
+```
+
+
+## Notable changes
+
+### Version 0.0.6
+
+- Fixed toggle button appearing delayed on slow loading pages (see #6)
+- Fixed behavior when using Material's `navigation.instant` feature (see #5)
+- Added `inline` option that prevents page flickering on reload (see #4). It is now enabled by default and async is disabled by default, to prevent the flickering. To revert to the old behavior you can set `async: True` and `inline: False` in the plugin's config in your `mkdocs.yml`
+- Added `theme` option that allows you to override theme detection (see #3)
+- Added support for `ansible` theme (see #3)
+- Added fallback to check `theme.extra.base_theme` from `mkdocs.yml` when other theme detection logic fails (see #3)
+- Added `debug` option
+
+### Version 0.0.5
+
+- Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
+
+### Version 0.0.4
+
+- Export API via `MkdocsToggleSidebarPlugin` object.
+    This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
+- Added `toggle_button` option and implemented it for Material theme.
+
+### Version 0.0.3
+
+- Changed internal API:
+    - Element hiding/restyling is now done via CSS, so it is easier to undo. You should no longer have problems on devices with small screens (like phones) having broken layouts.
+
+### Version 0.0.2
+
+- Added support for `mkdocs` and `readthedocs` theme.
+
+### Version 0.0.1
+
+- Prototype with `mkdocs-material` implementation.

{mkdocs_toggle_sidebar_plugin-0.0.4 → mkdocs_toggle_sidebar_plugin-0.0.6}/setup.cfg

@@ -1,9 +1,9 @@
 [metadata]
 name = mkdocs-toggle-sidebar-plugin
-version = 0.0.4
+version = 0.0.6
 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
+description = Add keybindings to toggle the navigation and table of contents sidebars
 long_description = file: README.md
 long_description_content_type = text/markdown
 url = https://github.com/six-two/mkdocs-toggle-sidebar-plugin
@@ -15,6 +15,8 @@ classifiers =
 	Programming Language :: Python :: 3.9
 	Programming Language :: Python :: 3.10
 	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+	Programming Language :: Python :: 3.13
 
 [options]
 include_package_data = True
@@ -24,7 +26,7 @@ packages = find:
 python_requires = >=3.9
 scripts = 
 install_requires = 
-	mkdocs>=1.4.0
+	mkdocs>=1.5.0
 
 [options.entry_points]
 mkdocs.plugins = 

mkdocs_toggle_sidebar_plugin-0.0.6/src/mkdocs_toggle_sidebar_plugin/__init__.py

@@ -0,0 +1,135 @@
+import os
+# 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.exceptions import PluginError
+
+LOGGER = get_plugin_logger(__name__)
+SCRIPT_DIR = os.path.dirname(__file__)
+ALLOWED_TOGGLE_BUTTON_VALUES = ["none", "navigation", "toc", "all"]
+# This is a map of compatible themes. For example 'ansible' inherits from 'material', so the material javascript will work for the ansible theme too
+THEME_COMPATIBILITY = {
+    "ansible": "material",
+}
+# May not always be accurate, this is just for a more helpful error message
+KNOWN_THEME_NAMES = ["material", "mkdocs", "readthedocs"] + list(THEME_COMPATIBILITY.keys())
+
+class PluginConfig(Config):
+    enabled = Type(bool, default=True)
+    show_toc_by_default = Type(bool, default=True)
+    show_navigation_by_default = Type(bool, default=True)
+    theme = Type(str, default="auto")
+    toggle_button = Type(str, default="none")
+    async_ = Type(bool, default=False)
+    javascript = Type(str, default="assets/javascripts/toggle-sidebar.js")
+    debug = Type(bool, default=False)
+    inline = Type(bool, default=True)
+
+
+def is_known_theme(theme_name: str) -> bool:
+    # If the theme is known to be based on another theme, then we resolve it to the base theme
+    theme_name = THEME_COMPATIBILITY.get(theme_name, theme_name)
+
+    # Then we check if we have a javascript file for the theme
+    theme_path = os.path.join(SCRIPT_DIR, f"{theme_name}.js")
+    return os.path.exists(theme_path) and theme_name != "toggle-sidebar"
+
+def get_unknown_theme_message(theme_name: str, auto_detect_enabled: bool) -> str:
+    if auto_detect_enabled:
+        basic_help = "If this theme is based on or similar to one of the supported themes above, add 'theme: <NAME_OF_SIMILAR_SUPPORTED_THEME>' to this plugin's configuration in your mkdocs.yml"
+    else:
+        basic_help = "You are overwriting the theme in this plugin's configuration in your mkdocs.yml. Make sure you spelled the theme's name correctly."
+    return f"Theme '{theme_name}' is not (yet) supported. The currently supported themes are: {', '.join(KNOWN_THEME_NAMES)}.\nRecommended steps:\n1. {basic_help}\n2. Try updating this plugin to the latest version: pip install -U mkdocs-toggle-sidebar-plugin\n3. Check if an issue for this theme exists: https://github.com/six-two/mkdocs-toggle-sidebar-plugin/issues\n4. If no issue exists feel free to open one. Please put the theme name and path where to download it in the issue"
+    
+
+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.
+        """
+        self.theme_function_definitions = None
+        self.inline_javascript = None
+        if self.config.enabled:
+            theme_name = self.config.theme
+            # Default to automatically determining the theme
+            if theme_name == "auto" or not theme_name:
+                theme_name = config.theme.name or "mkdocs"
+                base_theme_name = config.theme.get("extra", {}).get("base_theme") # check mkdocs.yml:theme.extra.base_theme
+                self.debug(f"Automatically detected theme: {theme_name}. Optional base theme: {base_theme_name}")
+
+                if not is_known_theme(theme_name):
+                    # Handle themes
+                    if base_theme_name and is_known_theme(base_theme_name):
+                        LOGGER.debug(f"Theme is unknown, so we fell back to base theme: {base_theme_name}")
+                        theme_name = base_theme_name
+                    else:
+                        LOGGER.warning(get_unknown_theme_message(theme_name, True))
+            else:
+                if not is_known_theme(theme_name):
+                    LOGGER.warning(get_unknown_theme_message(theme_name, False))
+
+            # If the theme is known to be based on another theme, then we resolve it to the base theme
+            resolved_theme_name = THEME_COMPATIBILITY.get(theme_name, theme_name)
+
+            theme_path = os.path.join(SCRIPT_DIR, f"{resolved_theme_name}.js")
+            if os.path.exists(theme_path):
+                self.debug(f"Using JavaScript {resolved_theme_name}.js for theme {theme_name}")
+                with open(theme_path) as f:
+                    self.theme_function_definitions = f.read()
+
+        if self.theme_function_definitions:
+            if self.config.inline:
+                # We cache it for performance reasons
+                self.inline_javascript = f"<script>{self.get_toggle_sidebar_javascript()}</script>"
+            else:
+                # Add a custom script reference
+                custom_script = ExtraScriptValue(self.config.javascript)
+                if self.config.async_:
+                    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
+
+    def debug(self, message: str) -> None:
+        if self.config.debug:
+            LOGGER.info(message)
+        else:
+            LOGGER.debug(message)
+
+    def on_post_page(self, html, /, *, page, config):
+        if self.inline_javascript:
+            html = html.replace("</head>", self.inline_javascript + "</head>")
+        return html
+
+    def on_post_build(self, config: MkDocsConfig) -> None:
+        if self.theme_function_definitions and not self.config.inline:
+            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
+                # So we just do nothing
+                pass
+            else:
+                # 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
+                javascript = self.get_toggle_sidebar_javascript()
+                with open(target_path, "w") as f:
+                    f.write(javascript)
+
+    def get_toggle_sidebar_javascript(self):
+        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")
+        data = data.replace("TOGGLE_BUTTON_PLACEHOLDER", self.config.toggle_button)
+        return data

{mkdocs_toggle_sidebar_plugin-0.0.4 → mkdocs_toggle_sidebar_plugin-0.0.6}/src/mkdocs_toggle_sidebar_plugin/material.js

@@ -1,4 +1,7 @@
 const setCombinedVisibility = (showNavigation, showTOC) => {
+    // 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
+    
     let style = `
 .mkdocs-toggle-sidebar-button {
     cursor: pointer;
@@ -6,31 +9,34 @@ const setCombinedVisibility = (showNavigation, showTOC) => {
     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;
+// The TOC has a different break point than the navigation.
+// It can be seen on the nav.md-nav--secondary:nth-child(1) element (60em)
+// If the screen is smaller, it is shown in the navigation section if you click the nested hamburger menu
+if (!showTOC) {
+    style += `
+@media screen and (min-width: 60em) {
+    div.md-sidebar.md-sidebar--secondary {
+        display: none;
+    }
 }
 `;
-    }
-
+        }
+        
+    // We always have to show the navigation in mobile view, otherwise the hamburger menu is broken
     if (!showNavigation) {
         style += `
-div.md-sidebar.md-sidebar--primary {
-    display: none;
+@media screen and (min-width: 76.1875em) {
+    div.md-sidebar.md-sidebar--primary {
+        display: none;
+    }
 }
-`
+`;
     }
 
     return style;

{mkdocs_toggle_sidebar_plugin-0.0.4 → mkdocs_toggle_sidebar_plugin-0.0.6}/src/mkdocs_toggle_sidebar_plugin/toggle-sidebar.js

@@ -1,6 +1,7 @@
 (function() {
     const customDynamicStyle = document.createElement("style");
-    document.head.appendChild(customDynamicStyle);
+    // We must put it outside of the head and body, since they are replaced by the instant navigation feature in the Material theme
+    document.documentElement.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.";
 
@@ -65,7 +66,7 @@
         }
     }
 
-    window.addEventListener("load", () => {
+    const onPageLoadedAction = () => {
         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";
@@ -82,8 +83,7 @@
         }
 
         registerKeyboardEventHandler();
-        customDynamicStyle.innerHTML = setCombinedVisibility(loadNavigationState(), loadTocState());
-    });
+    }
 
     const createDefaultToggleButton = (toggleNavigation, toggleTOC) => {
         const toggleBtn = document.createElement("div");
@@ -119,4 +119,17 @@
         toggleTocVisibility: () => toggleVisibility(false, true),
         toggleAllVisibility: () => toggleVisibility(true, true)
     };
+
+    // Run this immediately instead of waiting for page.onload to prevent page flicker
+    customDynamicStyle.innerHTML = setCombinedVisibility(loadNavigationState(), loadTocState());
+    // console.log("Debug: hide sidebar completed");
+
+    // SEE https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event#checking_whether_loading_is_already_complete
+    if (document.readyState === "loading") {
+        // console.debug("Registering DOMContentLoaded event listener");
+        document.addEventListener("DOMContentLoaded", onPageLoadedAction);
+    } else {
+        // console.debug("DOMContentLoaded has already fired");
+        onPageLoadedAction();
+    }
 }());

{mkdocs_toggle_sidebar_plugin-0.0.4 → mkdocs_toggle_sidebar_plugin-0.0.6/src/mkdocs_toggle_sidebar_plugin.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 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
+Version: 0.0.6
+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
 Author-email: pip@six-two.dev
@@ -12,10 +12,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: mkdocs>=1.5.0
+Dynamic: license-file
 
 # mkdocs-toggle-sidebar-plugin
 
@@ -64,7 +67,41 @@ Key   | Action
 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
+### Configuration options
+
+You can overwrite the defaults like this:
+
+```yaml
+plugins:
+- search
+- toggle-sidebar:
+    async: False
+    debug: True
+    enabled: True
+    inline: False
+    javascript: ./toggle-sidebar.js
+    show_navigation_by_default: False
+    show_toc_by_default: False
+    theme: material
+    toggle_button: all
+```
+
+The following options exist:
+
+Option | Type | Default value | Description
+--- | ---| --- | ---
+async | `bool` | `False` | Asynchronously load the JavaScript file created by the plugin
+debug | `bool` | `False` | Show some debug messages during mkdocs build (for example related to theme detection)
+enabled | `bool` | `True` | Can be used to disable the plugin. Usually used in combination with environment variables like `enabled: !ENV [TOGGLE_SIDEBAR, false]` as described in [mkdocs's docs](https://www.mkdocs.org/user-guide/configuration/#enabled-option)
+inline | `bool` | `True` | Instead of storing the javascript code in the file specified by `javascript`, it is directly copied into each page. Slightly increases page size, but can improve load times a little bit and reduce flickering on page (re-)load
+javascript | `str` | `"assets/javascripts/toggle-sidebar.js"` | The path where to store the output file
+show_navigation_by_default | `bool` | `True` | Whether to show the navigation by default
+show_toc_by_default | `bool` | `True` | Whether to show the table of contents by default
+theme | `str` | `auto` | Used for theme detection. With `auto`, the plugin tries to automatically detect the theme. But you can also force it to use a specific theme preset that you know will work. Currently supported values: `material`/`ansible`, `mkdocs`, `readthedocs`.
+toggle_button | `str` | `"none"` | Can be set to show a toggle button (see below)
+
+
+#### Toggle button
 
 When you set the `toggle_button` option to `navigation`, `toc` or `all`, it will add a button that looks like a hamburger menu (three horizontal bars) on a theme-dependent location.
 It is usually in the nav or the top bar.
@@ -90,35 +127,67 @@ 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.
+The table is not updated regularly, but the plugin should generally work for other 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
+mkdocs-ansible   | 25.6.0        | 0.0.6          | works
+mkdocs-material  | 9.6.14        | 0.0.4+         | works
+mkdocs (default) | 1.6.1         | 0.0.4+         | works
+readthedocs      | 1.6.1         | 0.0.4+         | works
 
-Just open a issue / PR if you use a strange theme or the info above is not up to date anymore.
+Just open an issue / PR if you use a strange theme or the info above is not up-to-date anymore.
 
 ### Note to self
 
-Test mkdocs-material theme:
+Test `material` theme:
 ```bash
 ./serve.sh
 ```
 
-Test mkdocs theme:
+Test `mkdocs` theme:
 ```bash
 ./serve.sh --theme mkdocs
 ```
 
+Test `mkdocs`, `readthedocs` and `material` themes:
+```bash
+./build.sh
+python3 -m http.server --directory './public/'
+```
+
+Test oldest python version supported by me (3.9):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:3.9 ./serve.sh
+```
+
+Test newest available python version (currently 3.13):
+```bash
+docker run --rm -it -v "$PWD:/share" -w "/share" -p 8000:8000 --entrypoint=bash python:latest ./serve.sh
+```
+
+
 ## Notable changes
 
+### Version 0.0.6
+
+- Fixed toggle button appearing delayed on slow loading pages (see #6)
+- Fixed behavior when using Material's `navigation.instant` feature (see #5)
+- Added `inline` option that prevents page flickering on reload (see #4). It is now enabled by default and async is disabled by default, to prevent the flickering. To revert to the old behavior you can set `async: True` and `inline: False` in the plugin's config in your `mkdocs.yml`
+- Added `theme` option that allows you to override theme detection (see #3)
+- Added support for `ansible` theme (see #3)
+- Added fallback to check `theme.extra.base_theme` from `mkdocs.yml` when other theme detection logic fails (see #3)
+- Added `debug` option
+
+### Version 0.0.5
+
+- Bug fix: On small screens with the material theme the navigation would be hidden, even when the hamburger menu was opened.
+
 ### Version 0.0.4
 
 - Export API via `MkdocsToggleSidebarPlugin` object.
     This lets you create custom buttons or key bindings to hide, show or toggle the side bars.
-- Added `toggle_button` option and implemented it for Material theme
+- Added `toggle_button` option and implemented it for Material theme.
 
 ### Version 0.0.3
 

mkdocs_toggle_sidebar_plugin-0.0.6/src/mkdocs_toggle_sidebar_plugin.egg-info/requires.txt

@@ -0,0 +1 @@
+mkdocs>=1.5.0

mkdocs_toggle_sidebar_plugin-0.0.4/README.md

@@ -1,115 +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`
-
-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/src/mkdocs_toggle_sidebar_plugin/__init__.py

@@ -1,73 +0,0 @@
-import os
-import logging
-# 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.exceptions import PluginError
-
-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")
-
-
-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.
-        """
-        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
-            
-            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
-
-
-    def on_post_build(self, config: MkDocsConfig) -> None:
-        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
-                # So we just do nothing
-                pass
-            else:
-                # 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
-                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")
-                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.egg-info/requires.txt

@@ -1 +0,0 @@
-mkdocs>=1.4.0