mkdocs-include-markdown-plugin 7.1.1__tar.gz → 7.1.3__tar.gz

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2017-2024 Joe Rickerby and contributors
+   Copyright 2017-2025 Joe Rickerby and contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mkdocs-include-markdown-plugin
-Version: 7.1.1
+Version: 7.1.3
 Summary: Mkdocs Markdown includer plugin.
 Project-URL: Source, https://github.com/mondeja/mkdocs-include-markdown-plugin
 Project-URL: Documentation, https://github.com/mondeja/mkdocs-include-markdown-plugin#documentation
@@ -9,7 +9,8 @@ Project-URL: Changelog, https://github.com/mondeja/mkdocs-include-markdown-plugi
 Author: Joe Rickerby
 Author-email: Álvaro Mondéjar Rubio <mondejar1994@gmail.com>
 Maintainer-email: Álvaro Mondéjar Rubio <mondejar1994@gmail.com>
-License: Apache-2.0
+License-Expression: Apache-2.0
+License-File: LICENSE
 Keywords: includer,markdown,mkdocs,plugin
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
@@ -135,8 +136,9 @@ plugins:
       cache: 600
 ```
 
-In order to use this feature, the dependency [platformdirs] must be installed.
-You can include it in the installation of the plugin adding the `cache` extra:
+In order to use this feature, the dependency [platformdirs] must be installed
+or the setting [`cache_dir`](#cache_dir) must be defined. You can include
+[platformdirs] in the installation of the plugin adding the `cache` extra:
 
 ```txt
 # requirements.txt
@@ -145,6 +147,23 @@ mkdocs-include-markdown-plugin[cache]
 
 <!-- mdpo-disable-next-line -->
 
