No guide has a review date yet, so "Last reviewed" never shows
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 48/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 活跃
- 技术栈
- markdown, python
调研方向
Start with docs/AGENTS.md, CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, and the review-date handling in scripts/prepare-mkdocs.py, scripts/catalog.py, and overrides/main.html. Review each guide under docs/ against its sources before adding a marker; then run python scripts/prepare-mkdocs.py and zensical build --strict -f mkdocs.gen.yml. Done means reviewed guides show dates on the published pages, the rule is consistent, and a check catches broken URL-to-source mapping.
由索引模型根据 Issue 内容生成。
描述
Summary
The review-date feature from #40 works, but no guide has a <!-- reviewed: YYYY-MM-DD --> marker yet. No page shows "Last reviewed", and every build prints 21 warnings, one per guide.
Where
docs/channels/*.md,docs/resources/*.md,docs/ad-templates/TEMPLATES.md(no marker in any guide)scripts/prepare-mkdocs.py:73(prints the warnings)scripts/catalog.py:261(review_status, "has no valid review date")docs/AGENTS.md:32andCONTRIBUTING.md:19(the rule, stated two different ways).github/PULL_REQUEST_TEMPLATE.md:16(new-page checklist)overrides/main.html:14(renders the date)
Details
git grep "reviewed:" -- docs finds only the rule in docs/AGENTS.md. Running python scripts/prepare-mkdocs.py prints:
Warning: channels/SEA.md has no valid review date
Warning: channels/SOCIAL.md has no valid review date
... (21 lines, one per guide)
So mkdocs.gen.yml gets no extra.reviewed_dates, and the template never shows a date.
Two smaller gaps in the same area:
docs/AGENTS.md:32says only a date older than 12 months warns.CONTRIBUTING.md:19and the code also warn on missing, invalid, and future dates.- The PR template's new-page checklist does not mention the marker.
Impact
Readers still cannot tell when a guide was last checked, which was the goal of #40. Because 21 warnings print on every build, contributors learn to ignore them, including the one that matters: a stale date.
Suggested fix
- Review each guide against its sources, then add
<!-- reviewed: YYYY-MM-DD -->on its own line after the H1. Only date a guide that was actually reviewed. The accuracy passes merged on 2026-11-15 and 2026-11-16 (commitsd407010,8ed956c,d46aec8) may already count for the guides they covered. - Make
docs/AGENTS.md:32matchCONTRIBUTING.md:19: missing, invalid, future, and stale dates all warn. - Add the marker to the new-page item in
.github/PULL_REQUEST_TEMPLATE.md. - Add a test for the template's URL-to-source mapping in
overrides/main.html:16(channels/SEA/becomeschannels/SEA.md). Today only the generatedextramap is tested, so a change in page URLs would hide every date without failing a check. One option: afterzensical buildin CI, check thatsite/channels/SEA/index.htmlcontains "Last reviewed".
Acceptance criteria
- Every reviewed guide has a marker, and
python scripts/prepare-mkdocs.pywarns only for guides that still need a review. - "Last reviewed" appears on those guides on the published site.
-
docs/AGENTS.md,CONTRIBUTING.md, and the PR template describe the rule the same way. - A test fails if the template stops finding a page's review date.
Getting started
- Relevant files: the guides under
docs/,docs/AGENTS.md,CONTRIBUTING.md,.github/PULL_REQUEST_TEMPLATE.md,overrides/main.html - Run the checks:
python scripts/prepare-mkdocs.py, thenzensical build --strict -f mkdocs.gen.yml(see CONTRIBUTING.md for the full list) - Related: #40
Filed by repo-audit/full-audit at 2aa0316. Severity: medium. Effort: M. audit-key: documentation|docs/channels|reviewed-date-markers
- 主要语言
- Python
- 星标
- 2
- 派生
- 5
- 平均合并
- 2 天 11 小时
- 30 天内合并 PR
- 7
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
相似的 Issue
-
hive size:simple
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
A new VOLTTRON_HOME starts with agent isolation mode on (string comparison of a boolean default)未关闭
难度 2/5 1-3 小时 新手友好度 68/100
-
难度 2/5 1-3 小时 新手友好度 70/100
painted-porch/marcus#977 ·
维护者通常 1 天内回复
-
llm translation
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
FAIRmat-NFDI/sand#239 ·
维护者通常 1 天内回复