Add manifest.diagram to the pipeline template, with linting

[ewels]

Nextflow recently added manifest.diagram: a relative path to the pipeline's workflow diagram. It lands in Nextflow 26.10. Older versions ignore unknown manifest fields, so it's safe to set in any pipeline today.

Template

Adds the field to nextflow.config, commented out with a TODO, since a brand new pipeline has no metro map yet:

// TODO nf-core: Make a metro map (nf-metro or drawn) and add relative path to the SVG below
// diagram      = 'docs/images/metro_map.svg'

nf-metro is mentioned as a recommendation, not a requirement — any SVG works, however you make it.

Linting

Both checks live in the existing nextflow_config lint test rather than a new one:

• Warning if manifest.diagram is not set. A freshly created pipeline gets this warning until the author draws a map, alongside the other template TODO warnings.
• Failure if it is set but is a URL rather than a relative path, is not one of the image formats Nextflow accepts (.svg, .png, .jpg, .jpeg, .gif, .webp), or points at a file that isn't in the repository.

The lint docs are generated from the test's docstring, which is updated to cover both.

Since a new pipeline now always produces the missing-diagram warning, the existing assert len(result["warned"]) == 0 assertions in test_nextflow_config.py now assert that this is the only warning. Four new tests cover the valid path, missing file, unsupported format and URL cases.

CI

create-lint-wf and create-test-lint-wf-template lint the generated test pipeline with --fail-warned, so the missing-diagram warning would fail those jobs. Both now create a placeholder docs/images/metro_map.svg and uncomment the diagram line first, in the same way they already neutralise the template TODOs and includeConfig.

Pipelines themselves are unaffected: the template's linting.yml doesn't use --fail-warned, so authors get the nudge as a warning.

Docs

The nf-core website side is in nf-core/website#4390 — a new section on the workflow schematics page.

PR checklist

• This comment contains a description of changes (with reason)
• CHANGELOG.md is updated
• If you've fixed a bug or added code that should be tested, add tests!
• Documentation in docs is updated

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.20%. Comparing base (5800db6) to head (1eec0f8).

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[pinin4fjords]

Suggested change

	// TODO nf-core: Make a metro map (nf-metro or drawn) and add relative path to the SVG below
	// TODO nf-core: Make a metro map and add relative path to the SVG below

Don't think we need to push nf-metro in a comment ;-)

[ewels]

I kind of disagree - we're pushing people to make a metro map, which is difficult. nf-metro makes it easy. So by pushing it we're helping people, who might otherwise not know it exists?

If you prefer we could link to the nf-core docs, and have more long form stuff there about different ways to make metro maps (including nf-metro), but I want to give some guidance rather than leaving people to assume that they need to buy a license for Adobe Illustrator..

[pinin4fjords]

Suggested change

	* Any SVG works, including hand-drawn ones. `nf-metro <https://seqeralabs.github.io/nf-metro/latest/>`_
	can generate one from a config file, if you'd like a hand.
	* Any SVG works.

[ewels]

This is what happens if you run a pipeline with this config setting in a version of Nextflow that doesn't support it:

❯ nextflow run ./demo --help

 N E X T F L O W   ~  version 26.04.6

Downloading plugin nf-schema@2.7.2
Launching `./demo/main.nf` [lonely_moriondo] revision: f6f57a9eb7

WARN: Unrecognized config option 'manifest.diagram'

------------------------------------------------------
                                        ,--./,-.
        ___     __   __   __   ___     /,-._.--~'
  |\ | |__  __ /  ` /  \ |__) |__         }  {
  | \| |       \__, \__/ |  \ |___     \`-._,-`-,
                                        `._,._,'
  nf-core/demo 1.2.0
------------------------------------------------------

With strict syntax off (old language parser) there's nothing at all:

❯ NXF_SYNTAX_PARSER=v1 nextflow run ./demo --help

 N E X T F L O W   ~  version 26.04.6

Launching `./demo/main.nf` [festering_rubens] revision: f6f57a9eb7


------------------------------------------------------
                                        ,--./,-.
        ___     __   __   __   ___     /,-._.--~'
  |\ | |__  __ /  ` /  \ |__) |__         }  {
  | \| |       \__, \__/ |  \ |___     \`-._,-`-,
                                        `._,._,'
  nf-core/demo 1.2.0
------------------------------------------------------

[ewels]

Looks good on a wider sweep of Nextflow versions (was worried briefly, but turns out that the error I saw at first was because my version of Java was too new for the old Nextflow version)

Stuff breaks badly if you try to access the config attribute within the pipeline (eg. println workflow.manifest.diagram), but just having it there should be fine, beyond a warning log or two:

---

All runs below on JDK 21 (JDK 17 for ≤23.04). Exit code 0 everywhere, workflow ran, no version failed.

Nextflow	With diagram	Why
21.10.6 – 25.04.8	WARN: Invalid config manifest attribute 'diagram' (printed twice)	Manifest(Map) loops over keys, warns on anything not a getter
25.10.0 – 25.10.7	silent	Manifest rewritten as a ConfigScope with explicit field assignment — unknown keys just fall on the floor
26.04.6, 26.08.0-edge	WARN: Unrecognized config option 'manifest.diagram' (once)	new ConfigValidator, gated on if( NF.isSyntaxParserV2() ) in CmdRun/CmdConfig — hence NXF_SYNTAX_PARSER=v1 silences it

[muffato]

Does this key support defining light-/dark-background images ? We generate all diagrams in both themes (same content, so could pick either)

[pinin4fjords]

Does this key support defining light-/dark-background images ? We generate all diagrams in both themes (same content, so could pick either)

This did occur to me when I was writing that Nextflow PR, but I went with a single value proposition on the assumption that we could make SVGs that worked well enough in light and dark.

[ewels]

SVGs that worked well enough in light and dark.

To elaborate: SVGs can have CSS variable colours that detect the host operating system's light / dark mode. So you can have white text or black text according to that. nf-metro does this by default, I believe. We can write some docs on the concept too.

It's not always super straightforward, eg. if a website's theme is set to light but the OS is dark, but generally it works pretty well. And it is possible to overcome this edge case if needed, with a bit of cleverness.

Worst case, we can just chuck in a non-transparent background to the image and it should be safe everywhere.

[codspeed-hq]

Hooray! CodSpeed harness just leveled up!

The base and head of this comparison were measured with different runner settings, so their benchmark values are not directly comparable.

What changed between base and head:

• CodSpeed runner v5 changed how benchmarks are measured (base 4.18.4 → head 5.0.1). View release notes

Re-run the base with the same settings to get a valid performance comparison.

---

_{Comparing ewels:manifest-diagram (1eec0f8) with dev (cb0ac11)¹}

Footnotes

1. No successful run was found on dev (5800db6) during the generation of this report, so cb0ac11 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