Spec says additional docs pages are rendered automatically; only docs/usage/ and docs/output/ actually are

Edited twice since filing. The first version proposed publishing every .md under docs/ minus an exclusion list; a survey of all 144 active pipelines showed that would publish around twenty internal planning documents, so that suggestion is withdrawn. The second version framed this as an accidental filter. Having now found the written specification, the issue is narrower and clearer than either: the spec promises something the implementation does not do. History is below for anyone who read the earlier versions.

The specification and the implementation disagree

Bundled documentation states:

Additional pages (e.g., tutorials, FAQs) MAY be added and will be automatically rendered on the nf-core website pipeline page.

They are not automatically rendered. A page is rendered only if its path contains the substring usage or output.

sites/main-site/src/components/octokit.js, in getDocFiles:

} else if (
  file.type === "file" &&
  file.name.includes(".md") &&
  (file.path.includes("output") || file.path.includes("usage"))
) {
  files.push(file.path);
}

That result becomes release.doc_files in pipelines.json (bin/pipelines.json.js), which sites/main-site/utils/loaders.ts iterates to generate routes:

const filesToProcess = [...release.doc_files, "README.md"];

A docs file that misses the substring test never reaches the loader, so no route is generated for it.

Why this is worth fixing rather than shrugging at

The failure is silent and lands far from its cause. The page renders correctly on GitHub — which is where it gets written and reviewed — and 404s only on the website. Nothing in nf-core pipelines lint, in CI, or in the spec warns the author.

nf-core/metatdenovo shipped docs/large_datasets.md with six links to it from docs/usage.md, covering assembly memory problems and recovering a killed Megahit run. It was unreachable on the website for its entire life, and we found out by accident:

https://nf-co.re/metatdenovo/dev/docs/large_datasets/   404
https://nf-co.re/metatdenovo/dev/docs/output/           200

$ curl -s https://nf-co.re/pipelines.json | jq '... metatdenovo ... doc_files'
1.4.1  ["docs/output.md", "docs/usage.md"]
dev    ["docs/output.md", "docs/usage.md"]

An author who reads the spec sentence above has no reason to suspect any of this.

Note that #4385 changed the shape of the failure rather than fixing it: such links now rewrite to a clean, plausible-looking /metatdenovo/<version>/docs/large_datasets/ rather than a mangled relative path, which makes the 404 easier to spot but no less of a 404.

What already works, and must keep working

docs/usage/ and docs/output/ subdirectories are published today, and a dozen pipelines rely on it — 50 files in total:

airrflow      docs/usage/{FAQ,bulk_tutorial,genotyping_tutorial,single_cell_tutorial}.md
bactmap       docs/usage/{faq-troubleshooting,tutorials}.md
createtaxdb   docs/usage/{faq,tutorials}.md
crisprseq     docs/{usage,output}/{screening,targeted}.md
mag           docs/usage/{new_to_mag,resource_guidance}.md
oncoanalyser  docs/usage/{compute_resources,faq_and_troubleshooting,key_concepts}.md
proteinfold   docs/usage/{alphafold2,alphafold3,boltz,colabfold,esmfold,helixfold3,…}.md
…and denovotranscript, differentialabundance, methylseq, multiplesequencealign

The route in sites/pipelines/src/pages/[pipeline]/[version]/docs/[...md_file].astro already handles these, including directory-style URLs for index files and a left sidebar once a section holds more than one page. This is a real, working feature — it is just undocumented, and it is the only way to add a page.

Why "publish everything under docs/" is not the fix

Across the 144 active pipelines, top-level docs/*.md files that are currently dropped split into two groups.

Genuine documentation a reader would want:

troubleshooting.md   qc.md   pipeline_steps.md   methods.md
reproducibility.md   configuration.md   large_datasets.md

And internal working documents that should stay unpublished:

strict_syntax_fix_plan.md   retreat-brainstrorming.md   development_plan.md
implementation_design.md    data_contracts.md           architecture.md
testcases.md   truth.md   benchmark.md   monolithic_container_versions.md
development/{manual_tests,dev_docs,code_conventions}.md
abstracts/2018-06-NPMI.md   abstracts/2018-07-JOBIM.md   (and two more)
dev/metro_map.md  (5 pipelines)

Plus docs/README.md in all 144 and docs/CONTRIBUTING.md in 92.

Publishing all of docs/ would put roughly twenty internal planning documents on the website, in repos whose authors never opted into that.

Suggested fix

Make the specification say what the implementation does, rather than the other way round. Replace:

Additional pages (e.g., tutorials, FAQs) MAY be added and will be automatically rendered on the nf-core website pipeline page.

with something like:

Additional pages (e.g., tutorials, FAQs) MAY be added under docs/usage/ or docs/output/, and will be automatically rendered on the nf-core website pipeline page as sub-pages of the corresponding section. Markdown files elsewhere in docs/ are not rendered on the website.

That is a one-line change to sites/docs/src/content/docs/specifications/pipelines/requirements/documentation.md, it documents a convention a dozen pipelines already follow, and it costs no pipeline anything.

Optionally, and separately, the substring test could become an exact match on usage.md/output.md plus a prefix match on docs/usage/ and docs/output/. That would change nothing for any pipeline surveyed, and would only remove accidental matches such as a hypothetical docs/my_usage_notes.md. Lower priority than the wording fix, since nobody is known to have been bitten by it.

I am happy to open the specification PR if the wording above looks right.

Related

The complementary half — catching this at the moment the mistake is made, rather than relying on an author having read the spec — would be a lint check in nf-core/tools. Filed as nf-core/tools#4474.

The pipeline-side fix for the case that prompted this is nf-core/metatdenovo#528.

---

Investigated with some help from Claude Code.