Seqera documentation

This repository contains the documentation published to docs.seqera.io. We're using Docusaurus v3, along with whichever Remark plugins are required for our purposes.

Changes merged to master are deployed to production automatically via Netlify. Pull requests have their own deployment preview.

The source of truth for all products' documentation lives in their respective product repositories, such as wave. These repositories contain a docs folder which house the latest version of that product's documentation.

For more information, see:

• Seqera documentation
  • Architecture
    • Seqera Platform
    • Wave
  • Writing new content
  • Fixing legacy content
  • Creating internal links
  • Changelog automation
  • Platform table update workflows

Architecture

Contentful/relevant files include:

├── README.md
├── docusaurus.config.js // website config
├── platform-enterprise_versioned_docs // versioned Platform docs
│   ├── version-22.4.0
│   ├── version-23.1.0
│   ├── version-23.2.0
│   └── version-23.3.0
├── platform-enterprise_versioned_sidebars // versioned Platform sidebars
│   ├── version-22.4.0-sidebars.json
│   ├── version-23.1.0-sidebars.json
│   ├── version-23.2.0-sidebars.json
│   └── version-23.3.0-sidebars.json
├── platform-enterprise_versions.json
└── wave_docs // Git submodule

Seqera Platform

The Platform documentation is versioned and lives in the platform-enterprise_versioned_docs directory. Each version in this directory also requires a sidebar config, which lives in the platform-enterprise_versioned_sidebars directory. Versions also need to be specified in platform-enterprise_versions.json. When adding a new latest version, the docusaurus.config.js needs to be updated as well.

We have a script which can select a commit (or ideally release tag) to be used for publishing a new version on the docs website.

Write and edit content

Install pre-commit

We use pre-commit in our repo, which is invoked when a commit is made. When you (or Claude) are working locally and commit your changes in VS Code (or run git commit) the pre-commit hooks defined in the precommit config file are executed and may tweak the files you're staging. We currently use basic standard hooks to remove trailing whitespaces, make sure the file ends with a newline, we check yaml documents and we prevent very large files from getting committed. More hooks may get installed in the future.

1. Open up a Terminal window and navigate to the docs repository.

2. Run the following commands to set up pre-commit hooks:

   $ pip install pre-commit
   $ pre-commit install
   $ pre-commit install-hooks

You shouldn't experience any issues but if you do, share them in the #team-documentation channel so we can try help.

:::note You only have to install pre-commit once. :::

Make changes and create a PR

1. In GitHub, or VS Code, create a new branch (e.g., gh-issue-number).
2. Complete the necessary work, save your changes, and commit.
3. In GitHub, create a PR to merge your updates to master.
4. Add relevant labels to your PR and request reviews from:
   • Language review from a docs-codeowners member.
   • Technical review from the backend engineer or other SME closest to the feature.
5. Check and review the changes using the Netlify preview.
6. If you created the PR, the onus is on you to merge the PR once approved. This is the Edu team's policy, to ensure that PRs are never merged inadvertently. If you'd like one of us to merge it for you, please let us know.

Once merged to the master branch, the changes will be live immediately.

Fixing legacy content

Version-specific changes to legacy documentation sets currently occur directly in this repository. Each product has a product_versioned_docs folder in this repository. That folder contains a subfolder for each version — edit the files in these versioned folders directly to update versioned content on docs.seqera.io:

1. Create a new branch in this repository, such as product-gh-issue-number.
2. Create the change in the related files in the correct version (e.g., 23.1.0) directory, and any other versions affected.
3. Raise a PR based for review, requesting the same 2 reviews as for new content.
4. After approval, merge the PR to the master branch.

Creating internal links

You can link between Markdown files with relative links within the same documentation set. If you need to link to a different documentation set, such as Wave or Fusion, you must use the HTTPS path. For example:

