# Link line format

Link lines as - [name](url): description

**In short:** Write every link as - [name](url): description, with a description of at least two characters after the colon.

- Category: Spec Conformance · weight 25 of 100 within the category
- Spec Conformance is worth 10 in every profile (points of 100, by scoring profile)
- Audit ID S4 (as shown on reports) · rubric v2.1

## What it checks

Whether link lines follow the spec form - [name](url): description.

## Why it matters

Agents and parsers rely on the fixed link form to separate the link’s name, target and notes. Irregular lines get parsed wrongly or skipped.

## When it applies

Applies when the file has links. A file with no links at all is Not applicable here.

An audit that doesn’t apply, or that we couldn’t verify, is removed from your score and its weight shared among the Spec Conformance audits that do apply. It is never scored as a zero.

## How it’s scored

The share of the file’s links that carry a description of two or more characters after the colon. A bare - Label: https://… item counts, with the label as its description.

> **Measurement.** Today only lines the parser reads as links are counted. A link line it can’t read (a + bullet, a numbered list, or a separator other than a colon, as in - [Docs](url) - guides) is skipped rather than counted as a failure. Scoring the share of all link-like lines that conform is planned.

## How to fix

1. Write every link as - [name](url): description.
2. Keep the description on the same line, after a colon.
3. Don’t use bare URLs or numbered lists for links.

## Example

```
- [Refunds API](https://acme.com/docs/refunds.md): Create, list and cancel refunds
```

## Frequently asked questions

### Does a link line without “: description” still count?

It counts as a link but not as a described one. The llms.txt format makes the notes optional (`[name](url)`, “then optionally a `:` and notes”), but this check scores the share of your links that carry them, so a file where half the links have a description scores 0.5. A colon followed by nothing, or by a single character, doesn’t count as a description.

Sources: [llms.txt format (v2)](https://llmstxt.org/#format) · [Link line format](https://llmsrank.dev/docs/audits/link-line-format.md)

### Can I use “*” or “+” bullets, numbered lists or nested lists for links?

Use `- ` or `* `: both are read as link lines, and indented (nested) items count too. CommonMark also allows `+` bullets and numbered lists, but our parser doesn’t read those as link lines, so links written that way are skipped rather than scored.

Sources: [CommonMark: list items](https://spec.commonmark.org/0.31.2/#list-items) · [llms.txt format (v2)](https://llmstxt.org/#format)

### Why are some of my links not counted at all?

A line is read as a link only if it is a list item of the form `- [name](url)`, optionally followed by `: notes`. Lines that don’t fit are skipped: a separator other than a colon (`- [Docs](url) - guides`), a URL containing spaces or a `)`, a name containing `]`, or links inside prose paragraphs. A bare `- Label: https://…` list item inside a section is accepted, with the label treated as its description.

Sources: [llms.txt format (v2)](https://llmstxt.org/#format) · [CommonMark: link destination](https://spec.commonmark.org/0.31.2/#link-destination)

### Are relative URLs like /docs/api.md acceptable in link lines?

For this check, yes: any URL in the `(url)` slot counts. The llms.txt format doesn’t forbid relative URLs, but agents often fetch llms.txt out of context, so [URL hygiene](https://llmsrank.dev/docs/audits/url-hygiene.md) rewards absolute `https://` URLs; writing them absolute costs nothing here and helps there.

Sources: [llms.txt format (v2)](https://llmstxt.org/#format) · [URL hygiene](https://llmsrank.dev/docs/audits/url-hygiene.md)

### In our research, how many sites write every link in the spec form with a description?

Of 187 llms.txt files (corpus captured 2026-10-10, rubric v2.1), the check applied to 174; 13 were not applicable because they had no links. 54.0% of the 174 described every link, and the mean score was 0.753, making this the weakest of the spec checks. netlify.com, expedia.com, tavily.com, cloudflare.com and attio.com are examples with fully described link lines.

Sources: [LLMSRank method](https://llmsrank.dev/docs/method.md) · [Link line format](https://llmsrank.dev/docs/audits/link-line-format.md)

See also: [all audits](https://llmsrank.dev/docs/audits.md) · [how scoring works](https://llmsrank.dev/docs/method.md)