---
name: hypertext-links
description: 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](https://github.com/dckc/prism/blob/master/docs/research/STYLE.md).

## 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.

```markdown
- [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:

```markdown
- [Akka Core documentation](https://doc.akka.io/libraries/akka-core/current/)
```