Running nf-docs

Generate docs

nf-docs generate PIPELINE_PATH [OPTIONS]

PIPELINE_PATH can be either a pipeline directory or a single .nf file (useful for documenting a standalone module or subworkflow — see Document a single module below).

# HTML — single shareable file
nf-docs generate . -f html -o site/

# Markdown — for static site generators
nf-docs generate . -f markdown -o docs/

# JSON — pipe to file or other tools
nf-docs generate . -f json > api.json

# Table — compact terraform-docs-style tables
nf-docs generate . -f table -o docs/

Document a single module

Pass a path to a single .nf file to generate a focused, module-style document containing only the processes, workflows, and functions defined in that file:

# Writes modules/mytool/subtools/README.md next to main.nf
nf-docs generate modules/mytool/subtools/main.nf --format md

# Pick a different output location
nf-docs generate modules/mytool/subtools/main.nf -f md -o docs/mytool.md

# Or emit structured data to stdout
nf-docs generate modules/mytool/subtools/main.nf -f json

The pipeline-level overview, inputs, and configuration sections are skipped in single-file mode, so the output is suitable as a drop-in README next to the module. A surrounding meta.yml file (nf-core style) is still picked up automatically.

Prek / pre-commit hook

Use the bundled hook with Prek or pre-commit to regenerate docs whenever pipeline documentation inputs change.

repos:
  - repo: https://github.com/ewels/nf-docs
    rev: v0.3.0
    hooks:
      - id: nf-docs

Install the hook into your repo:

# With Prek (recommended)
prek install

# Or with pre-commit
pre-commit install

By default, the hook runs:

nf-docs generate . --format html

That writes HTML documentation to docs/. To customize the command, replace the hook args in your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/ewels/nf-docs
    rev: v0.3.0
    hooks:
      - id: nf-docs
        args: [., --format, markdown, --output, docs/api]

The hook is triggered by changes to *.nf, nextflow.config, nextflow_schema.json, meta.yml, and README files.

Other commands

# Print a summary without generating full docs
nf-docs inspect /path/to/pipeline

# Pre-download the Language Server JAR
nf-docs download-lsp

# Clear the extraction cache for a specific pipeline
nf-docs clear-cache /path/to/pipeline

# Clear the entire extraction cache
nf-docs clear-cache --all

# Show configuration, its file path, or create a starter config file
nf-docs config
nf-docs config --path
nf-docs config --init

Configuration file

nf-docs reads an optional config file at ~/.config/nf-docs/config.yaml (respects $XDG_CONFIG_HOME). It works without one. nf-docs config --init writes a commented starter file, and nf-docs config shows the settings currently in effect.

An option set to the wrong type falls back to its default with a warning. These settings apply to the CLI; the Python API uses defaults unless you pass a config explicitly.

Caching

nf-docs caches extraction results to avoid re-running the Language Server on every invocation. Cached data is stored in ~/.cache/nf-docs/ (respects $XDG_CACHE_HOME).

The cache is keyed by pipeline path, a SHA-256 hash of all pipeline source files, the nf-docs version, and the configuration options that affect extraction — so it is automatically invalidated whenever files change, nf-docs is upgraded, or you edit a setting that changes the output.

Use --no-cache to skip the cache for a single run, or nf-docs clear-cache to remove entries manually.

Output formats

HTML

A single self-contained file with everything inlined:

• Three-column responsive layout with full-text search
• Deep linking to every section and item
• Source code links (GitHub, GitLab, Bitbucket)
• nf-core module documentation links
• Dark mode · mobile-friendly

Markdown

A directory of files, one per section:

docs/
├── index.md        # Pipeline overview
├── inputs.md       # Input parameters
├── config.md       # Config parameters
├── workflows.md    # Workflows
├── processes.md    # Processes
└── functions.md    # Functions

Table

A single README.md with compact Markdown tables — inspired by terraform-docs.

Supports marker-based injection into existing README files:

# My Pipeline

Some intro text.

<!-- BEGIN_NF_DOCS -->
<!-- END_NF_DOCS -->

Other content below.

Running nf-docs generate . -f table -o . will inject the generated tables between the markers, leaving the rest of the file untouched.

Selective sections with template tags

Control which sections appear by adding {{ section }} placeholders between the markers:

<!-- BEGIN_NF_DOCS -->

{{ inputs }}

{{ config }}

<!-- END_NF_DOCS -->

Available tags: {{ header }}, {{ inputs }}, {{ config }}, {{ workflows }}, {{ processes }}, {{ functions }}.

If no tags are present, all sections are rendered (the default).

JSON / YAML

Structured data for programmatic use, CI/CD pipelines, or custom tooling.

See the examples to get a feel for the structure.