mkdocs-permalinks-plugin 0.1.0__py3-none-any.whl

mkdocs_permalinks_plugin/plugin.py

@@ -0,0 +1,253 @@
+import re
+import os
+import logging
+import urllib.parse
+
+from mkdocs.plugins import BasePlugin
+import mkdocs.utils
+from mkdocs.config import config_options
+
+log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+log.addFilter(mkdocs.utils.warning_filter)
+
+# For Regex, match groups are:
+#       0: Whole markdown link e.g. [Alt-text](url)
+#       1: Alt text
+#       2: Full URL e.g. url + hash anchor
+#       3: Filename e.g. filename.md
+#       4: File extension e.g. .md, .png, etc.
+#       5. hash anchor e.g. #my-sub-heading-link
+AUTOLINK_RE = r'\[([^\]]+)\]\((([^)/]+\.(md|png|jpg))(#.*)*)\)'
+
+# For Regex, match groups are:
+#       0: Whole roamlike link e.g. [[filename#title|alias|widthxheight]]
+#       1: Link content e.g. filename#title|alias|widthxheight
+ROAMLINK_RE = r"""\[\[(.*?)\]\](?!\])"""
+
+# Regex to match both inline and fenced codeblocks
+CODEBLOCK_RE = r'(```.*?```|`.*?`)'
+
+class AutoLinkReplacer:
+    def __init__(self, base_docs_url, page_url):
+        self.base_docs_url = base_docs_url
+        self.page_url = page_url
+
+    def __call__(self, match):
+        # Name of the markdown file
+        filename = urllib.parse.unquote(match.group(3).strip())
+
+        # Absolute URL of the linker
+        abs_linker_url = os.path.dirname(
+            os.path.join(self.base_docs_url, self.page_url))
+
+        # Find directory URL to target link
+        rel_link_url = ''
+        # Walk through all files in docs directory to find a matching file
+        for root, dirs, files in os.walk(self.base_docs_url, followlinks=True):
+            for name in files:
+                # If we have a match, create the relative path from linker to the link
+                if name == filename:
+                    # Absolute path to the file we want to link to
+                    abs_link_url = os.path.dirname(os.path.join(root, name))
+                    # Constructing relative path from the linker to the link
+                    rel_link_url = os.path.join(
+                        os.path.relpath(abs_link_url, abs_linker_url),
+                        filename)
+        if rel_link_url == '':
+            log.warning(f"AutoLinksPlugin unable to find {filename} in directory {self.base_docs_url}")
+            return match.group(0)
+
+        # Construct the return link by replacing the filename with the relative path to the file
+        if (match.group(5) == None):
+            link = match.group(0).replace(match.group(2), rel_link_url)
+        else:
+            link = match.group(0).replace(match.group(2),
+                                          rel_link_url + match.group(5))
+        return link
+
+
+class RoamLinkReplacer:
+    def __init__(self, base_docs_url, page_url):
+        self.base_docs_url = base_docs_url
+        self.page_url = page_url
+
+    def simplify(self, filename):
+        """ ignore - _ and space different, replace .md to '' so it will match .md file,
+        if you want to link to png, make sure you filename contain suffix .png, same for other files
+        but if you want to link to markdown, you don't need suffix .md """
+        return re.sub(r"[\-_ ]", "", filename.lower()).replace(".md", "")
+
+    def gfm_anchor(self, title):
+        """Convert to gfw title / anchor
+        see: https://gist.github.com/asabaylus/3071099#gistcomment-1593627"""
+        if title:
+            title = title.strip().lower()
+            title = re.sub(r'[^\w\u4e00-\u9fff\- ]', "", title)
+            title = re.sub(r' +', "-", title)
+            return title
+        else:
+            return ""
+
+    def unresolved_text(self, filename, title, alias):
+        """Return the plain text to keep when no target file can be found."""
+        if alias:
+            return alias
+        return filename + title
+
+    def parse_link_content(self, content):
+        filename = ""
+        title = ""
+        alias = ""
+        width = ""
+        height = ""
+
+        parts = content.split("|")
+        target = parts[0].strip()
+        modifiers = parts[1:]
+
+        if modifiers:
+            size = modifiers[-1].strip()
+            size_match = re.fullmatch(r"(\d+)(?:x(\d+))?", size)
+            if size_match:
+                width = size_match.group(1) or ""
+                height = size_match.group(2) or ""
+                modifiers = modifiers[:-1]
+            if modifiers:
+                alias = "|".join(modifiers)
+
+        if target.startswith("#"):
+            title = target
+        elif "#" in target:
+            filename, heading = target.split("#", 1)
+            title = "#" + heading
+            filename = filename.strip()
+        else:
+            filename = target
+
+        return filename, title, alias, width, height
+
+    def __call__(self, match):
+        # Name of the markdown file
+        filename, title, alias, width, height = self.parse_link_content(match.group(1))
+        format_title = self.gfm_anchor(title)
+
+        # Absolute URL of the linker
+        abs_linker_url = os.path.dirname(
+            os.path.join(self.base_docs_url, self.page_url))
+
+        # Find directory URL to target link
+        rel_link_url = ''
+        # Walk through all files in docs directory to find a matching file
+        if filename:
+            if '/' in filename:
+                if 'http' in filename: # http or https
+                    rel_link_url = filename
+                else:
+                    rel_file = filename
+                    if not '.' in filename:   # don't have extension type
+                        rel_file = filename + ".md"
+
+                    abs_link_url = os.path.dirname(os.path.join(
+                        self.base_docs_url, rel_file))
+                    # Constructing relative path from the linker to the link
+                    rel_link_url = os.path.join(
+                            os.path.relpath(abs_link_url, abs_linker_url), os.path.basename(rel_file))
+                    if title:
+                        rel_link_url = rel_link_url + '#' + format_title
+            else:
+                for root, dirs, files in os.walk(self.base_docs_url, followlinks=True):
+                    for name in files:
+                        # If we have a match, create the relative path from linker to the link
+                        if self.simplify(name) == self.simplify(filename):
+                            # Absolute path to the file we want to link to
+                            abs_link_url = os.path.dirname(os.path.join(
+                                root, name))
+                            # Constructing relative path from the linker to the link
+                            rel_link_url = os.path.join(
+                                    os.path.relpath(abs_link_url, abs_linker_url), name)
+                            if title:
+                                rel_link_url = rel_link_url + '#' + format_title
+            if rel_link_url == '':
+                log.warning(f"PermaLinksPlugin unable to find {filename} in directory {self.base_docs_url}")
+                return self.unresolved_text(filename, title, alias)
+        else:
+            rel_link_url = '#' + format_title
+
+        # Construct the return link
+        # Windows escapes "\" unintentionally, and it creates incorrect links, so need to replace with "/"
+        rel_link_url = rel_link_url.replace("\\", "/")
+
+        if filename:
+            if alias:
+                link = f'[{alias}](<{rel_link_url}>)'
+            else:
+                link = f'[{filename+title}](<{rel_link_url}>)'
+        else:
+            if alias:
+                link = f'[{alias}](<{rel_link_url}>)'
+            else:
+                link = f'[{title}](<{rel_link_url}>)'
+
+        if width and not height:
+            link = f'{link}{{ width="{width}" }}'
+        elif not width and height:
+            link = f'{link}{{ height="{height}" }}'
+        elif width and height:
+            link = f'{link}{{ width="{width}"; height="{height}" }}'
+
+        return link
+
+def redact_codeblocks(markdown):
+    """ Redact codeblocks to avoid processing links inside codeblocks """
+    codeblock_re = re.compile(CODEBLOCK_RE, re.DOTALL)
+    redacted_blocks = {}
+
+    def replacer(match):
+        key = f"\x01__CODEBLOCK_{len(redacted_blocks)}__\x02"
+        redacted_blocks[key] = match.group(0)
+        return key
+    
+    redacted_markdown = codeblock_re.sub(replacer, markdown)
+    return redacted_markdown, redacted_blocks
+
+def restore_codeblocks(markdown, redacted_blocks):
+    """ Restore redacted codeblocks """
+    for key, block in redacted_blocks.items():
+        markdown = markdown.replace(key, block)
+
+    return markdown
+
+class PermaLinksPlugin(BasePlugin):
+    config_scheme = (
+        ('ignore_codeblocks', config_options.Type(bool, default=True)),
+    )
+
+    def on_page_markdown(self,
+                         markdown,
+                         page,
+                         config,
+                         site_navigation=None,
+                         **kwargs):
+
+        # Getting the root location of markdown source files
+        base_docs_url = config["docs_dir"]
+
+        # Getting the page url that we are linking from
+        page_url = page.file.src_path
+
+        # Redact codeblocks
+        redacted_blocks = {}
+        if self.config['ignore_codeblocks']:
+            markdown, redacted_blocks = redact_codeblocks(markdown)
+
+        # Look for matches and replace
+        markdown = re.sub(AUTOLINK_RE,
+                          AutoLinkReplacer(base_docs_url, page_url), markdown)
+        markdown = re.sub(ROAMLINK_RE,
+                          RoamLinkReplacer(base_docs_url, page_url), markdown)
+        
+        # Restore codeblocks
+        if self.config['ignore_codeblocks']:
+            markdown = restore_codeblocks(markdown, redacted_blocks)
+
+        return markdown

