elastic / elastic/docs-builder
Cross-repo link validator cannot resolve anchors generated by the {settings} directive
- 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
Assessment
This issue has not been assessed yet.