influxdata / influxdata/docs-v2
refactor(api-docs): extract Related Guides from operation descriptions into x-related
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Summary
Upstream OpenAPI spec operation descriptions contain `#### Related guides` and `#### Related endpoints` headings with inline markdown links. These render as raw text in Hugo templates because `sanitizeDescription` strips fragment anchors and doesn't process markdown links in operation descriptions.
These links should be extracted into structured related links so they render properly.
## Scope
~190 instances across 5 source spec files:
| Spec | Count |
|---|---|
| `influxdb/cloud/influxdb-cloud-v2-openapi.yaml` | 76 |
| `influxdb/v2/influxdb-oss-v2-openapi.yaml` | 70 |
| `influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml` | 36 |
| `influxdb3/enterprise/influxdb3-enterprise-openapi.yaml` | 8 |
| `influxdb3/core/influxdb3-core-openapi.yaml` | 4 |
These are in **operation-level** `description` fields under `#### Related guides` or `#### Related endpoints` headings.
## What to do
1. Extend `sanitizeDescription` in `openapi-paths-to-hugo-data/index.ts` to extract `#### Related` sections from operation descriptions
2. Store extracted links as structured data in the article data
3. Render them in the Hugo operation template as a styled "Related" section
4. Remove the heading and link list from the rendered description text
## Example
Before (raw text in rendered page):
```
#### Related guides - Manage buckets(/influxdb/cloud/admin/buckets/)
```
After: clean description + structured related links rendered by template.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in openapi-paths-to-hugo-data/index.ts by reading sanitizeDescription and tracing how operation data reaches the Hugo operation template. Update the article data path so links under operation-level Related guides or Related endpoints sections are structured and rendered as a styled Related section, while the headings and link lists no longer appear in the description. Verify the behavior against the five listed OpenAPI spec files.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- hugo, openapi, typescript
- Domain
- documentation
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100