mkdocs-backlinks-section-plugin 0.0.1__tar.gz

mkdocs_backlinks_section_plugin-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 six-two
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_backlinks_section_plugin-0.0.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.1
+Name: mkdocs-backlinks-section-plugin
+Version: 0.0.1
+Summary: Adds a backlinks section that lists every page linking to the current page.
+Home-page: https://github.com/six-two/mkdocs-backlinks-section-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
+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.5.0
+
+# MkDocs Backlinks Section Plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-backlinks-section-plugin)](https://pypi.org/project/mkdocs-backlinks-section-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-backlinks-section-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-backlinks-section-plugin)
+
+Adds a backlinks section that lists every page linking to the current page.
+
+## Installation
+
+You can install it with `pip`:
+```bash
+pip install mkdocs-backlinks-section-plugin
+```
+
+## Usage
+
+Add the plugin to your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section
+```
+
+## Configuration
+
+You can customize the text inserted by the plugin with the configuration values below:
+
+Option | Type | Default value
+--- | --- | ---
+`title` | string | `Backlinks`
+`description` | string | `The following pages link to this page:`
+`description_no_links` | string | `No other pages link to this page.`
+
+
+So for example if you would want the text to be in German, you could do this in your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section:
+    title: Rückverweise
+    description: "Die folgenden Seiten referenzieren die aktuelle Seite:"
+    description_no_links: Es gibt keine Verweise auf diese Seite.
+```
+
+## Notable changes
+
+### Version 0.0.1
+
+- Initial version

mkdocs_backlinks_section_plugin-0.0.1/README.md

@@ -0,0 +1,50 @@
+# MkDocs Backlinks Section Plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-backlinks-section-plugin)](https://pypi.org/project/mkdocs-backlinks-section-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-backlinks-section-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-backlinks-section-plugin)
+
+Adds a backlinks section that lists every page linking to the current page.
+
+## Installation
+
+You can install it with `pip`:
+```bash
+pip install mkdocs-backlinks-section-plugin
+```
+
+## Usage
+
+Add the plugin to your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section
+```
+
+## Configuration
+
+You can customize the text inserted by the plugin with the configuration values below:
+
+Option | Type | Default value
+--- | --- | ---
+`title` | string | `Backlinks`
+`description` | string | `The following pages link to this page:`
+`description_no_links` | string | `No other pages link to this page.`
+
+
+So for example if you would want the text to be in German, you could do this in your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section:
+    title: Rückverweise
+    description: "Die folgenden Seiten referenzieren die aktuelle Seite:"
+    description_no_links: Es gibt keine Verweise auf diese Seite.
+```
+
+## Notable changes
+
+### Version 0.0.1
+
+- Initial version

mkdocs_backlinks_section_plugin-0.0.1/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

mkdocs_backlinks_section_plugin-0.0.1/setup.cfg

@@ -0,0 +1,41 @@
+[metadata]
+name = mkdocs-backlinks-section-plugin
+version = 0.0.1
+author = six-two
+author_email = pip@six-two.dev
+description = Adds a backlinks section that lists every page linking to the current page.
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/six-two/mkdocs-backlinks-section-plugin
+license = MIT License
+classifiers = 
+	License :: OSI Approved :: MIT License
+	Operating System :: POSIX :: Linux
+	Programming Language :: Python :: 3
+	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
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.9
+scripts = 
+install_requires = 
+	mkdocs>=1.5.0 # Needed for mkdocs.plugins.get_plugin_logger
+
+[options.entry_points]
+mkdocs.plugins = 
+	backlinks_section = mkdocs_backlinks_section_plugin:BacklinksSectionPlugin
+
+[options.packages.find]
+where = src
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin/__init__.py

