influxdata / influxdata/docs-v2
v2 API reference per-tag pages: link-checker reports file-not-found
- 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