remark-github

remark-github is a unified/remark plugin that transforms plain-text references to GitHub commits, issues, pull requests, and user mentions into clickable links, mirroring the autolinking behavior GitHub itself applies inside issues, PRs, comments, and releases. It recognizes patterns like #123, GH-123, user/repo#123, @username, and both short and long commit SHAs, including cross-fork and cross-project forms and compare ranges like base...compare, converting each into a properly formatted markdown link pointing at github.com.

It’s built for cases where markdown is rendered outside GitHub’s own UI, such as a documentation site, blog, or changelog, but should still read the way GitHub renders it. The plugin infers the target repository from the repository field in package.json by default, or accepts an explicit repository option, and exposes a buildUrl hook for redirecting links, for example to point mentions at a company directory instead of GitHub profiles. It intentionally limits itself to GitHub’s reference syntax and defers other GitHub Flavored Markdown extensions, like tables and strikethrough, to sibling plugins such as remark-gfm.

What You Get

• Autolinking of commit SHAs, both short and long, including cross-fork and cross-project reference forms
• Autolinking of issue and PR references such as #123, GH-123, and cross-project user/repo#123
• @mention linking to GitHub user or org profiles, wrapped in strong styling by default
• Compare-range linking (base…compare) to GitHub’s commit-compare view
• A configurable buildUrl hook to redirect any reference type to a custom destination
• Automatic repository detection from package.json, with an explicit override option

Common Use Cases

• Rendering a project’s README or CHANGELOG on a docs site the same way GitHub renders it
• Publishing GitHub Issue/PR-referencing release notes to a blog or changelog page
• Building an internal knowledge base that links teammate mentions to a company’s GitHub org
• Static site generators built on unified/remark that ingest markdown authored with GitHub shorthand
• Migrating GitHub Wiki or Gist content to another CMS while preserving working reference links

Under The Hood

Architecture A single-module design in lib/index.js exports a factory, remarkGithub(options), that returns a unified transformer. The transformer combines one mdast-util-find-and-replace sweep, five ordered pattern/replacer pairs for cross-repo references, mentions, hash-style issues, SHA compare ranges, and bare SHAs, with a second unist-util-visit pass over existing link nodes that renormalizes already-authored GitHub URLs to GitHub’s own shorthand display. Repository resolution is injected through a conditional-exports subpath (#get-repo-from-package) that swaps a Node-specific implementation reading package.json off disk for a no-op default in non-Node environments, keeping environment branching out of the core transform. The only consumer-facing extension seam is the buildUrl option, which keeps the module’s public surface area small and its internal state limited to per-call closures.

Tech Stack Pure ESM JavaScript targeting Node.js 16+, with no runtime framework: it depends on unist-util-visit, mdast-util-find-and-replace, mdast-util-to-string, and vfile/to-vfile from the unified ecosystem. Type-checking runs entirely through JSDoc comments compiled by TypeScript in strict mode, with type-coverage enforcing full strict type coverage, so there is no .ts source at all, only .js plus emitted declaration files. Linting and formatting go through xo and prettier, and the project applies its own ecosystem’s remark-preset-wooorm to lint its own markdown. Continuous integration runs on GitHub Actions across two Node LTS lines with coverage uploaded to Codecov.

Code Quality Tests use Node’s built-in test runner and strict assertions against exact transform output, covering the public API surface, mention wrapping, repository inference and error paths, and custom buildUrl behavior, backed by a fixtures directory of golden-file cases exercised through remark-cli conventions. Coverage is enforced at a full threshold as part of the test script, alongside a strict type-coverage gate. Error handling is explicit: the transform throws descriptive errors for a missing or malformed repository rather than silently no-op’ing, and naming is consistent and documented throughout via JSDoc typedefs.

What Makes It Unique The plugin’s distinguishing choice is reproducing GitHub’s own reference-parsing heuristics closely, including a curated denylist of dictionary words that happen to resemble short hex SHAs so ordinary prose isn’t mangled, and asymmetric punctuation handling for single-dot versus double-dot commit ranges. Rather than a generic linkify pass, it mirrors several distinct GitHub reference grammars with per-grammar disambiguation, and it also re-processes already-written markdown links to match GitHub’s own shorthand display, a detail most autolinking plugins skip. It is a faithful, narrow reimplementation of one platform’s markdown conventions rather than a general capability, so it reads as solid domain-specific engineering rather than a novel abstraction.