# Markdown Anchor Link Policy

This document defines the anchor generation rules for AO documentation to ensure links work consistently across MkDocs and GitHub.

## Summary

Both MkDocs and GitHub generate heading anchors automatically. To ensure links work on both platforms:

1. Use simple, ASCII heading text when possible
2. Avoid special characters in headings
3. Use the configured `pymdownx.slugs.slugify` function for consistent behavior

## Anchor Generation Rules

### GitHub Rules

GitHub generates anchor IDs using these rules:

1. **Lowercase**: Letters are converted to lowercase
2. **Spaces → Hyphens**: Spaces become hyphens (`-`)
3. **Punctuation removed**: Most punctuation characters are removed
4. **Unicode preserved**: Unicode letters (e.g., Θ, ñ) are kept as-is
5. **Markup stripped**: Formatting like `_italics_` becomes `italics`
6. **Duplicates numbered**: Second `## Heading` becomes `#heading-1`

**Example:**
```
## This'll be a _Helpful_ Section About Θ!
→ #thisll-be-a-helpful-section-about-Θ
```

### MkDocs Rules (with pymdownx.slugs)

With `pymdownx.slugs.slugify(case="lower")`:

1. **Lowercase**: All characters lowercased
2. **Spaces → separator**: Default separator is `-`
3. **Unicode handled**: Preserves Unicode with proper normalization (NFC)
4. **Duplicates numbered**: Same as GitHub

## Configuration

In `mkdocs.yml`:

```yaml
markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
```

This configuration aligns MkDocs anchor generation with GitHub's behavior.

## Best Practices for Headings

### Do

- Use clear, simple headings: `## Getting Started`
- Use hyphens in multi-word concepts: `## CI-CD Integration`
- Keep headings concise

### Avoid

- Special characters: `## What's New?!` → prefer `## What is New`
- Markdown in headings: `## Using `code` blocks` → prefer `## Using Code Blocks`
- Unicode when ASCII suffices: `## Über Settings` → prefer `## Uber Settings`

### Acceptable

- Common Unicode when meaningful: `## C# Guide` (the `#` becomes nothing, so → `#c-guide`)
- Technical terms: `## .NET Configuration`

## Testing Links

Before publishing, verify anchor links work by:

1. Building MkDocs locally: `mkdocs serve`
2. Clicking all internal links
3. Checking GitHub preview renders correctly

## Migration Guidance

If changing anchor format affects existing links:

1. Identify all internal anchor links in documentation
2. Update links to match new anchor format
3. Consider adding HTML anchor aliases for backward compatibility:

```html
<a id="old-anchor-name"></a>
## New Heading Text
```

## References

- [GitHub: Section Links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links)
- [MkDocs Material: Table of Contents](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#table-of-contents)
- [PyMdown Extensions: Slugs](https://facelessuser.github.io/pymdown-extensions/extras/slugs/)
