| name | sync-docs |
| description | Use when auditing and fixing markdown documentation — broken links, outdated references, external URLs, and convention compliance. |
sync-docs
Synchronise all markdown documents and artifacts.
Check and fix documentation to ensure consistency with the current codebase structure.
Principles
- Every document reflects reality — Outdated docs are worse than no docs. If the code changes, the docs must change.
- Links must resolve — Every internal
.md link should point to an existing file. Broken links erode trust.
- Crate references match the workspace — Referenced crate names, module paths, and file paths must match the current workspace structure.
- External URLs should be valid — Links to GitHub repositories, issue trackers, and external resources should point to the correct locations.
Audit Dimensions
Internal Links
Scan all .md files in docs/ for links to other .md files. For each link:
- Resolve the path relative to the document's directory.
- Verify the target file exists.
- If the target has moved, update the link to the new path.
- If the target no longer exists, update the link to the nearest equivalent or remove it.
Crate and Module References
- Review all mentions of crate names, module names, and file paths.
- Verify they match the current workspace structure.
- Update references to crates that have been renamed, removed, or restructured.
- Pay special attention to module hierarchy descriptions, which drift as code is refactored.
External URLs
- Check URLs pointing to GitHub repositories. The canonical URL is
https://github.com/reasvyn/rvlibs.
- Check URLs to crates.io, docs.rs, and other external resources.
- Update any that return 404 or point to a moved location.
Convention Compliance
- All documentation is written in English.
- Code examples are syntactically valid Rust (or marked as
ignore if they are not).
- File references use forward slashes, even on Windows.
- Cross-references use backtick syntax in doc comments and relative markdown links in
.md files.
When to Sync Docs
- After crate additions, removals, or renames
- After module hierarchy changes
- After file path changes in
docs/
- After external URL changes (repository moves, service changes)
- Periodically, as part of release preparation
Output Requirements
- A summary of what was fixed: broken links, outdated references, renamed paths
- Confirmation that all docs are consistent with the current codebase structure
