# Avoid acronyms in titles or headings (EK00002)

import { Aside, Badge } from '@astrojs/starlight/components';

Spelling out an uncommon acronym in a title or heading keeps your headings clear to readers who don't yet know your abbreviations. EkLine flags an uncommon acronym that appears in a title or heading (rule EK00002) and suggests the spelled-out term, while widely known acronyms such as API and AWS are exempt.

## Why avoid acronyms in headings?

Headings orient readers and appear in navigation, search results, and page outlines. An unfamiliar acronym in a heading forces readers to guess what a section covers before they reach the body text. Spelling out the term in the heading, and introducing the acronym in the body, keeps your structure scannable for readers who don't yet know your abbreviations.

## What EkLine flags

EK00002 matches an uncommon acronym in a title or heading and leaves widely recognized acronyms, such as API and AWS, untouched.

- ❌ **Incorrect:** Set up SSO
- ✅ **Correct:** Set up single sign-on
- ❌ **Incorrect:** Configure RBAC
- ✅ **Correct:** Configure role-based access control

## How to fix

Replace the acronym with its full term in the heading. Introduce the acronym in the body text on first use, then use the short form in the sentences that follow.

<Aside type="note">
A widely known acronym in a heading is a valid reason to keep it. If your audience treats a term as common knowledge, silence the rule for that line.
</Aside>

## FAQ

### Which acronyms are safe to use in a heading?

Widely recognized acronyms, such as API and AWS, are exempt because most readers already know them. Spell out uncommon acronyms and introduce the short form in the body text.

### Where should you define an acronym you use in a heading?

Introduce the acronym in the body text on first use, then use the short form in the sentences that follow.

## Rule details

| Property | Value |
|----------|-------|
| Rule ID | `EK00002` |
| Category | Titles and headings |
| Default severity | <Badge text="Warning" variant="caution" /> |
| Enabled by default | No |

## Ignore this rule

To keep an acronym in one heading, add an inline comment with a reason:

```markdown
<!-- ekline-ignore-next-line EK00002 -- acronym is standard for this audience -->
## Configure SAML
```

To disable the rule across your project, add it to the `ignore` list in your [configuration file](/reviewer/configuration/ignoring-rules/#ignore).

## Related rules

- [EK00009](/reviewer/rules/define-abbreviations/) — Define unfamiliar terms and abbreviations
- [EK00037](/reviewer/rules/sentence-case-headings/) — Use sentence-style capitalization in headings