# MD052 - Fix broken reference links and images

## What this rule does

Checks that all reference-style links and images point to definitions that actually exist in your document.

## Why this matters

- **Prevents broken links**: Readers can't follow links that don't have destinations
- **Avoids confusion**: Missing references leave readers wondering where links should go
- **Maintains trust**: Broken links make your documentation appear unmaintained
- **Ensures completeness**: All referenced content is properly defined

## Examples

### ✅ Correct

```markdown
This is a [reference link][example] and here's an [image reference][pic].

You can also use [numbered references][1].

[example]: https://example.com
[pic]: /images/photo.jpg
[1]: https://docs.example.com
```

### ❌ Incorrect

```markdown
This is a [broken link][missing] and an [undefined image][nopic].

Here's a [shortcut reference] with no definition.

[other]: https://example.com
```

### 🔧 Fixed

```markdown
This is a [broken link][missing] and an [undefined image][nopic].

Here's a [shortcut reference] with no definition.

[missing]: https://example.com/page
[nopic]: /images/default.jpg
[shortcut reference]: https://example.com/shortcut
[other]: https://example.com
```

## Configuration

This rule has no configuration options - it's either enabled or disabled.

```yaml
MD052: true
```

## Automatic fixes

This rule cannot automatically fix issues because it can't know what URL you intended for missing references. You must manually:

1. Add the missing reference definition at the bottom of your document
2. Or change the reference to use an existing definition
3. Or convert to an inline link if a reference isn't needed

## Learn more

- [Markdown Guide: Reference-style Links](https://www.markdownguide.org/basic-syntax/#reference-style-links)
- [CommonMark: Link reference definitions](https://spec.commonmark.org/0.31.2/#link-reference-definitions)

## Related rules

- [MD051 - Fix broken link fragments](md051.md)
- [MD053 - Remove unused link definitions](md053.md)
- [MD054 - Use consistent link and image style](md054.md)
