influxdata / influxdata/docs-v2

v2 API reference per-tag pages: link-checker reports file-not-found

Open
#7,175 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Summary

The link-checker on PR #7173 (CI run: https://github.com/influxdata/docs-v2/actions/runs/25182601351/job/73831436424) reports 6 `Cannot find file` errors for `/influxdb/v2/api/*` paths even though the source content exists. Likely a build-pipeline issue (per-tag pages not rendering at expected URLs) rather than a link-source issue.

## Broken links

- [ ] `/influxdb/v2/api/users` — content exists at `content/influxdb/v2/api/users/_index.md`
- [ ] `/influxdb/v2/api/tasks` — content exists at `content/influxdb/v2/api/tasks/_index.md`
- [ ] `/influxdb/v2/api/backup` — content exists at `content/influxdb/v2/api/backup/_index.md`
- [ ] `/influxdb/v2/api/secrets` — content exists at `content/influxdb/v2/api/secrets/_index.md`
- [ ] `/influxdb/v2/api/buckets` — content exists at `content/influxdb/v2/api/buckets/_index.md`
- [ ] `/influxdb/v2/api` — bare path; source link couldn't be located via grep

## What I've verified

All five `_index.md` files exist with consistent front-matter:

```yaml
type: api
layout: list
staticFilePath: /openapi/influxdb-oss-v2/api/tags/influxdb-oss-v2-api-.yaml
specDownloadPath: /openapi/influxdb-oss-v2-api.yml
```

The link-checker error format is `Cannot find file: file:///home/runner/work/docs-v2/docs-v2/public/influxdb/v2/api/` — i.e., the built site doesn't have a file at the expected path. Possibilities:

1. Hugo's build of these pages doesn't produce a directory index at `public/influxdb/v2/api//index.html` in the CI environment (works locally?).
2. The `staticFilePath` referenced YAMLs (`/openapi/influxdb-oss-v2/api/tags/...yaml`) aren't being generated by the build, causing the page render to fail or skip.
3. The link-checker is checking a path format that doesn't match how Hugo serves these (trailing-slash vs. no-trailing-slash, file vs. directory index).

## Source pages with these links

- `content/influxdb/v2/reference/release-notes/influxdb.md` (multiple lines)
- `content/influxdb/v2/process-data/manage-tasks/view-tasks.md`
- `content/influxdb/v2/process-data/manage-tasks/run-task.md`
- `content/influxdb/v2/admin/buckets/create-bucket.md`
- `content/influxdb/v2/get-started/setup.md`
- `content/kapacitor/v1/working/flux/_index.md`

These are link sources, not the root cause. The actual fix likely lives in the build pipeline that generates the per-tag pages or the link-checker config.

## Suggested investigation

1. Run a local Hugo build and inspect `public/influxdb/v2/api/` to see what's actually generated.
2. Check whether `/openapi/influxdb-oss-v2/api/tags/*.yaml` files are produced (generated from `api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml` by some splitter).
3. Confirm whether the link-checker config should treat `api/tag/` style paths as expected-index directories.

## Provenance

Surfaced by the link-checker job on PR #7173. Pre-existing — not introduced by that PR (which only touched `api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml` as a 10-line surgical patch unrelated to per-tag page generation).

Contributor guide

No contributing guide indexed for this repository

Research direction

Run a local Hugo build and inspect public/influxdb/v2/api/ to compare generated paths with the six broken links. Check whether the per-tag YAML files under /openapi/influxdb-oss-v2/api/tags/ are produced from api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml, then review the link-checker configuration. Done means the per-tag pages or expected link paths exist and the checker passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
build-system, documentation, testing-qa
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.