Skip to content

CI and automation

Commit a metro-map .mmd to your pipeline repo and let automation keep the rendered SVG in sync. nf-metro ships two integrations:

  • A composite GitHub Action that installs nf-metro and renders the map, leaving you to decide what to do with the result.
  • A pre-commit hook that re-renders the SVG locally on every commit.

GitHub Action

Section titled “GitHub Action”

The composite action renders the map and reports what it wrote and whether anything changed.

.github/workflows/metro.yml
- uses: actions/checkout@v4
- uses: seqeralabs/nf-metro@2.1.0
The id is how later steps read steps.metro.outputs.*.
  id: metro
  with:
Path of the .mmd to render.
    input: assets/metro_map.mmd
    theme: nfcore
    embed-font: "true"
# steps.metro.outputs.output-path — the path(s) written, one per line
# steps.metro.outputs.changed     — 'true' when any output differs from the committed version

Every input is optional:

  • input: default assets/metro_map.mmd.
  • output: default is the map’s %%metro output: path(s), else the sibling .svg. Give several whitespace-separated paths to write more than one format in a single run, each taken from its extension: output: "assets/metro_map.svg assets/metro_map.png". A path here can’t contain a space; declare it with %%metro output: in the .mmd instead if it needs one.
  • theme: default nfcore.
  • mode: no default.
  • embed-font: default true.
  • version: the nf-metro version to install.
  • extra-args: any other nf-metro render flag, such as extra-args: "--fold-threshold 20".

When it writes more than one file, output-path lists them one per line and changed is 'true' if any of them differs from what is committed. The action reads these straight from nf-metro’s own output, so declaring the paths with %%metro output: in the .mmd and leaving output empty renders and tracks every declared file. The action always renders with --reject-output-outside-source, so a %%metro output: declaration that resolves outside the pipeline repository holding the .mmd (an absolute path, or a .. escape past the repo root), or into that repository’s .git/, fails the step instead of being written: a workflow rendering a .mmd it doesn’t control (an external contributor’s PR, say) can’t be made to write, or steer a later commit or diff step, outside its own checkout. Paths that stay inside the checkout are fine, .. hops included, so assets/metro_map.mmd can declare ../docs/images/metro_map.svg.

Several images from one .mmd

Section titled “Several images from one .mmd”

A %%metro output: path can carry per-output render overrides after a |, which is how one action run produces a whole image set without any extra-args:

%%metro output: nf-core-demo_metro_map.svg
Per-output overrides follow a |.
%%metro output: nf-core-demo_metro_map_animated.svg | animate
%%metro output: nf-core-demo_metro_map_dark.png     | mode=dark
%%metro output: nf-core-demo_metro_map_light.png    | mode=light

Leave the action’s output input empty and every declared file is rendered, listed in output-path, and covered by changed. The same block drives the pre-commit hook below, so a single commit keeps all four in sync.

Pre-commit hook

Section titled “Pre-commit hook”

Re-render the SVG locally on every commit so it cannot drift from the source.

.pre-commit-config.yaml
repos:
  - repo: https://github.com/seqeralabs/nf-metro
    rev: 2.1.0
    hooks:
      - id: nf-metro

The hook matches *.mmd and writes the sibling .svg. assets/metro_map.mmd becomes assets/metro_map.svg. A map that declares %%metro output: paths instead writes those (for example an .svg and a .png), so a single commit keeps every declared file in sync. Each of those paths can set its own animate/mode/theme/scale/raster_width after a |, so the hook needs no args to keep a light/dark/animated set current. It runs with --theme nfcore --embed-font by default. Setting args replaces that whole list. Repeat the flags you want to keep alongside the new one:

.pre-commit-config.yaml
- id: nf-metro
The one new flag. The rest repeat the defaults.
  args: [--theme, nfcore, --embed-font, --mode, light]

Drop --theme nfcore if the map picks its own brand with a %%metro style: directive, which the flag would otherwise override.