docs: specify docs directory and path-case rules
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
d579e38ba5
commit
9eec1d1016
1 file changed
+2
-2
+2
-2
@@ -7,7 +7,7 @@ The ADR body uses the [MADR 4](https://adr.github.io/madr/) layout; `Consequence
|
||||
## 1. Files and directories
|
||||
|
||||
- ADRs live in `docs/adr/`, plans in `docs/plans/`, relative to the repository root. Both are flat: subdirectories are not scanned and are errors.
|
||||
- A missing directory is treated as empty.
|
||||
- A missing directory is treated as empty. `docs/adr` and `docs/plans` MUST be real directories: a symlink in their place is an error.
|
||||
- Entries whose name starts with `.` (such as `.DS_Store` or editor swap files) are ignored. `README.md` in either directory is skipped. Every other entry MUST be a regular file whose name matches section 2 and ends in `.md`. Any other file, directory or name is an error. There are no other exceptions: no templates and no companion files; every `.md` file is a record.
|
||||
- Files are UTF-8 without a byte order mark. LF and CRLF line endings are both accepted.
|
||||
|
||||
@@ -146,7 +146,7 @@ Repo-root path:
|
||||
- Starts with a single `/` and is relative to the repository root, for example `/docs/adr/20261023T204512345Z-use-example-queue.md`. A leading `//` (protocol-relative `//host/...`) is rejected.
|
||||
- Repo-root links render correctly on Git forges (GitHub, Gitea) but not in every Markdown viewer.
|
||||
- The destination is percent-decoded before the existence check (`%20` is a space). A `?query` is an error.
|
||||
- The target MUST exist as a regular file inside the repository. Symlinks that resolve outside the repository are rejected.
|
||||
- The target MUST exist as a regular file inside the repository, and the path MUST match the target's case exactly, component by component, even on case-insensitive filesystems. Symlinks that resolve outside the repository are rejected.
|
||||
- In body links only, a `#fragment` suffix is allowed; the fragment is not verified. In frontmatter, a fragment is an error.
|
||||
- Rejected: relative paths (`foo.md`, `./foo.md`), any `..` segment and backslashes. Other non-existent targets, including machine paths such as `/Users/...` or `/home/...`, fail the existence rule; `file:` URLs fail the scheme rule.
|
||||
|
||||
|
||||
Reference in new issue
Block a user