Repolode
Submit
bwplotka

bwplotka/mdox

A Go CLI for formatting markdown in GFM style, auto-generating code snippets from commands, checking links, and building static doc websites from markdown.

View on GitHub
Stars
85
Forks
12
Open issues
33
Last commit
5 days ago

What is it?

mdox is a command-line tool for keeping project documentation accurate and consistent. It formats markdown files in place following GitHub Flavored Markdown, and it can validate both relative and remote links, with options to skip specific URLs or check GitHub issue and pull request links through the GitHub API.

Its code generation feature rewrites fenced code blocks marked with an mdox-exec directive by running a command and inserting its output. This keeps CLI help text, sample configuration files, or source excerpts in sync with the code they describe. Non-zero exit codes can be declared per block.

For websites, mdox can rewrite links to relative paths for multi-domain or multi-version sites, and run transformations that add front matter and back matter, rename or move files, and adapt links for static site generators such as Hugo. It can also be used as a Go library.

Key features

  • 01Formats markdown files in place to a consistent GFM style.
  • 02Auto-generates code block content by running commands, such as CLI help output.
  • 03Checks relative and remote links, with configurable skip rules and GitHub-aware validation.
  • 04Rewrites links to relative paths for multi-domain or multi-version websites.
  • 05Transforms markdown with front matter, back matter, and file moves for static site generators.

Use cases

  • Keeping CLI help and configuration examples in a repository README up to date through CI.
  • Catching broken links in documentation during pull request checks.
  • Publishing versioned project documentation from markdown sources to a static website.

Quick start

  1. 1

    Install the mdox CLI with Go

  2. 2

    Format markdown files with mdox fmt

    mdox fmt *.md

Things to know

  • The README does not give an explicit go install command, so the install step is not shown as a command.
  • The project is small, with 80 stars, so community support may be limited.

In collections

CLI & terminal toolsStatic site generators & documentation tools

Topics

#markdown#documentation#cli#link-checker#static-site#golang#code-generation

FAQ

What is mdox?
A Go CLI for formatting markdown in GFM style, auto-generating code snippets from commands, checking links, and building static doc websites from markdown. mdox is a command-line tool for keeping project documentation accurate and consistent. It formats markdown files in place following GitHub Flavored Markdown, and it can validate both relative and remote links, with options to skip specific URLs or check GitHub issue and pull request links through the GitHub API.
Is mdox free to use? What license does it have?
mdox is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is mdox still maintained?
Actively maintained. The last commit to mdox was on Nov 3, 2026.
What can I use mdox for?
Keeping CLI help and configuration examples in a repository README up to date through CI. Catching broken links in documentation during pull request checks. Publishing versioned project documentation from markdown sources to a static website.
How do I install mdox?
Install the mdox CLI with Go Format markdown files with mdox fmt: mdox fmt *.md
Where can I get mdox?
The source code and installation instructions are on GitHub: https://github.com/bwplotka/mdox

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects