Lint: warn when a docs page will not be rendered on the website #4474

Summary

A markdown file added to a pipeline's docs/ directory is only rendered on the nf-core website if its path contains the substring usage or output. Anything else renders correctly on GitHub and 404s on the website, with nothing to warn the author.

A lint check would catch this on the PR that introduces the file, which is the only point at which it is cheap to fix.

Background

From nf-core/website, sites/main-site/src/components/octokit.js, getDocFiles:

file.type === "file" && file.name.includes(".md") &&
  (file.path.includes("output") || file.path.includes("usage"))

The result becomes release.doc_files in pipelines.json, which is what the site iterates over to generate routes. A file that misses the test never gets a route.

The established way to add a page is therefore to put it under docs/usage/ or docs/output/, which a dozen pipelines already do (mag/docs/usage/resource_guidance.md, airrflow/docs/usage/FAQ.md, oncoanalyser/docs/usage/key_concepts.md, and about 50 files in total).

Context and the full survey are in nf-core/website#4408, which proposes fixing the specification wording. This issue is the complementary half: documentation only helps an author who happens to have read it, whereas a lint check fires exactly when the mistake is made.

Why it needs a check rather than just documentation

The failure has every property that makes a bug survive:

• It is invisible where the work happens. The page renders correctly on GitHub, so the author sees it working and the reviewer sees it working.
• It only manifests on the website, after merge and deploy.
• It manifests as an absence — no page — rather than an error, so nothing alerts anyone.
• Any links to the page also render fine on GitHub, so those look correct in review too.

nf-core/metatdenovo shipped docs/large_datasets.md with six links to it from docs/usage.md, and it was unreachable on the website for its entire life. Nobody noticed, including the people who wrote and reviewed it.

Suggested check

Warn when a markdown file under docs/ will not be rendered by the website, i.e. when its path is neither docs/usage.md nor docs/output.md, and it is not under docs/usage/ or docs/output/.

Files that should not trigger it: docs/README.md (present in all 144 active pipelines) and docs/CONTRIBUTING.md (present in 92), plus anything under docs/images/, which the website already skips explicitly.

A warning rather than a failure seems right, since a pipeline may legitimately keep a working document in docs/ that it does not want published — around twenty such files exist across the org today (development_plan.md, implementation_design.md, abstracts/*.md, dev/metro_map.md and similar). Those authors should be able to ignore the warning, or a .nf-core.yml lint exception would cover it in the usual way.

The message should say what to do, not just what is wrong — something along the lines of: docs/troubleshooting.md will not be rendered on the nf-core website. Move it to docs/usage/troubleshooting.md to publish it as a sub-page of the usage section.

Open questions for a maintainer

• Is docs/ layout within scope for pipeline linting, or is this better placed elsewhere?
• Should the two markdown files a pipeline is required to have (docs/usage.md, docs/output.md) be checked for existence by the same test, or is that already covered by files_exist?

Happy to implement it if the shape above sounds right.

Investigated with some help from Claude Code.