@@ -0,0 +1,128 @@
+# builtin
+
+# The idea is based roughly on https://github.com/danodic-dev/mkdocs-backlinks, but instead of dealing with a template, this plugin just injects the backlinks into the HTML at the bottom of the page
+import os
+import html
+import random
+import re
+from typing import Optional
+# pip
+from mkdocs.config.base import Config
+from mkdocs.config.config_options import Type
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin, get_plugin_logger
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+# Marks URLs that should be ignored
+BAD_URL_STARTS = ["http://", "https://", "tel:", "#"]
+# Regular expression for anchor tags
+LINK_START_TAG_REGEX = re.compile(r"<a[^>]*>", re.MULTILINE)
+# Logger
+LOGGER = get_plugin_logger(__name__)
+
+class BacklinksSectionConfig(Config):
+    title = Type(str, default="Backlinks")
+    description = Type(str, default="The following pages link to this page:")
+    description_no_links = Type(str, default="No other pages link to this page.")
+
+
+class BacklinksSectionPlugin(BasePlugin[BacklinksSectionConfig]):
+    def __init__(self):
+        # Use a random placeholder to prevent accidential collisions with strings like BACKLINK_PLUGIN
+        self.backlink_placeholder = f"BACKLINK_PLUGIN_{random.randint(0,10000000)}_PLACEHOLDER"
+    
+    def on_nav(self, nav, config: MkDocsConfig, files: Files):
+        # self.backlinks | normalized_url: str -> (page_url: str, page_title: str)
+        self.backlinks: dict[str,set[tuple[str,str]]] = {normalize_link(file.url): set() for file in files}
+        return nav
+
+    def on_page_markdown(self, markdown, page: Page, config: MkDocsConfig, files: Files) -> str:
+        # Add backlinks section placeholder
+        # We need to do this in the Markdown phase, so that the new section is added to the table of contents
+        return f"{markdown}\n\n## {self.config.title}\n\n{self.backlink_placeholder}"
+
+    def on_page_content(self, html, page: Page, config: MkDocsConfig, files: Files) -> str:
+        # Collect the backlinks
+        for url in parse_links_to_other_pages(html):
+            destination_link = normalize_link(url, page.url)
+
+            if destination_link in self.backlinks:
+                self.backlinks[destination_link].add((page.url, page.title))
+
+        return html
+
+    def on_post_page(self, output: str, page: Page, config: MkDocsConfig) -> str:
+        # Insert the backlink list
+        key = normalize_link(page.url, "")
+        links = self.backlinks[key]
+        if links:
+            backlink_html = f"<p>{html.escape(self.config.description)}</p>" if self.config.description else ""
+            backlink_html += "<ul>"
+            # sort by title
+            for link, title in sorted(links, key=lambda x: x[1]):
+                link_to_page = "/" + link # @TODO: only for testing, this will break later # @TODO: escape?
+                backlink_html += f'<li><a href="{link_to_page}">{html.escape(title)}</a></li>'
+            backlink_html += "</ul>"
+            output = output.replace(self.backlink_placeholder, backlink_html)
+        else:
+            output = output.replace(self.backlink_placeholder, f"<p>{html.escape(self.config.description_no_links)}</p>")
+        return output
+
+
+def normalize_link(path: str, base_url: str = "") -> str:
+    path = path.split("#", 1)[0] # Remove anything after a hashtag (exact anchor on page)
+
+    # @TODO: isn't this dependent on how directory urls? A: probs not, does not need to be "right", just consistent(ly wrong)
+    if path.startswith("/"):
+        # Absolute URL
+        path = os.path.normpath(path)[1:]
+    else:
+        if base_url:
+            path = os.path.join(os.path.dirname(base_url), path)
+    
+        path = os.path.normpath(path)
+    
+    if path.endswith("/index.html") or path == "index.html":
+        path = path[:-len("index.html")]
+
+    return path
+
+def is_valid_link(url: str) -> bool:
+    url = url.lower()
+    for bad_pattern in BAD_URL_STARTS:
+        if url.startswith(bad_pattern):
+            # Url is not a local path
+            return False
+    # Url is probably a local file
+    return True
+
+
+def parse_href_from_anchor_tag(anchor_tag: str) -> Optional[str]:
+    for part in anchor_tag.split():
+        if part.endswith(">"):
+            part = part[:-1]
+        if part.startswith("href="):
+            link = part[5:]
+            if link[0] in ["\"", "'"]:
+                if link[0] == link[-1]:
+                    return link[1:-1]
+                else:
+                    LOGGER.warn(f"href does not have matching quotes: {link}")
+                    return ""
+            else:
+                return link
+    
+    LOGGER.warn(f"anchor tag has no href: {anchor_tag}")
+    return ""
+
+
+def parse_links_to_other_pages(html: str) -> list[str]:
+    results = []
+    for link_start_tag in LINK_START_TAG_REGEX.findall(html):
+        link = parse_href_from_anchor_tag(link_start_tag)
+        if link and is_valid_link(link):
+            results.append(link)
+    
+    return results
+

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.1
+Name: mkdocs-backlinks-section-plugin
+Version: 0.0.1
+Summary: Adds a backlinks section that lists every page linking to the current page.
+Home-page: https://github.com/six-two/mkdocs-backlinks-section-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
+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.5.0
+
+# MkDocs Backlinks Section Plugin
+
+[![PyPI version](https://img.shields.io/pypi/v/mkdocs-backlinks-section-plugin)](https://pypi.org/project/mkdocs-backlinks-section-plugin/)
+![License](https://img.shields.io/pypi/l/mkdocs-backlinks-section-plugin)
+![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-backlinks-section-plugin)
+
+Adds a backlinks section that lists every page linking to the current page.
+
+## Installation
+
+You can install it with `pip`:
+```bash
+pip install mkdocs-backlinks-section-plugin
+```
+
+## Usage
+
+Add the plugin to your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section
+```
+
+## Configuration
+
+You can customize the text inserted by the plugin with the configuration values below:
+
+Option | Type | Default value
+--- | --- | ---
+`title` | string | `Backlinks`
+`description` | string | `The following pages link to this page:`
+`description_no_links` | string | `No other pages link to this page.`
+
+
+So for example if you would want the text to be in German, you could do this in your `mkdocs.yml`:
+```yaml
+plugins:
+- search
+- backlinks_section:
+    title: Rückverweise
+    description: "Die folgenden Seiten referenzieren die aktuelle Seite:"
+    description_no_links: Es gibt keine Verweise auf diese Seite.
+```
+
+## Notable changes
+
+### Version 0.0.1
+
+- Initial version

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/mkdocs_backlinks_section_plugin/__init__.py
+src/mkdocs_backlinks_section_plugin.egg-info/PKG-INFO
+src/mkdocs_backlinks_section_plugin.egg-info/SOURCES.txt
+src/mkdocs_backlinks_section_plugin.egg-info/dependency_links.txt
+src/mkdocs_backlinks_section_plugin.egg-info/entry_points.txt
+src/mkdocs_backlinks_section_plugin.egg-info/requires.txt
+src/mkdocs_backlinks_section_plugin.egg-info/top_level.txt

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+backlinks_section = mkdocs_backlinks_section_plugin:BacklinksSectionPlugin

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/requires.txt

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

mkdocs_backlinks_section_plugin-0.0.1/src/mkdocs_backlinks_section_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_backlinks_section_plugin