elastic / elastic/docs-builder

Cross-repo link validator cannot resolve anchors generated by the {settings} directive

Open
#3,374 2 comments 1 reaction 0 assignees View on GitHub
ai-triaged needs triage stale
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Problem

When a page uses the `{settings}` directive to pull content from a YAML file, the anchors defined via `id:` fields in that YAML are not recognised by the cross-repo link validator.

**Example:** `kibana/docs/reference/configuration-reference/alerting-settings.md` uses:

\`\`\`markdown
:::{settings} /reference/configuration-reference/alerting-settings.yml
:::
\`\`\`

The YAML file defines section anchors such as:

\`\`\`yaml
- group: Action settings
id: action-settings
- group: Alerting settings
id: alert-settings
- group: General settings
id: general-alert-action-settings
- setting: xpack.actions.email.domain_allowlist
id: action-config-email-domain-allowlist
\`\`\`

These anchors are valid in the rendered output, but `kibana://` links from `docs-content` that reference them (e.g. `kibana://reference/configuration-reference/alerting-settings.md#action-settings`) fail validation with:

```
'reference/configuration-reference/alerting-settings.md' has no anchor named: '#action-settings'
```

## Impact

In `docs-content`, 8 links across 7 files had to have their fragments stripped as a workaround (see elastic/docs-content#6632). This loses precision for the reader.

## Expected behaviour

The link validator should expand `{settings}` directive content (or index the `id:` fields from the referenced YAML) so that fragment anchors generated by the directive are considered valid targets for cross-repo link validation.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.