elastic / elastic/docs-builder

[Feature Request]: Link checking related to API docs

Open
#974 1 comment 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question enhancement
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

### Prerequisites

- [x] I have searched existing issues to ensure this feature hasn't already been requested
- [x] I have tested using the latest version of docs-builder

### What problem are you trying to solve?

While editing the list of "current" redirects in preparation for GA, I was reminded that we have an increasing number of links between the narrative docs and the API docs but AFAIK there is no link checking to ensure those links remain valid.

Possibly related to https://github.com/elastic/docs-builder/issues/123 and https://github.com/elastic/docs-builder/issues/949, however there is even less human intervention, since the API documents are largely automated, so humans are even less likely to know when a specific target disappears.

### Proposed Solution

Similar to https://github.com/elastic/docs-builder/issues/123 it seems to me that we need to have a way of generating a list of URLs (in this case, ones used by the docs, the product, or in our redirects list that target https://www.elastic.co/docs/api/) and periodically testing them. When one of them fails, I assume human intervention will be required to:

- update the source of the link to point to a different target, or
- investigate whether the target was removed in error

### Examples and Research

One example of a situation where API endpoints disappear is when they've gone from being "deprecated" to "discontinued". In such a case if we have pages that still need to cover the older versions' behaviour, we'd update them to use the older branches of the API docs (e.g. there are Upgrade Assistant APIs that exist in https://www.elastic.co/docs/api/doc/kibana/v8/ that do not exist in https://www.elastic.co/docs/api/doc/kibana/v9/ or https://www.elastic.co/docs/api/doc/kibana/ ).

### Alternative Solutions

_No response_

### Additional Context

_No response_

### How important is this feature to you?

Nice to have

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.