mkdocs-document-dates 3.7.0__tar.gz → 3.7.2__tar.gz

{mkdocs_document_dates-3.7.0/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.0
+Version: 3.7.2
 Summary: A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents
 Author-email: Aaron Wang <aaronwqt@gmail.com>
 License-Expression: MIT
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mkdocs>=1.1.0
+Requires-Dist: mkdocs<=1.6.1,>=1.6
 Dynamic: license-file
 
 # mkdocs-document-dates

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/mkdocs_document_dates/cache_manager.py

@@ -1,10 +1,11 @@
 import logging
+import yaml
 import os
 import subprocess
 from pathlib import Path
 from logging.handlers import RotatingFileHandler
 from typing import Optional
-from .utils import read_jsonl_cache, write_jsonl_cache, get_file_creation_time, get_git_first_commit_time
+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")
 _LOGGING_CONFIGURED = False
@@ -82,7 +83,8 @@ def _clean_git_env():
     return env
 
 def find_mkdocs_projects():
-    projects = []
+    projects = set()
+
     try:
         git_root = Path(subprocess.check_output(
             ['git', 'rev-parse', '--show-toplevel'],
@@ -90,19 +92,20 @@ def find_mkdocs_projects():
             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:
@@ -136,8 +139,25 @@ def update_cache():
             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文件
@@ -165,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] = {

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/mkdocs_document_dates/plugin.py

@@ -2,15 +2,15 @@ import os
 import yaml
 import shutil
 import logging
-from jinja2 import Environment, FileSystemLoader, select_autoescape
+from jinja2 import ChoiceLoader, FileSystemLoader
 from datetime import datetime
 from pathlib import Path
-from mkdocs.plugins import BasePlugin
+from mkdocs.plugins import BasePlugin, event_priority
 from mkdocs.config import config_options
 from mkdocs.structure.pages import Page
 from mkdocs.utils import get_relative_url
 from urllib.parse import urlparse
-from .utils import get_file_creation_time, load_git_metadata, load_git_last_updated_date, read_jsonl_cache, compile_exclude_patterns, is_excluded, get_recently_updated_files
+from .utils import load_file_creation_date, load_git_metadata, load_git_last_updated_dates, read_jsonl_cache, compile_exclude_patterns, is_excluded, get_recently_updated_files
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
 logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
@@ -44,7 +44,7 @@ class DocumentDatesPlugin(BasePlugin):
     def __init__(self):
         super().__init__()
 
-        self.dates_cache = {}
+        self.data_cached = {}
         self.last_updated_dates = {}
         self.authors_yml = {}
         self.recent_docs_html = None
@@ -58,25 +58,25 @@ class DocumentDatesPlugin(BasePlugin):
         authors_file = docs_dir_path / 'authors.yml'
         if not authors_file.exists():
             try:
-                blog_config = config['plugins']['material/blog'].config
+                blog_config = config.plugins.get(f"{config.theme.name}/blog").config
                 authors_file_resolved = blog_config.authors_file.format(blog=blog_config.blog_dir)
                 authors_file = docs_dir_path / authors_file_resolved
             except Exception:
                 pass
         self._load_authors_from_yaml(authors_file)
 
-        # 加载文档元数据
-        self.dates_cache = load_git_metadata(docs_dir_path)
-        # 覆盖 jsonl 缓存
+        # 加载文档 git 元数据(日期 & 作者)
+        self.data_cached = load_git_metadata(docs_dir_path)
+        # 加载 jsonl 缓存数据
         jsonl_cache_file = docs_dir_path / '.dates_cache.jsonl'
         if jsonl_cache_file.exists():
             jsonl_cache = read_jsonl_cache(jsonl_cache_file)
             for filename, new_info in jsonl_cache.items():
-                if filename in self.dates_cache:
-                    self.dates_cache[filename].update(new_info)
+                if filename in self.data_cached:
+                    self.data_cached[filename].update(new_info)
 
-        # 加载文档最近更新时间
-        self.last_updated_dates = load_git_last_updated_date(docs_dir_path)
+        # 加载文档最近更新时间(日期)
+        self.last_updated_dates = load_git_last_updated_dates(docs_dir_path)
 
 
         # 复制配置文件到用户目录（如果不存在）
@@ -151,6 +151,7 @@ class DocumentDatesPlugin(BasePlugin):
 
         return config
 
+    @event_priority(50)
     def on_page_markdown(self, markdown, page: Page, config, files):
         # 获取相对路径，src_uri 总是以"/"分隔
         rel_path = getattr(page.file, 'src_uri', page.file.src_path)
@@ -158,20 +159,21 @@ class DocumentDatesPlugin(BasePlugin):
             rel_path = rel_path.replace(os.sep, '/')
         file_path = page.file.abs_src_path
         
-        # 获取时间信息
-        created = self._find_meta_date(page.meta, self.config['created_field_names'])
-        updated = self._find_meta_date(page.meta, self.config['updated_field_names'])
+        # 优先获取 page.meta 中的数据
+        created = self._load_meta_date(page.meta, self.config['created_field_names'])
+        updated = self._load_meta_date(page.meta, self.config['updated_field_names'])
+        authors = self._load_meta_author(page.meta, page.url)
+
+        # 再获取缓存的数据
         if not created:
-            created = self._get_file_creation_time(file_path, rel_path)
+            created = self._load_created_cached(file_path, rel_path)
         if not updated:
-            updated = self._get_file_modification_time(file_path, rel_path)
-        
-        # 获取作者信息
-        authors = self._get_author_info(rel_path, page, config)
+            updated = self._load_updated_cached(file_path, rel_path)
+        if not authors:
+            authors = self._load_author_cached(rel_path, page, config)
 
-        # 按 MaterialX 的数据规范给 meta 填充数据
-        mx = page.meta.setdefault("_mx", {})
-        mx["document_dates"] = {
+        # 注入数据
+        page.meta["document_dates"] = {
             "dates": {
                 "created": created.isoformat(),
                 "updated": updated.isoformat(),
@@ -189,6 +191,7 @@ class DocumentDatesPlugin(BasePlugin):
         # 将信息写入 markdown
         return self._insert_date_info(markdown, info_html)
 
+    @event_priority(50)
     def on_env(self, env, config, files):
         recently_updated_config = self.config.get('recently-updated')
         if recently_updated_config:
@@ -207,26 +210,23 @@ class DocumentDatesPlugin(BasePlugin):
         recently_updated_docs = get_recently_updated_files(self.last_updated_dates, files, recent_exclude_patterns, limit, self.recent_enable)
 
         # 将数据注入到 config['extra'] 中供全局访问
-        if 'extra' not in config:
-            config['extra'] = {}
-        config['extra']['recently_updated_docs'] = recently_updated_docs
+        if not config.get('extra', {}).get("recently_updated_docs", {}):
+            config['extra']['recently_updated_docs'] = recently_updated_docs
 
         # 渲染HTML
         if self.recent_enable:
-            self.recent_docs_html = self._render_recently_updated_html(recently_updated_docs)
+            # 摘要行数的动态配置
+            summary = recently_updated_config.get("summary_lines", {})
+            summary_lines = {
+                "grid": summary.get("grid", 4),
+                "detail": summary.get("detail", 6),
+            }
 
-        # # 便捷访问日期数据函数
-        # def mdd_access(page, domain):
-        #     return (
-        #         page.meta.get("_mx", {})
-        #         .get("document_dates", {})
-        #         .get(domain, {})
-        #     )
-
-        # env.globals["mdd"] = mdd_access
+            self.recent_docs_html = self._render_recently_updated_html(env, config, recently_updated_docs, summary_lines)
 
         return env
 
+    @event_priority(50)
     def on_post_page(self, output, page, config):
         if self.recent_enable and '\n<!-- RECENTLY_UPDATED_DOCS -->' in output:
             output = output.replace('\n<!-- RECENTLY_UPDATED_DOCS -->', self.recent_docs_html or '')
@@ -257,23 +257,31 @@ class DocumentDatesPlugin(BasePlugin):
             logger.info(f"Error parsing .authors.yml: {e}")
 
 
-    def _render_recently_updated_html(self, recently_updated_data):
-        default_template_path = Path(__file__).parent / 'static' / 'templates' / 'recently_updated_group.html'
-        template_dir = default_template_path.parent
-        template_file = default_template_path.name
+    def _render_recently_updated_html(self, env, config, recently_updated_data, summary_lines):
+        # 设置模板加载器
+        template_path = Path(__file__).parent / 'static' / 'templates'
+        env.loader = ChoiceLoader([
+            FileSystemLoader(str(template_path)),
+            env.loader
+        ])
 
-        # 加载模板
-        env = Environment(
-            loader = FileSystemLoader(str(template_dir)),
-            autoescape = select_autoescape(["html", "xml"])
+        # 用于模板的安全阀
+        try:
+            env.get_template("partials/language.html")
+            env.globals["HAS_LANGUAGE_TEMPLATE"] = True
+        except Exception:
+            env.globals["HAS_LANGUAGE_TEMPLATE"] = False
+
+        # 获取模板并渲染
+        template = env.get_template("recently_updated_group.html")
+        return template.render(
+            recent_docs=recently_updated_data,
+            summary_lines=summary_lines,
+            config=config
         )
-        template = env.get_template(template_file)
 
-        # 渲染模板
-        return template.render(recent_docs=recently_updated_data)
 
-
-    def _find_meta_date(self, meta, field_names):
+    def _load_meta_date(self, meta, field_names):
         for field in field_names:
             if field in meta:
                 try:
@@ -284,14 +292,14 @@ class DocumentDatesPlugin(BasePlugin):
                     continue
         return None
 
-    def _get_file_creation_time(self, file_path, rel_path):
+    def _load_created_cached(self, file_path, rel_path):
         # 优先从缓存中读取
-        if rel_path in self.dates_cache:
-            return datetime.fromisoformat(self.dates_cache[rel_path]['created'])
+        if rel_path in self.data_cached:
+            return datetime.fromisoformat(self.data_cached[rel_path]['created'])
         # 从文件系统获取
-        return get_file_creation_time(file_path).astimezone()
+        return load_file_creation_date(file_path).astimezone()
 
-    def _get_file_modification_time(self, file_path, rel_path):
+    def _load_updated_cached(self, file_path, rel_path):
         # 优先从缓存中读取
         if rel_path in self.last_updated_dates:
             return datetime.fromtimestamp(self.last_updated_dates[rel_path]).astimezone()
@@ -300,34 +308,29 @@ class DocumentDatesPlugin(BasePlugin):
         return datetime.fromtimestamp(stat.st_mtime).astimezone()
 
 
-    def _get_author_info(self, rel_path, page, config):
-        # 1. meta author
-        authors = self._process_meta_author(page.meta, page.url)
-        if authors:
-            return authors
-
-        # 2. git author
-        if rel_path in self.dates_cache:
-            authors_list = self.dates_cache[rel_path].get('authors')
+    def _load_author_cached(self, rel_path, page, config):
+        # 1. git author
+        if rel_path in self.data_cached:
+            authors_list = self.data_cached[rel_path].get('authors')
             if authors_list:
                 authors = []
                 for data in authors_list:
                     full_author = self.authors_yml.get(data['name'])
                     if full_author:
-                        authors.append(self._get_repaired_author(full_author, page.url))
+                        authors.append(self._repair_author(full_author, page.url))
                     else:
                         authors.append(Author(**data))
                 return authors
 
-        # 3. site_author 或 PC username
+        # 2. site_author 或 PC username
         name = config.get('site_author') or Path.home().name
         full_author = self.authors_yml.get(name)
         if full_author:
-            return [self._get_repaired_author(full_author, page.url)]
+            return [self._repair_author(full_author, page.url)]
         else:
             return [Author(name=name)]
 
-    def _process_meta_author(self, meta, page_url):
+    def _load_meta_author(self, meta, page_url):
         try:
             # 匹配 authors 数组
             author_objs = []
@@ -335,7 +338,7 @@ class DocumentDatesPlugin(BasePlugin):
             for key in authors_data or []:
                 full_author = self.authors_yml.get(key)
                 if full_author:
-                    author_objs.append(self._get_repaired_author(full_author, page_url))
+                    author_objs.append(self._repair_author(full_author, page_url))
                 else:
                     author_objs.append(Author(name=str(key)))
             if author_objs:
@@ -349,14 +352,14 @@ class DocumentDatesPlugin(BasePlugin):
                     name = email.partition('@')[0]
                 full_author = self.authors_yml.get(name)
                 if full_author:
-                    return [self._get_repaired_author(full_author, page_url)]
+                    return [self._repair_author(full_author, page_url)]
                 else:
                     return [Author(name=name, email=email)]
         except Exception as e:
             logger.warning(f"Error processing author meta: {e}")
         return None
 
-    def _get_repaired_author(self, author: Author, page_url: str) -> Author:
+    def _repair_author(self, author: Author, page_url: str) -> Author:
         try:
             if not author.avatar:
                 return author
@@ -370,7 +373,7 @@ class DocumentDatesPlugin(BasePlugin):
             return author
 
 
-    def _get_formatted_date(self, date: datetime):
+    def _formatting_date(self, date: datetime):
         if self.config['type'] == 'timeago':
             return ""
         elif self.config['type'] == 'datetime':
@@ -399,7 +402,7 @@ class DocumentDatesPlugin(BasePlugin):
                 return (
                     f"<span class='dd-item' data-tippy-content data-tippy-raw='{formatted}'>"
                     f"<span class='material-icons' data-icon='{icon}'></span>"
-                    f"<time datetime='{time_obj.isoformat()}'>{self._get_formatted_date(time_obj)}</time>"
+                    f"<time datetime='{time_obj.isoformat()}'>{self._formatting_date(time_obj)}</time>"
                     f"</span>"
                 )
 

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/mkdocs_document_dates/static/templates/recently_updated_group.html

@@ -1,4 +1,5 @@
 <style>
+/* --- 视图选择器 --- */
 .article-layout-switcher {
     display: flex;
     justify-content: flex-end;
@@ -32,7 +33,7 @@
     font-size: 20px;
 }
 
-/* --- 网格模式 (默认) --- */
+/* --- 三种视图 --- */
 .article-grid {
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
@@ -40,15 +41,18 @@
     margin: 20px 0;
     /* transition: all 0.2s ease; */
 }
-
-/* --- 详情模式 (is-detail) --- */
 .article-grid.is-detail {
-    grid-template-columns: 1fr;
+    grid-template-columns: minmax(0, 1fr);
     margin-left: auto;
     margin-right: auto;
 }
-
-/* --- 列表模式 (is-list) --- */
+.article-grid.is-detail .card-summary {
+    --summary-lines: var(--summary-lines-detail);
+}
+.article-grid.is-detail .card-cover {
+    width: 135px;
+    height: 90px;
+}
 .article-grid.is-list {
     margin-left: auto;
     margin-right: auto;
@@ -61,6 +65,9 @@
 .article-grid.is-list .card-body {
     display: none;
 }
+.article-grid.is-list .card-footer {
+    display: none;
+}
 .article-grid.is-list .article-card {
     border: none;
     border-radius: 0;
@@ -79,7 +86,7 @@
     margin-right: 0;
 }
 
-
+/* --- Card --- */
 .article-card {
     border: 1px solid rgba(142, 142, 142, 0.2);
     border-radius: 8px;
@@ -88,13 +95,14 @@
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
+    height:100%;
 }
 
-/* --- 第一行：标题与时间 --- */
+/* --- Header --- */
 .card-header {
     display: flex;
     justify-content: space-between;
-    align-items: center;
+    align-items: baseline;
     text-decoration: none;
 }
 .card-title {
@@ -104,10 +112,12 @@
     margin-right: 12px;
 }
 .card-date {
-    font-size: 0.84em;
-    color: rgba(100, 100, 100, 0.4);
+    font-size: 0.8em;
+    color: rgba(100, 100, 100, 0.6);
     white-space: nowrap;
     margin-right: 10px;
+    /* 补偿 baseline 布局时字体度量的误差 */
+    transform: translateY(-1px);
 }
 .card-header:hover,
 .card-header:focus {
@@ -118,37 +128,44 @@
     text-decoration: underline;
 }
 
-/* --- 第二行：摘要与封面图 --- */
+/* --- Body --- */
 .card-body {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
     margin-top: 12px;
 }
 .card-summary {
-    flex: 1;
-    color: rgba(142, 142, 142, 1);
+    --summary-lines: var(--summary-lines-grid, 4);
+    --lh: 1.8em;
+
+    line-height: var(--lh);
+    max-height: calc(var(--summary-lines) * var(--lh));
+
+    overflow: clip;
+    pointer-events: none;
+
+    color: var(--md-default-fg-color--light, rgb(121, 121, 121));
     font-size: 0.7rem;
-    line-height: 1.6;
     letter-spacing: 0.02rem;
     word-break: break-all;
-    
-    /* 3 行文字截断，超出显示省略号 */
-    display: -webkit-box;
-    -webkit-box-orient: vertical;
-    -webkit-line-clamp: 3;
-    overflow: hidden;
+
+    -webkit-mask-image: linear-gradient(
+        to bottom,
+        black calc(100% - var(--lh)*1.2),
+        transparent 100%
+    );
+    mask-image: linear-gradient(
+        to bottom,
+        black calc(100% - var(--lh)*1.2),
+        transparent 100%
+    );
 }
 .card-cover {
-    width: 120px;
-    height: 80px;
-    border-radius: 8px;
-    flex-shrink: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
+    float: right;
+    width: 105px;
+    height: 70px;
+    margin: 2px 0 0 10px;
+    border-radius: 4px;
     overflow: hidden;
-    margin-left: 10px;
+
     transition: filter 0.3s ease;
 
     /* Safari 圆角闪烁修复 */
@@ -181,6 +198,55 @@
 .card-cover:hover img {
     transform: scale(1.1) translateX(4px) translateZ(0);
 }
+.card-body::after {
+    content: "";
+    display: block;
+    clear: both;
+}
+
+/* --- Footer --- */
+.card-footer {
+    display: flex;
+    align-items: center;
+    margin-top: auto;
+    padding-top: 12px;
+    margin-bottom: -4px;
+    font-size: 0.75rem;
+    line-height: 1.6;
+}
+.card-footer .read-time {
+    display: inline-flex;
+    align-items: center;
+    font-size: 0.65rem;
+    color: rgba(100, 100, 100, 0.6);
+    white-space: nowrap;
+    margin-right: 12px;
+}
+.card-footer .read-time-icon {
+    font-size: 0.8rem;
+    opacity: .7;
+    margin-right: 4px;
+}
+
+.md-typeset .md-tags:not([hidden]) {
+    margin: 0 0 0 auto;
+    display: flex;
+    align-items: center;
+    min-width: 0;
+    gap: 0;
+    flex-wrap: nowrap;
+    overflow: hidden;
+}
+.md-typeset .md-tag {
+    font-weight: 400;
+    flex-shrink: 0;
+    gap: 0;
+    color: var(--md-default-fg-color--light);
+    margin-right: 6px;
+}
+.md-typeset .md-tag-icon::before {
+    margin-right: 4px;
+}
 </style>
 
 <div class="article-layout-switcher">
@@ -189,21 +255,47 @@
     <button class="layout-grid-btn"><span class="material-icons">view_module</span></button>
 </div>
 
-<div class="article-grid">
-    {%- for mtime, rel_path, title, url, cover, summary in recent_docs %}
+<div class="article-grid"
+     style="
+        --summary-lines-grid: {{ summary_lines.grid }};
+        --summary-lines-detail: {{ summary_lines.detail }};
+     ">
+    {%- for mtime, rel_path, title, url, cover, summary, readtime, tags in recent_docs %}
     <div class="article-card">
         <a class="card-header" href="{{ url }}" target="_blank">
             <div class="card-title">{{ title }}</div>
             <time class="dd-timeago card-date" datetime="{{ mtime }}">{{ mtime[:10] }}</time>
         </a>
         <div class="card-body">
-            <div class="card-summary">{{ summary }}</div>
             {%- if cover %}
             <div class="card-cover">
                 <img src="{{ cover }}" alt="{{ title }}">
             </div>
             {%- endif %}
+            <div class="card-summary">{{ summary }}</div>
+        </div>
+
+        {%- if tags or readtime > 0 %}
+        <div class="card-footer">
+            {%- if readtime > 0 %}
+            <span class="read-time"><span class="read-time-icon material-icons">hourglass_top</span>
+                {%- if HAS_LANGUAGE_TEMPLATE -%}
+                    {%- import "partials/language.html" as lang with context -%}
+                    {{ lang.t("readtime.other") | replace("#", readtime) }}
+                {%- else -%}
+                    {{ readtime }} min read
+                {%- endif -%}
+            </span>
+            {%- endif %}
+            {%- if tags %}
+            <div class="md-tags">
+                {%- for tag in tags %}
+                <span class="md-tag md-tag-icon">{{- tag -}}</span>
+                {%- endfor %}
+            </div>
+            {%- endif %}
         </div>
+        {%- endif %}
     </div>
     {%- endfor %}
 </div>

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/mkdocs_document_dates/utils.py

@@ -6,6 +6,7 @@ import logging
 import subprocess
 import fnmatch
 import re
+import math
 from pathlib import Path
 from datetime import datetime
 from collections import defaultdict
@@ -34,7 +35,7 @@ def is_excluded(path, patterns):
                 return True
     return False
 
-def get_file_creation_time(file_path):
+def load_file_creation_date(file_path):
     try:
         stat = os.stat(file_path)
         system = platform.system().lower()
@@ -48,10 +49,10 @@ def get_file_creation_time(file_path):
         else:  # Linux, 没有创建时间，使用修改时间
             return datetime.fromtimestamp(stat.st_mtime)
     except (OSError, ValueError) as e:
-        logger.error(f"Failed to get file creation time for {file_path}: {e}")
+        logger.error(f"Failed to load file creation date for {file_path}: {e}")
         return datetime.now()
 
-def get_git_first_commit_time(file_path):
+def load_git_first_commit_date(file_path):
     try:
         # git log --reverse --format="%aI" -- {file_path} | head -n 1
         cmd_list = ['git', 'log', '--reverse', '--format=%aI', '--', file_path]
@@ -60,7 +61,7 @@ def get_git_first_commit_time(file_path):
             first_line = process.stdout.partition('\n')[0].strip()
             return datetime.fromisoformat(first_line)
     except Exception as e:
-        logger.info(f"Error getting git first commit time for {file_path}: {e}")
+        logger.info(f"Error load git first commit date for {file_path}: {e}")
     return None
 
 def load_git_metadata(docs_dir_path: Path):
@@ -107,7 +108,7 @@ def load_git_metadata(docs_dir_path: Path):
         logger.info(f"Error getting git info in {docs_dir_path}: {e}")
     return dates_cache
 
-def load_git_last_updated_date(docs_dir_path: Path):
+def load_git_last_updated_dates(docs_dir_path: Path):
     doc_mtime_map = {}
     try:
         git_root = Path(subprocess.check_output(
@@ -160,21 +161,26 @@ def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list:
             # 优先从现有数据获取 mtime，如果不存在则 fallback 到文件系统 mtime
             mtime = existing_dates.get(rel_path, os.path.getmtime(file.abs_src_path))
 
-            # 获取文档标题和 URL
+            # 获取文档其它信息
             title = file.page.title if file.page and file.page.title else file.name
             url = file.page.url if file.page and file.page.url else file.url
+            tags = file.page.meta.get("tags") or []
 
             cover = ''
             summary = ''
+            readtime = 0
             # authors = []
             if file.page:
                 cover = file.page.meta.get('cover', '')
-                # authors = file.page.meta._mx.document_dates.authors
+                # authors = file.page.meta.document_dates.authors
                 if file.page.file:
-                    summary = extract_summary(file.page.file.content_string)
+                    summary, readtime = analyze_markdown(file.page.file.content_string)
 
-            # 存储信息
-            files_meta.append((mtime, rel_path, title, url, cover, summary))
+            meta_readtime = int(file.page.meta.get('readtime') or 0)
+            readtime = meta_readtime if meta_readtime > 0 else readtime
+
+            # 存储信息（更新时间、路径、标题、URL、封面、摘要、阅读时间、标签）
+            files_meta.append((mtime, rel_path, title, url, cover, summary, readtime, tags))
             # existing_map[rel_path] = mtime
 
         # 构建最近更新列表
@@ -229,50 +235,108 @@ def write_jsonl_cache(jsonl_file: Path, dates_cache, tracked_files):
     return False
 
 
+# ==================================================
+# High-performance Readtime & Summary parser design:
+# 
+# - O(n) single-pass parser (scan once)
+# - No AST construction
+# - Finite state machine
+# - Block detection: frontmatter / fence / HTML / math / comment
+# - Inline and block parsing separated
+# - Summary and read-time computed in the same pass
+#
+# Language support:
+# 
+# - CJK languages: Chinese, Japanese, Korean
+# - Space-delimited languages: English, Spanish, French, German, Portuguese, Russian ...
+# - Supports mixed-language content (e.g. English + CJK)
+# ==================================================
+
+# ===== Extract Readtime =====
+DEFAULT_WPM = 240
+
+# Match Unicode "words" for space-delimited languages (English, Spanish, French, German, Russian, etc.)
+# CJK characters also match \w in Python, so they are removed before applying this regex to avoid double counting
+WORD_RE = re.compile(r"\w+", re.UNICODE)
+# WORD_RE = re.compile(r"[A-Za-z0-9_']+")
+
+# Match common CJK characters (Chinese, Japanese, Korean).
+# These languages do not use spaces between words, so characters are counted separately and weighted differently in Readtime
+# Ranges:
+#   \u4E00–\u9FFF  : Chinese (both Simplified and Traditional)
+#   \u3040–\u30FF  : Japanese Hiragana and Katakana
+#   \uAC00–\uD7AF  : Korean Hangul syllables
+CJK_RE = re.compile(r"[\u4E00-\u9FFF\u3040-\u30FF\uAC00-\uD7AF]")
+
+
 # ===== Extract Summary =====
 # 
 # -------- block skip --------
-# Fence
 FENCE_RE = re.compile(r"^\s*([`~]{3,})")
 
-# HTML comment
-HTML_COMMENT_START = re.compile(r'<!--', re.I)
-HTML_COMMENT_END   = re.compile(r'-->', re.I)
-
 # HTML
-HTML_TAG_OPEN = re.compile(r'<\s*([a-zA-Z][\w\-]*)\b', re.I)
-HTML_TAG_CLOSE_TEMPLATE = r"</\s*{}\s*>"
+HTML_TAG_OPEN = re.compile(r"<\s*([a-zA-Z][\w\-]*)\b", re.I)
+HTML_VALID_TAGS = {
+    "html","head","title","base","link","meta","style",
+    "body","article","section","nav","aside","header","footer","main",
+    "h1","h2","h3","h4","h5","h6",
+    "p","hr","pre","blockquote","ol","ul","li","dl","dt","dd",
+    "figure","figcaption","div",
+    "a","em","strong","small","s","cite","q","dfn","abbr","data","time",
+    "code","var","samp","kbd","sub","sup","i","b","u","mark",
+    "ruby","rt","rp","bdi","bdo","span","br","wbr",
+    "ins","del",
+    "picture","source","img","iframe","embed","object","param",
+    "video","audio","track","map","area",
+    "svg","math",
+    "table","caption","colgroup","col","tbody","thead","tfoot",
+    "tr","td","th",
+    "form","label","input","button","select","datalist","optgroup",
+    "option","textarea","output","progress","meter",
+    "fieldset","legend",
+    "details","summary","dialog",
+    "script","noscript","template","slot","canvas",
+    "font","center","big","tt","strike","basefont","dir","applet"
+}
 HTML_VOID_TAGS = {
     "area", "base", "br", "col", "embed", "hr",
     "img", "input", "link", "meta", "param",
     "source", "track", "wbr"
 }
-HTML_VOID_CLOSE_RE = re.compile(r">", re.I)
 
 # -------- inline skip --------
-H1_TITLE = re.compile(r'^\s*# .+$', re.MULTILINE)
-SINGLE_LINE_HTML_NOISE = re.compile(r'^</?[a-z][\w-]*[^>]*>$', re.I)
-TABLE_ROW_RE = re.compile(r"^\s*\|.*\|\s*$")
-INLINE_SKIP_RE = re.compile(
-    r"""
-    ^\s*> |                 # quote
-    ^\s*(?:!!!|\?\?\?) |    # admonition
-    ^\s*=== |               # tab
-    ^\s*\[.+?\]:            # reference link, including footnote
-    """,
-    re.X,
-)
+# TABLE_ROW_RE = re.compile(r"^\s*\|.*\|\s*$")
+REF_LINK_RE = re.compile(r"^\s*\[.+?\]:")
+H1_TITLE = re.compile(r"^\s*# .+$", re.MULTILINE)
+SINGLE_LINE_HTML_NOISE = re.compile(r"^</?[a-z][\w-]*[^>]*>", re.I)
+def inline_skip(line: str):
+    s = line.lstrip()
+    if s.startswith(">"):
+        return True
+    if s.startswith("!!!") or s.startswith("???"):
+        return True
+    if s.startswith("==="):
+        return True
+    return False
 
 # -------- inline replace --------
-IMAGE_RE = re.compile(r'!\[[^\]]*\]\([^)]+\)')
-LINK_RE = re.compile(r'\[([^\]]+)\]\([^)]+\)')
+IMAGE_RE = re.compile(r"!\[[^\]]*\]\([^)]+\)")
+LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]+\)")
 BRACE_RE = re.compile(r"\{[^}]*\}")
-MD_SYNTAX_RE = re.compile(r'[`*_>#]+')
+MD_SYNTAX_RE = re.compile(r"[`*_>#]+")
 
-def clean_markdown(md: str) -> list:
 
-    lines = md.splitlines()
-    result = []
+def analyze_markdown(md: str) -> list:
+    # ---------- for Readtime ----------
+    words = 0
+    cjk = 0
+    images = 0
+    table_rows = 0
+    code_rows = 0
+    math_blocks = 0
+
+    # ---------- for Summary ----------
+    summary_lines = []
 
     state = "NORMAL"
     fence = ""
@@ -281,7 +345,7 @@ def clean_markdown(md: str) -> list:
     h1_parsed = False
     math_delim = ""
 
-    for line in lines:
+    for line in md.splitlines():
         stripped = line.strip()
         if not stripped:
             continue
@@ -295,10 +359,12 @@ def clean_markdown(md: str) -> list:
                     state = "NORMAL"
                     frontmatter_parsed = True
                 continue
-            
+
             if state == "NORMAL" and stripped in ("---", "+++"):
                 state = "FRONTMATTER"
                 continue
+            else:
+                frontmatter_parsed = True
 
         # ==================================================
         # 2. Fence Block
@@ -306,6 +372,8 @@ def clean_markdown(md: str) -> list:
         if state == "FENCE":
             if stripped.startswith(fence):
                 state = "NORMAL"
+            else:
+                code_rows += 1
             continue
  
         if state == "NORMAL":
@@ -319,49 +387,51 @@ def clean_markdown(md: str) -> list:
         # 3. HTML Comment
         # ==================================================
         if state == "COMMENT":
-            if HTML_COMMENT_END.search(stripped):
+            if stripped.endswith("-->"):
                 state = "NORMAL"
             continue
 
-        if state == "NORMAL" and HTML_COMMENT_START.search(stripped):
+        if state == "NORMAL" and stripped.startswith("<!--"):
             state = "COMMENT"
-            if HTML_COMMENT_END.search(stripped):
+            if stripped.endswith("-->"):
                 state = "NORMAL"
             continue
 
         # ==================================================
         # 4. HTML Block
         # ==================================================
+        # Counting img tags in html
+        lower = stripped.lower()
+        if "<img " in lower:
+            images += lower.count("<img ")
+
         if state == "HTML_BLOCK":
-            if html_close_re and html_close_re.search(stripped):
+            if html_close_re and html_close_re in lower:
                 state = "NORMAL"
                 html_close_re = None
             continue
 
         if state == "NORMAL":
-            m = HTML_TAG_OPEN.match(stripped)
-            if m:
-                tag = m.group(1).lower()
-                is_void = tag in HTML_VOID_TAGS
-
-                # void tag：单行且以 > 结尾，视为直接结束，忽略该行
-                if stripped.endswith('>') and is_void:
+            if stripped.startswith("<"):
+                m = HTML_TAG_OPEN.match(stripped)
+                if m:
+                    tag = m.group(1).lower()
+
+                    # Normal tags: required </tag>
+                    if tag in HTML_VALID_TAGS and tag not in HTML_VOID_TAGS:
+                        html_close_re = f"</{tag}>"
+                        if html_close_re in lower:
+                            continue
+                    else:
+                        # VOID or Non-standard tags: as long as they end in >
+                        html_close_re = ">"
+                        if stripped.endswith(html_close_re):
+                            continue
+
+                    # Going here means that the multiline HTML block
+                    state = "HTML_BLOCK"
                     continue
 
-                # 非 void tag：进入 HTML_BLOCK
-                state = "HTML_BLOCK"
-                if is_void:
-                    html_close_re = HTML_VOID_CLOSE_RE
-                else:
-                    html_close_re = re.compile(HTML_TAG_CLOSE_TEMPLATE.format(re.escape(tag)), re.I)
-
-                # same-line close: <div>...</div>
-                if html_close_re.search(stripped):
-                    state = "NORMAL"
-                    html_close_re = None
-
-                continue
-
         # ==================================================
         # 5. Math Block
         # ==================================================
@@ -373,29 +443,36 @@ def clean_markdown(md: str) -> list:
         if state == "NORMAL" and stripped in ("$$", "\\["):
             math_delim = "$$" if stripped == "$$" else "\\]"
             state = "MATH"
+            math_blocks += 1
             continue
 
         # ==================================================
         # 6. Inline Skip
         # ==================================================
         if state == "NORMAL":
-            if TABLE_ROW_RE.match(stripped):
+            if stripped.startswith("|") and stripped.endswith("|"):
+            # if TABLE_ROW_RE.match(stripped):
+                table_rows += 1
                 continue
-            if INLINE_SKIP_RE.match(stripped):
+            if inline_skip(stripped):
                 continue
-            # 单行 HTML 噪音兜底
-            if SINGLE_LINE_HTML_NOISE.match(stripped):
+            if REF_LINK_RE.match(stripped):
                 continue
             if not h1_parsed:
                 if H1_TITLE.match(stripped):
                     h1_parsed = True
                     continue
-            if stripped.startswith(('---', '***')):
+            if stripped.startswith(("---", "***", "___")):
+                continue
+            if SINGLE_LINE_HTML_NOISE.match(stripped):
                 continue
 
         # ==================================================
         # 7. Inline Replace
         # ==================================================
+        if "![" in stripped:
+            images += len(IMAGE_RE.findall(stripped))
+
         text = stripped
         text = IMAGE_RE.sub("", text)
         text = LINK_RE.sub(r"\1", text)
@@ -403,19 +480,27 @@ def clean_markdown(md: str) -> list:
 
         text = text.strip()
         if text:
-            result.append(text)
-
-            # 提前熔断
-            if len(result) >= 10:
-                break
-
-        # 锁定 Frontmatter 状态，防止后续 --- 干扰
-        frontmatter_parsed = True
-
-    return result
-    # return "\n".join(result)
-
-def extract_summary(markdown_text: str) -> str:
-    md_list = clean_markdown(markdown_text)
-    text = "  ".join(md_list)
-    return MD_SYNTAX_RE.sub('', text).strip()
+            cjk += len(CJK_RE.findall(text))
+            # CJK characters also match \w, so remove them before applying \w to avoid double counting!
+            text_no_cjk = CJK_RE.sub(" ", text)
+            words += len(WORD_RE.findall(text_no_cjk))
+
+            # Make the summary break early
+            if len(summary_lines) < 10:
+                summary_lines.append(text)
+
+    # ===============================
+    # compute read time
+    # ===============================
+    units = words + cjk / 2
+    seconds = math.ceil(units / DEFAULT_WPM * 60)
+
+    seconds += table_rows * 2
+    seconds += code_rows
+    seconds += math_blocks * 4
+    seconds += images * 2
+
+    summary = MD_SYNTAX_RE.sub("", "  ".join(summary_lines)).strip()
+    minutes = max(1, math.ceil(seconds / 60))
+
+    return summary, minutes

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2/mkdocs_document_dates.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.0
+Version: 3.7.2
 Summary: A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents
 Author-email: Aaron Wang <aaronwqt@gmail.com>
 License-Expression: MIT
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mkdocs>=1.1.0
+Requires-Dist: mkdocs<=1.6.1,>=1.6
 Dynamic: license-file
 
 # mkdocs-document-dates

mkdocs_document_dates-3.7.2/mkdocs_document_dates.egg-info/requires.txt

@@ -0,0 +1 @@
+mkdocs<=1.6.1,>=1.6

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/pyproject.toml

@@ -4,13 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-document-dates"
-version = "3.7.0"
+version = "3.7.2"
 description = "A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.7"
 license = "MIT"
 authors = [{ name = "Aaron Wang", email = "aaronwqt@gmail.com" }]
-dependencies = ["mkdocs>=1.1.0"]
+dependencies = [
+  "mkdocs>=1.6,<=1.6.1"
+  # "properdocs>=1.6.5"
+]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",

{mkdocs_document_dates-3.7.0 → mkdocs_document_dates-3.7.2}/setup.py

@@ -4,7 +4,7 @@ from setuptools import find_packages, setup
 def legacy_setup():
     setup(
         name="mkdocs-document-dates",
-        version="3.7.0",
+        version="3.7.2",
         author="Aaron Wang",
         author_email="aaronwqt@gmail.com",
         license="MIT",

mkdocs_document_dates-3.7.0/mkdocs_document_dates.egg-info/requires.txt

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