mkdocs_permalinks_plugin-0.1.0.dist-info/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Matthew Marchetti
+
+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_permalinks_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.1
+Name: mkdocs-permalinks-plugin
+Version: 0.1.0
+Summary: An MkDocs plugin
+Home-page: https://github.com/Mattlock0/mkdocs-permalinks-plugin
+Author: 
+Author-email: visionofhonor@gmail.com
+License: MIT
+Keywords: mkdocs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Requires-Python: >=3.6
+License-File: LICENSE
+Requires-Dist: mkdocs >=1.0.4
+Provides-Extra: dev
+Requires-Dist: pytest ; extra == 'dev'
+
+An MkDocs plugin that automagically generates relative links and convert links for foam and obsidian between markdown pages

mkdocs_permalinks_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mkdocs_permalinks_plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_permalinks_plugin/plugin.py,sha256=ePLOmu40Ho-DbG6onAJ-3QN3cMHB-K6crzez_aIUW-k,9939
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_plugin.py,sha256=pKeZ9kQHAMv7NqT9XzpfW2FvMaiXo4tCrU-oWGV8YUc,7711
+mkdocs_permalinks_plugin-0.1.0.dist-info/LICENSE,sha256=TgPExXd9i1aGN11nz1N_jZVzUsZBdsIfvDCGYVU1LFs,1080
+mkdocs_permalinks_plugin-0.1.0.dist-info/METADATA,sha256=YYcZ6xDR-8Wk31a6VJlv3RvtUUbVHQwwT0k8hVy10vY,855
+mkdocs_permalinks_plugin-0.1.0.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
+mkdocs_permalinks_plugin-0.1.0.dist-info/entry_points.txt,sha256=lKDJfVVxspi_yhtPsA0Mh80wjQ1jFXn15BfP06ZPZtY,79
+mkdocs_permalinks_plugin-0.1.0.dist-info/top_level.txt,sha256=TeA-b4N3MvhuRK9U6tY8hQiYRDlfYpsPE834N0WwEMY,31
+mkdocs_permalinks_plugin-0.1.0.dist-info/RECORD,,

