CLICK-EXTRA-REFRESH-DIRECTIVES(1) CLICK-EXTRA-REFRESH-DIRECTIVES(1)

click-extra refresh-directives - Refresh the self-updating blocks embedded in Markdown files.

click-extra refresh-directives [OPTIONS] PATHS...

Refresh the self-updating blocks embedded in Markdown files.

Walks each PATH (a Markdown file, or a directory scanned recursively for Markdown sources) and rewrites every supported self-updating block in place:

- matrix blocks (directive fences and marker regions alike), regenerated from the project git history;

- python:render blocks carrying the :mirror: flag, whose Python code is executed to regenerate the mirrored region below the fence (inserted on first refresh).

Examples nested inside longer code fences are never refreshed or executed.

Pass --check to report stale blocks without writing; the command then exits with a non-zero status, so a continuous-integration job can fail on out-of-date documentation.

Refreshing reads the project git history and needs the sphinx extra: install it with click-extra[sphinx]. Beware: mirror blocks are arbitrary Python executed with the privileges of this process, so only refresh documentation you trust, exactly as you would only build trusted docs.

Do not write; exit with a non-zero status if any block is stale.
Measure and print elapsed execution time.
Location of the configuration file. Supports local path with glob patterns or remote URL.
Ignore all configuration files and only use command line parameters and environment variables.
Validate the configuration file and exit.
Export the configuration in the selected format to <stdout>, then exit.
Accessibility mode: disable colors and render tables in a plain, screen-reader-friendly format.
Colorize the output. A bare --color is the same as --color=always.
Disable colorization (alias of --color=never).
Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.
Color theme used for help screens.
Show all CLI parameters, their provenance, defaults and value, then exit.
Rendering style of tables.
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
Show the tree of nested subcommands and exit.
Show the command's man page (roff) and exit.
Show the version and exit.
Show this message and exit.

Do not write; exit with a non-zero status if any block is stale.
Measure and print elapsed execution time.
Location of the configuration file. Supports local path with glob patterns or remote URL.
Validate the configuration file and exit.
Export the configuration in the selected format to <stdout>, then exit.
Accessibility mode: disable colors and render tables in a plain, screen-reader-friendly format.
Colorize the output. A bare --color is the same as --color=always.
Disable colorization (alias of --color=never).
Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.
Color theme used for help screens.
Show all CLI parameters, their provenance, defaults and value, then exit.
Rendering style of tables.
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
Show the tree of nested subcommands and exit.
Show the command's man page (roff) and exit.
Show the version and exit.
Show this message and exit.

~/.config/click-extra/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}

0
Success.
1
A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).
2
A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.

Kevin Deldycke

2026-07-27 8.6.2.dev0