For more information, see [Fusion](https://docs.seqera.io/fusion).

Changelog automation

Release notes for Fusion, Wave, Nextflow, and MultiQC are automatically generated from GitHub releases. A scheduled workflow runs twice daily to check for new releases and creates PRs with changelog entries.

How it works

1. The workflow (.github/workflows/changelog-from-releases.yml) polls GitHub for releases from:

   • seqeralabs/fusion
   • seqeralabs/wave
   • nextflow-io/nextflow
   • MultiQC/MultiQC

2. For each new release, it generates a formatted changelog file and creates a PR

3. PRs are ready for review (not drafts) and require manual merge

Manual usage

You can also run the changelog generator locally to backfill missing releases:

# Show help
uv run .github/scripts/generate-changelog.py --help

# Generate changelog for a specific release
uv run .github/scripts/generate-changelog.py --repo seqeralabs/wave --release v1.32.0

# Generate changelogs for the last 10 releases
uv run .github/scripts/generate-changelog.py --repo seqeralabs/wave --last 10

# Generate changelogs for the last 10 releases, overwrite existing markdown
uv run .github/scripts/generate-changelog.py --repo seqeralabs/wave --last 10 --overwrite

# Generate changelogs for a date range
uv run .github/scripts/generate-changelog.py --repo MultiQC/MultiQC --from 2024-01-01 --to 2024-12-31

# Dry run to preview what would be generated
uv run .github/scripts/generate-changelog.py --repo seqeralabs/fusion --last 5 --dry-run

# Generate changelog and create a PR for it
uv run .github/scripts/generate-changelog.py --repo seqeralabs/wave --release v1.32.0 --create-pr

The script uses uv for dependency management - dependencies are installed automatically on first run.

For private repositories (seqeralabs/fusion), you need a GitHub token with repository access:

export GH_TOKEN=$(gh auth token)

Changelog file locations

Product	Directory	Extension
Fusion	changelog/fusion/	.md
Wave	changelog/wave/	.md
Nextflow	changelog/nextflow/	.md
MultiQC	changelog/multiqc/	.mdx

Platform table update workflows

Some Platform reference tables are generated from source files in the seqeralabs/platform repository. Platform release workflows send a repository_dispatch event to this repository, and the docs workflow opens a draft PR with the generated table updates.

Permissions tables

Applies to Enterprise and Cloud documentation Permissions documentation is updated by .github/workflows/update-permissions-docs.yml, using .github/scripts/update-permissions-tables.py.

The workflow listens for the permissions-docs-updated dispatch event from Platform. It expects changed_files to include one or both of:

• docs/grants_roles.md
• docs/grants_operations.md

When changes are detected, the workflow checks out Platform with a Platform-scoped docs bot app token, regenerates the permissions tables, and opens a draft PR against this repository with a Docs-scoped docs bot app token. The generated PR branch is named permissions-docs-update-{platform_ref}.

The Platform trigger runs for Cloud release tags such as v26.1.0-cycle41 and Enterprise release candidate tags such as v26.2.0-RC1-enterprise. Cloud tags compare against the previous Cloud release tag. Enterprise RC tags compare against the previous stable Enterprise release tag, such as v26.1.0-enterprise.

Audit event tables

Applies to Enterprise documentation only Audit event documentation is updated by .github/workflows/update-audit-events-docs.yml, using .github/scripts/update-audit-events-tables.py.

The workflow listens for the audit-events-docs-updated dispatch event from Platform. It expects changed_files to include:

• docs/audit_events.md

The Platform trigger is intended for Enterprise release candidate tags, such as v26.1.0-RC5-enterprise. The docs workflow checks out the Platform ref from the dispatch payload, regenerates the unversioned Enterprise audit event tables from docs/audit_events.md, and opens a draft PR. Versioned docs are not updated by this workflow; make versioned updates manually when required.

Manual workflow runs

You can run either workflow manually from the GitHub Actions tab in this repository.

For permissions, run Update Permissions Documentation and provide:

• changed_files: docs/grants_roles.md, docs/grants_operations.md, or both as a comma-separated list.
• platform_ref: optional Platform tag, branch, or commit SHA to read grants files from. Use the release tag when reproducing an automated release update.
• previous_tag: optional context for the generated PR body.

For audit events, run Update Audit Events Documentation and provide:

• changed_files: docs/audit_events.md
• platform_ref: the Platform tag, branch, or commit SHA to read docs/audit_events.md from, such as v26.1.0-RC5-enterprise
• previous_tag: optional context for the generated PR body

You can also trigger the Platform-side workflows manually from the Platform repository. Use the exact source file paths above in changed_files if you want to bypass tag-diff detection.

Troubleshooting

If the docs workflow does not start:

• Confirm the Platform-side workflow ran on a matching tag pattern. Permissions use Cloud release tags such as v*-cycle* and Enterprise RC tags such as v*-RC*-enterprise; audit events use Enterprise RC tags such as v*-RC*-enterprise.
• Confirm the Platform-side workflow detected one of the expected source files. If the tag diff does not include the source file, no dispatch event is sent.
• Check that the Platform workflow dispatched the expected event type: permissions-docs-updated or audit-events-docs-updated.
• Confirm the Platform repository has the docs bot secrets required to dispatch to this repository.
• Confirm this repository has the docs bot secrets required to read Platform and create draft PRs: DOCS_BOT_APP_ID and DOCS_BOT_APP_PRIVATE_KEY.

If the docs workflow starts but fails:

• Check the Validate payload step. The workflows reject unexpected file paths.
• Check the Platform app token and checkout steps. The docs bot GitHub App must be installed on Platform with contents read access.
• Check the docs app token step. Draft PR creation requires the docs bot GitHub App to be installed on this repository with contents and pull request write access.
• Check the update script output. Parse failures usually mean the source table headings or columns changed.
• Check the Check for changes step. If the generated tables already match, the workflow exits without opening a PR.

Workaround for Netlify memory problems (May 2025)

In May 2025 we added new API docs. This increased the size of the Docusaurus build, and led to Netlify deployment builds running out of memory and time.

To fix this, we added logic to docusaurus.config.js and netlify.toml to split the site builds into multiple separate Netlify deployments, stitched back together with redirects.

This works using the following principles:

• Sections of the docs are defined in variables in docusaurus.config.mjs
• Based on the presence or absence of named environment variables, they are included in the Docuaurus config or not
• By defining these ENV vars in your build environment, you can selectively skip chunks in the build

Deployment works because we have two Netlify sites: seqera-docs and seqera-docs-api. They're the same except that they have different environment variable set in their configuration. This means that whenever you push to master, both deploy and both sites update.

The site's netlify.toml includes some redirects with 200 statuses that take links to missing content on the primary deployment to fetch data from the secondary deployment, without affecting the browser bar URL.