mkdocs_permalinks_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.41.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_permalinks_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+permalinks = mkdocs_permalinks_plugin.plugin:PermaLinksPlugin

mkdocs_permalinks_plugin-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+mkdocs_permalinks_plugin
+tests

tests/test_plugin.py

@@ -0,0 +1,194 @@
+import os
+import tempfile
+import pytest
+
+from mkdocs.structure.files import File
+from mkdocs.structure.pages import Page
+from mkdocs_permalinks_plugin.plugin import PermaLinksPlugin
+
+
+@pytest.fixture
+def temp_directory():
+    with tempfile.TemporaryDirectory() as temp_dir:
+        yield temp_dir
+
+
+@pytest.fixture
+def config(temp_directory):
+    return {"docs_dir": temp_directory}
+
+
+@pytest.fixture
+def site_navigation():
+    return []
+
+
+@pytest.fixture
+def page(temp_directory):
+    os.mkdir(os.path.join(temp_directory, "test"))
+    file_path = os.path.join(temp_directory, "test", "test.md")
+    with open(file_path, "w", encoding="utf8") as f:
+        f.write("# Heading identifiers in HTML")
+    with open(os.path.join(temp_directory, "demo (t).md"), "w", encoding="utf8") as f:
+        f.write("# Demo Page")
+    with open(os.path.join(temp_directory, "image.png"), "w", encoding="utf8") as f:
+        f.write("# Image Page")
+    with open(os.path.join(temp_directory, "image (1).png"), "w", encoding="utf8") as f:
+        f.write("# Image Page")
+    with open(os.path.join(temp_directory, "41m+ZoNoWqL._AC_UF894,1000_QL80_.jpg"), "w", encoding="utf8") as f:
+        f.write("# Image Page")
+    os.mkdir(os.path.join(temp_directory, "software"))
+    with open(
+        os.path.join(temp_directory, "software", "git_flow.md"), "w", encoding="utf8"
+    ) as f:
+        f.write("# Git Flow")
+
+    return Page(
+        title="Test Page",
+        file=File(file_path, temp_directory, temp_directory, False),
+        config={},
+    )
+
+@pytest.fixture
+def converter(temp_directory, config, site_navigation, page):
+    def c(markdown, ignore_codeblocks=True):
+        plugin = PermaLinksPlugin()
+        plugin.load_config({'ignore_codeblocks': ignore_codeblocks})
+        return plugin.on_page_markdown(markdown, page, config, site_navigation)
+
+    return c
+
+###############################################################################{}
+## Text Links
+###############################################################################{}
+
+def test_converts_basic_link(converter):
+    assert converter("[[Git Flow]]") == "[Git Flow](<../software/git_flow.md>)"
+
+def test_converts_link_with_slash(converter):
+    assert converter("[[software/Git Flow]]") == "[software/Git Flow](<../software/Git Flow.md>)"
+
+def test_converts_link_with_anchor_only(converter):
+    assert converter("[[#Heading identifiers]]") == "[#Heading identifiers](<#heading-identifiers>)"
+
+def test_converts_link_with_anchor(converter):
+    assert converter("[[Git Flow#Heading]]") == "[Git Flow#Heading](<../software/git_flow.md#heading>)"
+
+def test_converts_link_with_parenthesis(converter):
+    assert converter("[[demo (t)]]") == "[demo (t)](<../demo (t).md>)"
+
+def test_converts_link_with_parenthesis_and_space(converter):
+    assert converter("[demo (t)](<../demo%20(t).md>)") == "[demo (t)](<../demo%20(t).md>)"
+
+def test_converts_link_with_spaces_in_text(converter):
+    assert converter('[[Git Flow|Title With Spaces]]') == '[Title With Spaces](<../software/git_flow.md>)'
+
+def test_converts_link_with_punctuation_in_text(converter):
+    assert converter('[[Git Flow|Title, with. Punctuation!]]') == '[Title, with. Punctuation!](<../software/git_flow.md>)'
+
+def test_converts_link_with_square_brackets_in_text(converter):
+    assert converter('[[Git Flow|Title [with] square [brackets]]]') == '[Title [with] square [brackets]](<../software/git_flow.md>)'
+
+def test_converts_link_with_single_quotes_in_text(converter):
+    assert converter("[[Git Flow|Title 'with' single 'quotes']]") == "[Title 'with' single 'quotes'](<../software/git_flow.md>)"
+
+def test_converts_link_with_double_quotes_in_text(converter):
+    assert converter('[[Git Flow|Title "with" double "quotes"]]') == '[Title "with" double "quotes"](<../software/git_flow.md>)'
+
+def test_converts_link_with_fragment_identifier(converter):
+    assert converter('[[Git Flow#section|Title]]') == '[Title](<../software/git_flow.md#section>)'
+
+def test_unresolved_link_becomes_plain_text(converter):
+    assert converter("[[Missing Page]]") == "Missing Page"
+
+def test_unresolved_link_with_alias_becomes_alias_text(converter):
+    assert converter("[[Missing Page|Readable Title]]") == "Readable Title"
+
+###############################################################################{}
+## Code Blocks (ignore_codeblocks=True, default)
+###############################################################################{}
+
+def test_dont_converts_link_inside_inline_code_block(converter):
+    input_md = 'Here is a link `[[Git Flow]]` inside code'
+    assert converter(input_md) == input_md
+
+def test_dont_converts_link_inside_fenced_code_block(converter):
+    input_md = '''Here is a link
+```
+[[Git Flow]]
+```
+inside code'''
+
+    assert converter(input_md) == input_md
+
+def test_dont_converts_link_inside_fenced_code_block_with_inline_code(converter):
+    input_md = '''Here is a link
+```
+`[[Git Flow]]`
+```
+inside code'''
+
+    assert converter(input_md) == input_md
+
+###############################################################################{}
+## Code Blocks (ignore_codeblocks=False)
+###############################################################################{}
+
+def test_converts_link_inside_inline_code_block_when_ignore_false(converter):
+    input_md = 'Here is a link `[[Git Flow]]` inside code'
+    expected = 'Here is a link `[Git Flow](<../software/git_flow.md>)` inside code'
+    assert converter(input_md, ignore_codeblocks=False) == expected
+
+def test_converts_link_inside_fenced_code_block_when_ignore_false(converter):
+    input_md = '''Here is a link
+```
+[[Git Flow]]
+```
+inside code'''
+
+    expected = '''Here is a link
+```
+[Git Flow](<../software/git_flow.md>)
+```
+inside code'''
+
+    assert converter(input_md, ignore_codeblocks=False) == expected
+
+def test_converts_link_inside_fenced_code_block_with_inline_code_when_ignore_false(converter):
+    input_md = '''Here is a link
+```
+`[[Git Flow]]`
+```
+inside code'''
+
+    expected = '''Here is a link
+```
+`[Git Flow](<../software/git_flow.md>)`
+```
+inside code'''
+
+    assert converter(input_md, ignore_codeblocks=False) == expected
+
+###############################################################################{}
+## Images
+###############################################################################{}
+def test_converts_basic_image_link(converter):
+    assert converter("![[image.png]]") == '![image.png](<../image.png>)'
+
+def test_converts_crazy_image_link(converter):
+    assert converter("![[41m+ZoNoWqL._AC_UF894,1000_QL80_.jpg|Edimax EW-7811un 802.11n WiFi Adapter]]") == '![Edimax EW-7811un 802.11n WiFi Adapter](<../41m+ZoNoWqL._AC_UF894,1000_QL80_.jpg>)'
+
+def test_converts_image_link_with_width(converter):
+    assert converter("![[image.png|600]]") == '![image.png](<../image.png>){ width="600" }'
+
+def test_converts_image_link_with_width_and_height(converter):
+    assert converter("![[image.png|600x800]]") == '![image.png](<../image.png>){ width="600"; height="800" }'
+
+def test_converts_image_link_with_title_and_width(converter):
+    assert converter("![[image.png|Image|600]]") == '![Image](<../image.png>){ width="600" }'
+
+def test_converts_image_link_with_parenthesis_title_and_width(converter):
+    assert converter("![[image (1).png|Image|600]]") == '![Image](<../image (1).png>){ width="600" }'
+
+def test_converts_image_link_with_parenthesis_title_width_and_height(converter):
+    assert converter("![[image (1).png|Image|600x200]]") == '![Image](<../image (1).png>){ width="600"; height="200" }'