md-reflinks 1.0

Command line tool to insert Markdown reference links list in Markdown files.

md-reflinks

md-reflinks is a command-line tool that manages common Markdown reference-style links across multiple Markdown files. You maintain a single master Markdown file which contains all your reference link definitions (e.g. [python]: https://python.org). md-reflinks reads that master file and injects the relevant definitions into one or more target files. This means you only have to manage your reference links in one Markdown file.

By default, only the links that are actually referenced in a target file (i.e. those which appear as [key] tags in the body) are added. Any existing reference-link blocks at the bottom of a target file are replaced.

Usage

Type md-reflinks -h to view the usage summary:

usage: md-reflinks [-h] [-a] [-n] [-f] [-q]
                      master_file_md file_md [file_md ...]

Insert Markdown reference links list in Markdown files.

positional arguments:
  master_file_md      markdown master file to source link definitions
  file_md             markdown target file[s] to update

options:
  -h, --help          show this help message and exit
  -a, --all           append all reference links in the file (default: only
                      append required links)
  -n, --no-normalize  do not normalize reference links (default: normalize
                      keys to remove file name for local reference)
  -f, --force         force update of reference links even if they are
                      unchanged (default: only update if changed)
  -q, --quiet         quiet mode (default: print updated files to stdout)

Installation and Running

The easiest way to install and run md-reflinks is via uvx which is provided by installing uv, e.g.:

uvx md-reflinks README.md docs/*.md

The above will run the latest version of md-reflinks without needing to explicitly install it locally. uvx will handle installation if needed (on the fly very quickly). You can also install it explicitly using uv tool install if you prefer.

The above example will read reference link definitions from README.md and update those required in all the Markdown files in the docs/ directory, inserting, deleting, or replacing them at the bottom of each file.

Note you can also use a wildcard to update all Markdown files in the current directory and md-reflinks will automatically skip the master file itself to avoid self-injection, e.g.:

uvx md-reflinks README.md *.md

License

Copyright (C) 2026 Mark Blakeney. This program is distributed under the terms of the GNU General Public License. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at https://www.gnu.org/licenses/gpl-3.0.html for more details.