mkdocs-document-dates 3.6.1__tar.gz → 3.7.1__tar.gz

{mkdocs_document_dates-3.6.1 → mkdocs_document_dates-3.7.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Aaron Wang
+Copyright (c) 2026 Aaron Wang
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mkdocs_document_dates-3.7.1/MANIFEST.in

@@ -0,0 +1,9 @@
+global-exclude tests/*
+global-exclude tests/**/*
+
+global-exclude .DS_Store
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+
+graft mkdocs_document_dates/hooks
+graft mkdocs_document_dates/static

{mkdocs_document_dates-3.6.1/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.7.1}/PKG-INFO

@@ -1,28 +1,19 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.6.1
+Version: 3.7.1
 Summary: A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents
-Home-page: https://github.com/jaywhj/mkdocs-document-dates
-Author: Aaron Wang
-Author-email: aaronwqt@gmail.com
-License: MIT
+Author-email: Aaron Wang <aaronwqt@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaywhj/mkdocs-document-dates
+Project-URL: Repository, https://github.com/jaywhj/mkdocs-document-dates
+Project-URL: Documentation, https://jaywhj.netlify.app/document-dates-en
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mkdocs>=1.1.0
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
+Requires-Dist: mkdocs<=1.6.1,>=1.6
 Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # mkdocs-document-dates
 
@@ -36,7 +27,7 @@ A new generation MkDocs plugin for displaying exact **creation date, last update
 
 ## Features
 
-- [x] Always displays **exact** meta information of the document and works in any environment (no-Git, Git environments, Docker, all CI/CD build systems, etc.)
+- [x] Works in any environment: no-Git, Git environments, Docker, all CI/CD build systems, etc.
 - [x] Support list display of recently updated documents (in descending order of update date)
 - [x] Support for manually specifying date and author in `Front Matter`
 - [x] Support for multiple date formats (date, datetime, timeago)
@@ -74,23 +65,23 @@ plugins:
   - document-dates:
       position: top            # Display position: top(after title) bottom(end of document), default: top
       type: date               # Date type: date datetime timeago, default: date
-      exclude:                 # List of excluded files
+      exclude:                 # List of excluded files (support unix shell-style wildcards)
         - temp.md                  # Example: exclude the specified file
         - blog/*                   # Example: exclude all files in blog folder, including subfolders
+        - '*/index.md'             # Example: exclude all index.md files in any subfolders
 ```
 
 ## Customization Settings
 
 In addition to the above basic configuration, the plug-in also provides a wealth of customization options to meet a variety of individual needs:
 
-- [Specify Datetime](https://jaywhj.netlify.app/document-dates-en#Specify-Datetime): Introduces the mechanism for obtaining document dates and methods for personalized customization, you can manually specify the creation date and last updated date for each document
-- [Specify Author](https://jaywhj.netlify.app/document-dates-en#Specify-Author): Introduces the mechanism for obtaining document authors and methods for personalized customization, you can manually specify the author information for each document, such as name, link, avatar, email, etc.
-- [Specify Avatar](https://jaywhj.netlify.app/document-dates-en#Specify-Avatar): You can manually specify the avatar for each author, support local file path and URL path
-- [Configuration Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
-- [Use Template Variables](https://jaywhj.netlify.app/document-dates-en#Use-Template-Variables): Can be used to optimize `sitemap.xml` for site SEO; Can be used to re-customize plug-ins, etc.
-- [Add Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Add-Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Add Localization Language](https://jaywhj.netlify.app/document-dates-en#Add-Localization-Language): More localization languages for `timeago` and `tooltip` 
-- [Other Tips](https://jaywhj.netlify.app/document-dates-en#Other-Tips): Introducing the Do's of using plugin in Docker
+- [Date & Time](https://jaywhj.netlify.app/document-dates-en#Date--Time): Introduces the mechanism for obtaining document dates and methods for personalized customization, support for manually specifying the creation date and last updated date for each document
+- [Author](https://jaywhj.netlify.app/document-dates-en#Author): Introduces the mechanism for obtaining document authors and methods for personalized customization, support for manually specifying the author information for each document, such as name, link, avatar, email, etc.
+- [Avatar](https://jaywhj.netlify.app/document-dates-en#Avatar): You can manually specify the avatar for each author, support local file path and URL path
+- [Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
+- [Template Variables](https://jaywhj.netlify.app/document-dates-en#Template-Variables): Can be used to optimize `sitemap.xml` for site SEO
+- [Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
+- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip` 
 - [Development Stories](https://jaywhj.netlify.app/document-dates-en#Development-Stories): Describes the origin of the plug-in, the difficulties and solutions encountered in development, and the principles and directions of product design
 
 See the documentation for details: https://jaywhj.netlify.app/document-dates-en
@@ -99,7 +90,7 @@ See the documentation for details: https://jaywhj.netlify.app/document-dates-en
 
 ## Other Projects
 
-- [**MaterialX**](https://github.com/jaywhj/mkdocs-materialx), the next generation of mkdocs-material, is based on `mkdocs-material-9.7.0` and is named `X`. I'll be maintaining this branch continuously (since mkdocs-material will stop being maintained). 
+- [**MaterialX**](https://github.com/jaywhj/mkdocs-materialx), the next generation of mkdocs-material. Build beautiful sites the way you already know and love. Based on `mkdocs-material-9.7.1` and is named `X`, it provides ongoing maintenance and updates (since mkdocs-material will stop being maintained).  
 Updates have been released that refactor and add a lot of new features, see https://github.com/jaywhj/mkdocs-materialx/releases/
 
 <br />

{mkdocs_document_dates-3.6.1 → mkdocs_document_dates-3.7.1}/README.md

@@ -10,7 +10,7 @@ A new generation MkDocs plugin for displaying exact **creation date, last update
 
 ## Features
 
-- [x] Always displays **exact** meta information of the document and works in any environment (no-Git, Git environments, Docker, all CI/CD build systems, etc.)
+- [x] Works in any environment: no-Git, Git environments, Docker, all CI/CD build systems, etc.
 - [x] Support list display of recently updated documents (in descending order of update date)
 - [x] Support for manually specifying date and author in `Front Matter`
 - [x] Support for multiple date formats (date, datetime, timeago)
@@ -48,23 +48,23 @@ plugins:
   - document-dates:
       position: top            # Display position: top(after title) bottom(end of document), default: top
       type: date               # Date type: date datetime timeago, default: date
-      exclude:                 # List of excluded files
+      exclude:                 # List of excluded files (support unix shell-style wildcards)
         - temp.md                  # Example: exclude the specified file
         - blog/*                   # Example: exclude all files in blog folder, including subfolders
+        - '*/index.md'             # Example: exclude all index.md files in any subfolders
 ```
 
 ## Customization Settings
 
 In addition to the above basic configuration, the plug-in also provides a wealth of customization options to meet a variety of individual needs:
 
-- [Specify Datetime](https://jaywhj.netlify.app/document-dates-en#Specify-Datetime): Introduces the mechanism for obtaining document dates and methods for personalized customization, you can manually specify the creation date and last updated date for each document
-- [Specify Author](https://jaywhj.netlify.app/document-dates-en#Specify-Author): Introduces the mechanism for obtaining document authors and methods for personalized customization, you can manually specify the author information for each document, such as name, link, avatar, email, etc.
-- [Specify Avatar](https://jaywhj.netlify.app/document-dates-en#Specify-Avatar): You can manually specify the avatar for each author, support local file path and URL path
-- [Configuration Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
-- [Use Template Variables](https://jaywhj.netlify.app/document-dates-en#Use-Template-Variables): Can be used to optimize `sitemap.xml` for site SEO; Can be used to re-customize plug-ins, etc.
-- [Add Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Add-Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Add Localization Language](https://jaywhj.netlify.app/document-dates-en#Add-Localization-Language): More localization languages for `timeago` and `tooltip` 
-- [Other Tips](https://jaywhj.netlify.app/document-dates-en#Other-Tips): Introducing the Do's of using plugin in Docker
+- [Date & Time](https://jaywhj.netlify.app/document-dates-en#Date--Time): Introduces the mechanism for obtaining document dates and methods for personalized customization, support for manually specifying the creation date and last updated date for each document
+- [Author](https://jaywhj.netlify.app/document-dates-en#Author): Introduces the mechanism for obtaining document authors and methods for personalized customization, support for manually specifying the author information for each document, such as name, link, avatar, email, etc.
+- [Avatar](https://jaywhj.netlify.app/document-dates-en#Avatar): You can manually specify the avatar for each author, support local file path and URL path
+- [Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
+- [Template Variables](https://jaywhj.netlify.app/document-dates-en#Template-Variables): Can be used to optimize `sitemap.xml` for site SEO
+- [Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
+- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip` 
 - [Development Stories](https://jaywhj.netlify.app/document-dates-en#Development-Stories): Describes the origin of the plug-in, the difficulties and solutions encountered in development, and the principles and directions of product design
 
 See the documentation for details: https://jaywhj.netlify.app/document-dates-en
@@ -73,7 +73,7 @@ See the documentation for details: https://jaywhj.netlify.app/document-dates-en
 
 ## Other Projects
 
-- [**MaterialX**](https://github.com/jaywhj/mkdocs-materialx), the next generation of mkdocs-material, is based on `mkdocs-material-9.7.0` and is named `X`. I'll be maintaining this branch continuously (since mkdocs-material will stop being maintained). 
+- [**MaterialX**](https://github.com/jaywhj/mkdocs-materialx), the next generation of mkdocs-material. Build beautiful sites the way you already know and love. Based on `mkdocs-material-9.7.1` and is named `X`, it provides ongoing maintenance and updates (since mkdocs-material will stop being maintained).  
 Updates have been released that refactor and add a lot of new features, see https://github.com/jaywhj/mkdocs-materialx/releases/
 
 <br />

mkdocs_document_dates-3.7.1/mkdocs_document_dates/__init__.py

@@ -0,0 +1 @@
+"""MkDocs Document Dates Plugin."""

{mkdocs_document_dates-3.6.1 → mkdocs_document_dates-3.7.1}/mkdocs_document_dates/cache_manager.py

@@ -1,32 +1,111 @@
 import logging
+import yaml
+import os
 import subprocess
 from pathlib import Path
-from .utils import read_jsonl_cache, write_jsonl_cache, get_file_creation_time, get_git_first_commit_time
+from logging.handlers import RotatingFileHandler
+from typing import Optional
+from .utils import read_jsonl_cache, write_jsonl_cache, load_file_creation_date, load_git_first_commit_date
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
-logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+_LOGGING_CONFIGURED = False
+
+
+def _default_log_file() -> Path:
+    try:
+        git_root = Path(subprocess.check_output(
+            ['git', 'rev-parse', '--show-toplevel'],
+            env=_clean_git_env(),
+            encoding='utf-8'
+        ).strip())
+        base_dir = git_root
+    except Exception:
+        base_dir = Path.cwd()
+    return base_dir / "mkdocs_document_dates.log"
+
+def configure_file_logging(log_file: Optional[Path] = None, level: int = logging.DEBUG) -> Optional[Path]:
+    global _LOGGING_CONFIGURED
+    if _LOGGING_CONFIGURED:
+        return log_file
+
+    env_log_file = os.getenv("MKDOCS_DOCUMENT_DATES_LOG_FILE")
+    if log_file is None and env_log_file:
+        log_file = Path(env_log_file).expanduser()
+
+    if log_file is None:
+        return None
+
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    handler = RotatingFileHandler(
+        log_file,
+        maxBytes=5 * 1024 * 1024,
+        backupCount=3,
+        encoding="utf-8",
+    )
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter(
+        fmt="%(asctime)s [%(filename)s:%(lineno)d] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    ))
+
+    logger.setLevel(level)
+    logger.addHandler(handler)
+    logger.propagate = False
+    _LOGGING_CONFIGURED = True
+    logger.debug(f"File logging enabled: {log_file}")
+    return log_file
+
+def _env_truthy(name: str) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return False
+    value = value.strip().lower()
+    return value not in ("", "0", "false", "no", "off")
+
+
+def _clean_git_env():
+    env = os.environ.copy()
+
+    for k in [
+        "GIT_DIR",
+        "GIT_WORK_TREE",
+        "GIT_COMMON_DIR",
+        "GIT_INDEX_FILE",
+        "GIT_PREFIX",
+        "GIT_SUPER_PREFIX",
+        "GIT_CEILING_DIRECTORIES",
+    ]:
+        env.pop(k, None)
+
+    env["GIT_OPTIONAL_LOCKS"] = "0"
+
+    return env
 
 def find_mkdocs_projects():
-    projects = []
+    projects = set()
+
     try:
         git_root = Path(subprocess.check_output(
             ['git', 'rev-parse', '--show-toplevel'],
+            env=_clean_git_env(),
             encoding='utf-8'
         ).strip())
 
-        # 遍历 git_root 及子目录, 寻找 mkdocs.yml 文件
-        for config_file in git_root.rglob('mkdocs.y*ml'):
-            if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
-                projects.append(config_file.parent)
+        target_names = {'mkdocs.yml', 'properdocs.yml'}
+        for config_file in git_root.rglob('*.yml'):
+            if config_file.name.lower() in target_names:
+                projects.add(config_file.parent)
 
         if not projects:
-            logger.warning("No MkDocs projects found in the repository")
+            logger.warning("No MkDocs/ProperDocs projects found in the repository")
+
     except subprocess.CalledProcessError as e:
         logger.error(f"Failed to find the Git repository root: {e}")
     except Exception as e:
-        logger.error(f"Unexpected error while searching for MkDocs projects: {e}")
-    
-    return projects
+        logger.error(f"Unexpected error while searching for projects: {e}")
+
+    return list(projects)
 
 def setup_gitattributes(docs_dir: Path):
     try:
@@ -39,7 +118,7 @@ def setup_gitattributes(docs_dir: Path):
                 content += '\n'
             content += f"{union_merge_line}\n"
             gitattributes_path.write_text(content, encoding='utf-8')
-            subprocess.run(["git", "add", str(gitattributes_path)], check=True)
+            subprocess.run(["git", "add", str(gitattributes_path)], cwd=docs_dir, env=_clean_git_env(), check=True)
             logger.info(f"Updated .gitattributes file: {gitattributes_path}")
             return True
     except (IOError, OSError) as e:
@@ -49,15 +128,36 @@ def setup_gitattributes(docs_dir: Path):
     return False
 
 def update_cache():
-    global_updated = False
+    if os.getenv("MKDOCS_DOCUMENT_DATES_LOG_FILE"):
+        configure_file_logging()
+    elif _env_truthy("MKDOCS_DOCUMENT_DATES_DEBUG"):
+        configure_file_logging(_default_log_file())
 
+    global_updated = False
     for project_dir in find_mkdocs_projects():
         try:
             project_updated = False
 
             docs_dir = project_dir / 'docs'
+
+            # 从 mkdocs.yml 中读取 docs_dir 配置覆盖默认值
+            try:
+                mkdocs_yml = project_dir / "properdocs.yml"
+                if not mkdocs_yml.exists():
+                    mkdocs_yml = project_dir / "mkdocs.yml"
+
+                mkdocs_config = yaml.load(
+                    mkdocs_yml.read_text(encoding="utf-8"),
+                    Loader=yaml.BaseLoader,
+                ) or {}
+
+                docs_dir_name = mkdocs_config.get("docs_dir") or "docs"
+                docs_dir = (project_dir / docs_dir_name).resolve(strict=False)
+            except (IOError, OSError, yaml.YAMLError) as e:
+                logger.warning(f"Failed to read docs_dir: {e}")
+
             if not docs_dir.exists():
-                logger.warning(f"Document directory does not exist: {docs_dir}")
+                logger.info(f"Document directory does not exist: {docs_dir}")
                 continue
 
             # 设置.gitattributes文件
@@ -65,7 +165,7 @@ def update_cache():
 
             # 获取docs目录下已跟踪(tracked)的markdown文件
             cmd = ["git", "ls-files", "*.md"]
-            result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, encoding='utf-8')
+            result = subprocess.run(cmd, cwd=docs_dir, env=_clean_git_env(), capture_output=True, encoding='utf-8')
             tracked_files = result.stdout.splitlines() if result.stdout else []
 
             if not tracked_files:
@@ -85,9 +185,9 @@ def update_cache():
 
                     full_path = docs_dir / rel_path
                     if full_path.exists():
-                        created_time = get_file_creation_time(full_path).astimezone()
+                        created_time = load_file_creation_date(full_path).astimezone()
                         if not jsonl_cache_file.exists():
-                            git_time = get_git_first_commit_time(full_path)
+                            git_time = load_git_first_commit_date(full_path)
                             if git_time:
                                 created_time = min(created_time, git_time)
                         jsonl_dates_cache[rel_path] = {
@@ -115,4 +215,4 @@ def update_cache():
 
 
 if __name__ == "__main__":
-    update_cache()
+    update_cache()

{mkdocs_document_dates-3.6.1 → mkdocs_document_dates-3.7.1}/mkdocs_document_dates/hooks/pre-commit

@@ -4,7 +4,7 @@ try:
     from mkdocs_document_dates.cache_manager import update_cache
 except Exception:
     import sys
-    # 正常退出（0 状态码），不影响 git 的后续动作
+    # Normal exit (0 status code), don't affect subsequent git actions
     sys.exit(0)
 
 if __name__ == "__main__":

mkdocs_document_dates-3.7.1/mkdocs_document_dates/hooks_installer.py

@@ -0,0 +1,98 @@
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+DEFAULT_HOOKS_DIRNAME = ".githooks"
+
+
+class HookInstallError(Exception):
+    pass
+
+
+def get_repo_root() -> Path:
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        raise HookInstallError("This command must be run inside a Git repo. Please cd into your project directory and try again.")
+    return Path(result.stdout.strip())
+
+
+def ensure_hooks_dir(repo_root: Path) -> Path:
+    hooks_dir = repo_root / DEFAULT_HOOKS_DIRNAME
+    try:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        os.chmod(hooks_dir, 0o755)
+    except Exception as e:
+        raise HookInstallError(f"Failed to create hooks directory: {hooks_dir} ({e})")
+    return hooks_dir
+
+
+def write_hooks(source_dir: Path, target_dir: Path):
+    if not source_dir.exists():
+        raise HookInstallError(f"Hooks source directory not found: {source_dir}")
+
+    shebang = f"#!{sys.executable}"
+
+    try:
+        for file in source_dir.iterdir():
+            if file.name.startswith(".") or not file.is_file():
+                continue
+
+            content = file.read_text(encoding="utf-8")
+
+            if content.startswith("#!"):
+                os.linesep
+                content = shebang + "\n" + content.split("\n", 1)[1]
+            else:
+                content = shebang + "\n" + content
+
+            target = target_dir / file.name
+            target.write_text(content, encoding="utf-8")
+            os.chmod(target, 0o755)
+
+    except Exception as e:
+        raise HookInstallError(f"Failed to write hook files: {e}")
+
+
+def set_hooks_path(repo_root: Path, hooks_dir: Path):
+    rel_path = hooks_dir.relative_to(repo_root).as_posix()
+
+    # # 配置自定义合并驱动
+    # script_path = hooks_dir / 'json_merge_driver.py'
+    # subprocess.run(['git', 'config', 'merge.custom_json_merge.name', 'Custom JSON merge driver'], check=True)
+    # subprocess.run(['git', 'config', 'merge.custom_json_merge.driver', f'"{sys.executable}" "{script_path}" %O %A %B'], check=True)
+
+    result = subprocess.run(
+        ["git", "config", "core.hooksPath", rel_path],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise HookInstallError(result.stderr.strip() or "Failed to set hooksPath")
+
+
+def install():
+    try:
+        repo_root = get_repo_root()
+        hooks_dir = ensure_hooks_dir(repo_root)
+
+        source_dir = Path(__file__).parent / "hooks"
+
+        write_hooks(source_dir, hooks_dir)
+        set_hooks_path(repo_root, hooks_dir)
+
+        print(f"✔ Hooks installed successfully: {hooks_dir}")
+
+    except HookInstallError as e:
+        print(f"✖ Installation failed: {e}", file=sys.stderr)
+    except Exception as e:
+        print(f"✖ Unexpected error: {e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    install()