1.6 KiB
1.6 KiB
name, description
| name | description |
|---|---|
| hypertext-links | Writing style for links in markdown docs — use when writing or reviewing any doc with URLs to external pages, repo files, or intra-repo documents; enforces descriptive link text over bare/generic links. |
Hypertext Links
Markdown link style, from the Prism research doc style guide.
No bare URLs
Every URL is wrapped: [descriptive text](url). A raw URL pasted inline
fails review, even in comments and commit messages.
Link text carries information scent
Anchor text must be descriptive, frontloaded (first two words do the scanning work — users read those first), and context-free (intelligible without the surrounding sentence). Generic labels fail: "here", "read more", "click here", or a raw filename where a concept was meant.
- Yes:
[the Passable datatype design](01-passable-datatype.md) - No:
[01-passable-datatype.md](01-passable-datatype.md) - No:
[read more](...)
Citations: metadata outside the link
Date/author/version goes outside the link text; reference lists sort newest first; the title (in quotes) is the primary link for papers.
- [Introducing Prism](https://example.com/prism) — example.com, 2025
- 2019 — Clebsch et al. ["Protocols for Concurrent Reference Counting"](https://doi.org/10.4230/LIPIcs.ECOOP.2019.25). _OOPSLA 2019._
Metadata headers are bullet lists
Not **Label**: [link](...) — just bullets:
- [Akka Core documentation](https://doc.akka.io/libraries/akka-core/current/)