influxdata / influxdata/docs-v2

refactor(api-docs): extract Related Guides from operation descriptions into x-related

Open
#7,008 0 comments 0 reactions 0 assignees View on GitHub
product:shared product:v2 product:v2-cloud product:v3-monolith
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.