+#### `cache_dir`
+
+Directory where cached HTTP requests will be stored. If set, [platformdirs] is not
+needed to be installed to use [`cache`](#cache).
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+      cache_dir: ./mkdocs-include-markdown-cache
+```
+
+A _.gitignore_ file will be added to the cache directory if not exists to avoid
+committing the cache files.
+
+<!-- mdpo-disable-next-line -->
+
 #### `directives`
 
 Customize the names of the directives.

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/README.md

@@ -101,8 +101,9 @@ plugins:
       cache: 600
 ```
 
-In order to use this feature, the dependency [platformdirs] must be installed.
-You can include it in the installation of the plugin adding the `cache` extra:
+In order to use this feature, the dependency [platformdirs] must be installed
+or the setting [`cache_dir`](#cache_dir) must be defined. You can include
+[platformdirs] in the installation of the plugin adding the `cache` extra:
 
 ```txt
 # requirements.txt
@@ -111,6 +112,23 @@ mkdocs-include-markdown-plugin[cache]
 
 <!-- mdpo-disable-next-line -->
 
+#### `cache_dir`
+
+Directory where cached HTTP requests will be stored. If set, [platformdirs] is not
+needed to be installed to use [`cache`](#cache).
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+      cache_dir: ./mkdocs-include-markdown-cache
+```
+
+A _.gitignore_ file will be added to the cache directory if not exists to avoid
+committing the cache files.
+
+<!-- mdpo-disable-next-line -->
+
 #### `directives`
 
 Customize the names of the directives.

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "7.1.1"
+version = "7.1.3"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"
@@ -104,9 +104,9 @@ targets = [{ file = "pyproject.toml" }]
 [tool.project-config]
 cache = "2 days"
 style = [
-  "gh://mondeja/project-config-styles@v5.4/base/pre-commit/md2po2md.json5",
-  "gh://mondeja/project-config-styles@v5.4/python/base.json5",
-  "gh://mondeja/project-config-styles@v5.4/python/mypy.json5",
+  "gh://mondeja/project-config-styles@v5.5/base/pre-commit/md2po2md.json5",
+  "gh://mondeja/project-config-styles@v5.5/python/base.json5",
+  "gh://mondeja/project-config-styles@v5.5/python/mypy.json5",
 ]
 
 [tool.coverage.run]

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/cache.py

@@ -9,9 +9,6 @@ import time
 from importlib.util import find_spec
 
 
-CACHE_AVAILABLE = find_spec('platformdirs') is not None
-
-
 class Cache:
     """Cache for arbitrary content, one file per entry."""
 
@@ -46,7 +43,7 @@ class Cache:
             is_file = stat.S_ISREG(os.stat(fpath).st_mode)
         except (FileNotFoundError, OSError):  # pragma: no cover
             return None
-        if is_file:
+        if is_file:  # pragma: no branch
             creation_time = self.get_creation_time_from_fpath(fpath)
             if time.time() < creation_time + self.expiration_seconds:
                 return self.read_file(fpath, encoding=encoding)
@@ -64,31 +61,52 @@ class Cache:
     def clean(self) -> None:
         """Clean expired entries from the cache."""
         for fname in os.listdir(self.cache_dir):
+            if fname == '.gitignore':
+                continue
             fpath = os.path.join(self.cache_dir, fname)
             creation_time = self.get_creation_time_from_fpath(fpath)
             if time.time() > creation_time + self.expiration_seconds:
                 os.remove(fpath)
 
 
-def get_cache_directory() -> str | None:
-    """Get the cache directory."""
-    if not CACHE_AVAILABLE:
+def get_cache_directory(cache_dir: str) -> str | None:
+    """Get cache directory."""
+    if cache_dir:
+        return cache_dir
+
+    if not is_platformdirs_installed():
         return None
 
     try:
         from platformdirs import user_data_dir
-    except ImportError:
+    except ImportError:  # pragma: no cover
+        return None
+    else:
+        return user_data_dir('mkdocs-include-markdown-plugin')
+
+
+def initialize_cache(expiration_seconds: int, cache_dir: str) -> Cache | None:
+    """Initialize a cache instance."""
+    cache_directory = get_cache_directory(cache_dir)
+
+    if cache_directory is None:
         return None
 
-    cache_dir = user_data_dir('mkdocs-include-markdown-plugin')
-    os.makedirs(cache_dir, exist_ok=True)
+    os.makedirs(cache_directory, exist_ok=True)
 
-    return cache_dir
+    # Add a `.gitignore` file to prevent the cache directory from being
+    # included in the repository. This is needed because the cache directory
+    # can be configured as a relative path with `cache_dir` setting.
+    gitignore = os.path.join(cache_directory, '.gitignore')
+    if not os.path.exists(gitignore):
+        with open(gitignore, 'wb') as f:
+            f.write(b'*\n')
 
+    cache = Cache(cache_directory, expiration_seconds)
+    cache.clean()
+    return cache
 
-def initialize_cache(expiration_seconds: int) -> Cache | None:
-    """Initialize a cache instance."""
-    cache_dir = get_cache_directory()
-    return None if cache_dir is None else Cache(
-        cache_dir, expiration_seconds,
-    )
+
+def is_platformdirs_installed() -> bool:
+    """Check if `platformdirs` package is installed without importing it."""
+    return find_spec('platformdirs') is not None

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/config.py

@@ -24,6 +24,7 @@ class PluginConfig(Config):  # noqa: D101
     end = Optional(MkType(str))
     exclude = ListOfItems(MkType(str), default=[])
     cache = MkType(int, default=0)
+    cache_dir = MkType(str, default='')
     recursive = MkType(bool, default=True)
     directives = MkType(
         dict,

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/directive.py

@@ -306,7 +306,6 @@ def resolve_file_paths_to_exclude(
     docs_dir: str,
 ) -> list[str]:
     """Resolve the file paths to exclude for a directive."""
-    root_dir = None
     if process.is_absolute_path(exclude_string):
         return glob.glob(exclude_string, flags=GLOB_FLAGS)
 
@@ -330,7 +329,7 @@ def resolve_file_paths_to_exclude(
             )
         ]
 
-    return glob.glob(
+    return glob.glob(  # pragma: no cover
         exclude_string,
         flags=GLOB_FLAGS,
         root_dir=docs_dir,

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/event.py

@@ -83,21 +83,20 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         http_cache: Cache | None = None,
 ) -> str:
     """Return the content of the file to include."""
-    settings_ignore_paths = []
-    if settings.exclude is not None:
-        for path in glob.glob(
-                [
-                    os.path.join(docs_dir, fp)
-                    if not os.path.isabs(fp)
-                    else fp for fp in settings.exclude
-                ],
-                flags=GLOB_FLAGS,
-                root_dir=docs_dir,
-        ):
-            if path not in settings_ignore_paths:
-                settings_ignore_paths.append(path)
+    if settings.exclude:
+        settings_ignore_paths = list(glob.glob(
+            [
+                os.path.join(docs_dir, fp)
+                if not os.path.isabs(fp)
+                else fp for fp in settings.exclude
+            ],
+            flags=GLOB_FLAGS,
+            root_dir=docs_dir,
+        ))
         if page_src_path in settings_ignore_paths:
             return markdown
+    else:
+        settings_ignore_paths = []
 
     new_found_include_contents: list[tuple[str, str]] = []
     new_found_include_markdown_contents: list[tuple[str, str]] = []
@@ -150,8 +149,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             for path in resolve_file_paths_to_exclude(
                 exclude_string, page_src_path, docs_dir,
             ):
-                if path not in ignore_paths:
-                    ignore_paths.append(path)
+                ignore_paths.append(path)
 
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,
@@ -361,8 +359,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             for path in resolve_file_paths_to_exclude(
                 exclude_string, page_src_path, docs_dir,
             ):
-                if path not in ignore_paths:
-                    ignore_paths.append(path)
+                ignore_paths.append(path)
 
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/plugin.py

@@ -31,22 +31,19 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
 
     def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
         if self.config.cache > 0:
-            cache = initialize_cache(self.config.cache)
+            cache = initialize_cache(self.config.cache, self.config.cache_dir)
             if cache is None:
                 raise PluginError(
-                    'The "platformdirs" package is required to use the'
-                    ' "cache" option. Install'
-                    ' mkdocs-include-markdown-plugin with the "cache"'
-                    ' extra to install it.',
+                    'Either `cache_dir` global setting must be configured or'
+                    ' `platformdirs` package is required to use the'
+                    ' `cache` option. Install mkdocs-include-markdown-plugin'
+                    " with the 'cache' extra to install `platformdirs`.",
                 )
-            cache.clean()
             self._cache = cache
 
         if '__default' not in self.config.directives:  # pragma: no cover
             for directive in self.config.directives:
-                if directive not in {
-                    'include', 'include-markdown',
-                }:
+                if directive not in ('include', 'include-markdown'):
                     raise PluginError(
                         f"Invalid directive name '{directive}' at 'directives'"
                         ' global setting. Valid values are "include" and'

{mkdocs_include_markdown_plugin-7.1.1 → mkdocs_include_markdown_plugin-7.1.3}/src/mkdocs_include_markdown_plugin/process.py

@@ -112,6 +112,49 @@ MARKDOWN_LINK_DEFINITION_REGEX = re.compile(
     flags=re.VERBOSE | re.MULTILINE,
 )
 
+# Matched html image and source definition.
+# e.g. <img src="path/to/image.png" alt="alt-text">
+# e.g. <source src="path/to/image.png" alt="alt-text">
+MARKDOWN_HTML_IMAGE_REGEX = re.compile(
+    r'''
+        <(?:img|source)    # img or source
+        (?:\s+             # More than one whitespace
+            (?!src=)       # Not src=
+            [\w-]+         # attribute name
+            (?:\s*=\s*)?   # arbitrary whitespace (optional)
+            (?:
+                "[^"]*"    # Quoted value (double quote)
+                |
+                '[^']*'    # Quoted value (single quote)
+            )?
+        )*                 # Other attributes are repeated 0 or more times
+        \s+                # More than one whitespace
+        src=["'](\S+?)["'] # src = $1 (double quote or single quote)
+    ''',
+    flags=re.VERBOSE | re.MULTILINE,
+)
+
+# Matched html anchor definition.
+# e.g. <a href="https://example.com">example</a>
+MARKDOWN_HTML_ANCHOR_DEFINITION_REGEX = re.compile(
+    r'''
+        <a
+        (?:\s+             # More than one whitespace
+            (?!href=)      # Not href=
+            [\w-]+         # attribute name
+            (?:\s*=\s*)?   # arbitrary whitespace (optional)
+            (?:
+                "[^"]*"    # Quoted value (double quote)
+                |
+                '[^']*'    # Quoted value (single quote)
+            )?
+        )*                 # Other attributes are repeated 0 or more times
+        \s+                # More than one whitespace
+        href=["'](\S+?)["']# href = $1 (double quote or single quote)
+    ''',
+    flags=re.VERBOSE | re.MULTILINE,
+)
+
 
 def transform_p_by_p_skipping_codeblocks(  # noqa: PLR0912, PLR0915
         markdown: str,
@@ -244,10 +287,10 @@ def rewrite_relative_urls(
     ``source_path`` will still work when inserted into a file at
     ``destination_path``.
     """
-    def rewrite_url(url: str) -> str:
-        from urllib.parse import urlparse, urlunparse
+    from urllib.parse import urlparse, urlunparse
 
-        if is_relative_path(url):
+    def rewrite_url(url: str) -> str:
+        if is_url(url):
             return url
 
         scheme, netloc, path, params, query, fragment = urlparse(url)
@@ -299,10 +342,18 @@ def rewrite_relative_urls(
             found_href_url_group_index_3,
             paragraph,
         )
-        return MARKDOWN_LINK_DEFINITION_REGEX.sub(
+        paragraph = MARKDOWN_LINK_DEFINITION_REGEX.sub(
             functools.partial(found_href, url_group_index=2),
             paragraph,
         )
+        paragraph = MARKDOWN_HTML_IMAGE_REGEX.sub(
+            functools.partial(found_href, url_group_index=1),
+            paragraph,
+        )
+        return MARKDOWN_HTML_ANCHOR_DEFINITION_REGEX.sub(
+            functools.partial(found_href, url_group_index=1),
+            paragraph,
+        )
 
     return transform_p_by_p_skipping_codeblocks(
         markdown,
@@ -425,7 +476,7 @@ def increase_headings_offset(markdown: str, offset: int = 0) -> str:
 
 def rstrip_trailing_newlines(content: str) -> str:
     """Removes trailing newlines from a string."""
-    while content.endswith('\n') or content.endswith('\r'):
+    while content.endswith(('\n', '\r')):
         content = content.rstrip('\r\n')
     return content