docset.mq

Treats a directory of Markdown docs as one documentation set, implemented as an mq module.

Features

• check_links — verifies every relative link ([text](path.md), [text](path.md#anchor), [text](#anchor)) points to a file/heading that actually exists
• duplicate_headings — finds headings within a file whose slug collides (e.g. two "## Notes" sections)
• nav — builds prev/next navigation across every file, ordered by path

http(s):///mailto:/other-scheme links are out of scope — see extract_urls for those. Anchors are matched against the same slugs section::toc_markdown would generate, including its -1/-2 duplicate suffixes.

Installation

Copy docset.mq to your mq module directory, or place it anywhere and reference it with -L.

cp docset.mq ~/.local/mq/config/

HTTP Import (no local installation needed)

HTTP imports are disabled by default; pass --allow-http-import to import directly from GitHub without any local setup:

mq --allow-http-import --allow-read -I raw \
  'import "github.com/harehare/docset.mq" | docset::check_links("./docs")' <<< "x"

Pin to a specific release with @vX.Y.Z:

mq --allow-http-import --allow-read -I raw \
  'import "github.com/harehare/docset.mq@v0.1.0" | docset::check_links("./docs")' <<< "x"

Usage

mq -L /path/to/modules --allow-read -I raw \
  'import "docset" | docset::check_links("./docs")' <<< "x"

If you copied it to the mq built-in module directory:

mq --allow-read -I raw 'include "docset" | check_links("./docs")' <<< "x"

collection() (used internally) requires filesystem read access, so --allow-read (or -A) is required.

API

check_links(dir, respect_gitignore = true)

Returns one {file, url, status, reason} record per relative link found under dir. status is "ok" or "broken"; reason is None when status is "ok".

duplicate_headings(dir, respect_gitignore = true)

Returns one {file, slug, titles} record per set of headings in the same file that slugify to the same anchor.

nav(dir, respect_gitignore = true)

Returns one {path, title, prev, next} record per file, ordered by path. prev/next are None at the ends.

All three take the same arguments as collection: dir (directory to scan for .md/.markdown files) and respect_gitignore (skip dotfiles/dot-directories and .gitignore-matched paths, default true).

Example

Given:

docs/
├── index.md   # links to ./guide.md and #section-in-same-file (a heading in this file)
└── guide.md   # links back to ./index.md#section-in-same-file; has two "## Notes" headings

mq --allow-read -F json -I raw \
  'import "docset" | docset::check_links("./docs")' <<< "x"

[
  {"file": "docs/guide.md", "url": "./index.md#section-in-same-file", "status": "ok", "reason": null},
  {"file": "docs/index.md", "url": "./guide.md", "status": "ok", "reason": null},
  {"file": "docs/index.md", "url": "#section-in-same-file", "status": "ok", "reason": null}
]

mq --allow-read -F json -I raw \
  'import "docset" | docset::duplicate_headings("./docs")' <<< "x"

[{"file": "docs/guide.md", "slug": "notes", "titles": ["Notes", "Notes"]}]

Compatibility

Requires mq v0.8 or later (uses collection(), section::toc_markdown, and Markdown node-kind pattern matching).

License

MIT