From eea710e951d669109448f6710a0785dbd4f5b8de Mon Sep 17 00:00:00 2001
From: onmax
Date: Tue, 10 Nov 2026 11:42:37 +0100
Subject: [PATCH] feat: add a markdown-exit/linkify-gfm plugin that links like
GitHub
---
docs/guide/quick-start.md | 15 +
packages/markdown-exit/package.json | 1 +
packages/markdown-exit/src/linkify-gfm.ts | 418 ++++++++++++++++++
.../markdown-exit/tests/linkify-gfm.test.ts | 82 ++++
packages/markdown-exit/tsdown.config.ts | 2 +-
5 files changed, 517 insertions(+), 1 deletion(-)
create mode 100644 packages/markdown-exit/src/linkify-gfm.ts
create mode 100644 packages/markdown-exit/tests/linkify-gfm.test.ts
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
index fceee5b..02c7674 100644
--- a/docs/guide/quick-start.md
+++ b/docs/guide/quick-start.md
@@ -143,3 +143,18 @@ md.linkify = new LinkifyIt()
> [!WARNING]
> - Plugins that access `md.linkify` (e.g. `md.linkify.set(...)`) throw in the core entry unless you assign a linkify-it instance before calling `md.use()`.
> - If any module in your app imports `markdown-exit` instead of `markdown-exit/core`, linkify-it is bundled anyway, and instances created from `markdown-exit/core` get a linkify-it instance too.
+
+### GitHub-style links
+
+`markdown-exit/linkify-gfm` is a plugin that links text the way GitHub does ([GFM autolinks](https://github.github.com/gfm/#autolinks-extension-)), without linkify-it. It links `www.` addresses, `http://` and `https://` URLs, and email addresses. It does not link bare domains such as `example.com`. markdown-exit still parses inline markdown first, so `www.example.com/a*b*c` links only `www.example.com/a`, where GitHub links the whole URL.
+
+```ts
+import { createMarkdownExit } from 'markdown-exit/core'
+import linkifyGfm from 'markdown-exit/linkify-gfm'
+
+const md = createMarkdownExit().use(linkifyGfm)
+md.render('Visit www.commonmark.org.')
+// Visit www.commonmark.org.
+```
+
+The plugin enables `linkify` and sets `md.linkify`. It has no TLD list and no custom schemas, so `md.linkify.tlds()` and `md.linkify.add()` throw. Pass `{ fuzzyLink: false }` to skip `www.` addresses, or `{ fuzzyEmail: false }` to skip emails without `mailto:`.
diff --git a/packages/markdown-exit/package.json b/packages/markdown-exit/package.json
index b10f64a..03c2433 100644
--- a/packages/markdown-exit/package.json
+++ b/packages/markdown-exit/package.json
@@ -23,6 +23,7 @@
"exports": {
".": "./dist/index.js",
"./core": "./dist/core.js",
+ "./linkify-gfm": "./dist/linkify-gfm.js",
"./package.json": "./package.json"
},
"main": "./dist/index.js",
diff --git a/packages/markdown-exit/src/linkify-gfm.ts b/packages/markdown-exit/src/linkify-gfm.ts
new file mode 100644
index 0000000..ce14aa0
--- /dev/null
+++ b/packages/markdown-exit/src/linkify-gfm.ts
@@ -0,0 +1,418 @@
+import type { LinkifyIt } from 'linkify-it'
+import type { MarkdownExit } from './core'
+
+// GFM autolink literals in plain text, found the way remark-gfm finds them:
+// micromark-extension-gfm-autolink-literal 2.1.0, as published, reads `www.`, `http(s)://`
+// and email literals while it parses, and mdast-util-gfm-autolink-literal
+// 2.1.0 then searches the text between the links it found for what it
+// missed, `mailto:` and `xmpp:` included. Both steps are here, on the text
+// as one run with no other markdown in it. Characters are UTF-16 code units,
+// as micromark reads them.
+
+interface Link {
+ /** `""` for a `www.` link, `http:` or `https:`, `mailto:` for an email, or `xmpp:`. */
+ schema: string
+ /** Where the link starts in the text. */
+ index: number
+ /** Where it ends. */
+ lastIndex: number
+ /** The link as written. */
+ text: string
+ /** Where it points: `http://` before `www.`, `mailto:` before an email. */
+ url: string
+}
+
+const PUNCTUATION = /[\p{P}\p{S}]/u
+const WHITESPACE = /\s/
+
+// micromark's character classes, for a code unit, with -1 for no character.
+const alpha = (c: number) => (c | 32) >= 97 && (c | 32) <= 122
+const alnum = (c: number) => alpha(c) || (c >= 48 && c <= 57)
+const atext = (c: number) => alnum(c) || c === 43 || c === 45 || c === 46 || c === 95
+// A space, a tab or a line ending.
+const space = (c: number) => c === 32 || c === 9 || c === 10 || c === 13
+const whitespace = (c: number) => c > -1 && WHITESPACE.test(String.fromCharCode(c))
+const punctuation = (c: number) => c > -1 && PUNCTUATION.test(String.fromCharCode(c))
+const end = (c: number) => c < 0 || space(c) || whitespace(c)
+
+// Trailing punctuation, which leaves a link when nothing but an end follows.
+// `&` is one too when it starts a character reference, and `]` when an end,
+// `(` or `[` follows it.
+const TRAIL = new Set([33, 34, 39, 41, 42, 44, 46, 58, 59, 63, 95, 126])
+// What a path checks for a trail at: those, `&`, `<` and `]`.
+const PATH_TRAIL = new Set([...TRAIL, 38, 60, 93])
+
+// The text being read. Nothing here calls out, so one at a time is enough.
+let text = ''
+let n = 0
+const at = (i: number) => (i < n ? text.charCodeAt(i) : -1)
+
+// Where the last trail that wasn't one stopped: a trail checked from before
+// it, in the same domain or path, stops there too.
+let failed = -1
+
+/** Whether the punctuation at `i`, and what follows, is a trail before an end. */
+function trail(i: number): boolean {
+ if (i < failed)
+ return false
+ for (;;) {
+ const c = at(i)
+ if (TRAIL.has(c)) {
+ i++
+ } else if (c === 38) {
+ if (!alpha(at(++i)))
+ break
+ while (alpha(at(i))) i++
+ if (at(i) !== 59)
+ break
+ i++
+ } else if (c === 93) {
+ const d = at(++i)
+ if (d === 40 || d === 91 || end(d))
+ return true
+ } else if (c === 60 || end(c)) {
+ return true
+ } else {
+ break
+ }
+ }
+ failed = i
+ return false
+}
+
+/**
+ * A domain from `i`: where it ends, or -1. The last two labels can't have an
+ * underscore, and it needs one character.
+ */
+function domain(i: number): number {
+ let last = false
+ let before = false
+ let seen = false
+ failed = -1
+ for (;;) {
+ const c = at(i)
+ if (c === 46 || c === 95) {
+ if (trail(i))
+ break
+ if (c === 95)
+ last = true
+ else [before, last] = [last, false]
+ } else if (end(c) || (c !== 45 && punctuation(c))) {
+ break
+ } else {
+ seen = true
+ }
+ i++
+ }
+ return before || last || !seen ? -1 : i
+}
+
+/** A path from `i`, to its end. A closing parenthesis stays while it closes one opened in it. */
+function path(i: number): number {
+ let open = 0
+ let closed = 0
+ failed = -1
+ for (;;) {
+ const c = at(i)
+ if (c === 40) {
+ open++
+ } else if (c === 41 && closed < open) {
+ closed++
+ } else if (PATH_TRAIL.has(c)) {
+ if (trail(i))
+ return i
+ if (c === 41)
+ closed++
+ } else if (end(c)) {
+ return i
+ }
+ i++
+ }
+}
+
+/** An `http://` or `https://` link at `i`: its schema and end, or undefined. */
+function protocol(i: number): [string, number] | undefined {
+ let j = i
+ while (alpha(at(j)) && j - i < 5) j++
+ const scheme = text.slice(i, j).toLowerCase()
+ if (
+ (scheme !== 'http' && scheme !== 'https') ||
+ at(j) !== 58 ||
+ at(j + 1) !== 47 ||
+ at(j + 2) !== 47
+ ) {
+ return
+ }
+ const c = at((j += 3))
+ const host = c < 32 || c === 127 || space(c) || whitespace(c) || punctuation(c) ? -1 : domain(j)
+ return host < 0 ? undefined : [`${scheme}:`, path(host)]
+}
+
+// mdast-util-gfm-autolink-literal's searches, in its order.
+const URL = /(? !!label && (label.includes('_') || !/[\dA-Z]/i.test(label))
+
+/** The URL without trailing punctuation, keeping closing parentheses while it has more opening ones. */
+function trim(url: string): string {
+ let i = url.length
+ while (i > 0 && '!"&\'),.:;<>?]}'.includes(url[i - 1]!)) i--
+ if (i === url.length)
+ return url
+ let rest = url.slice(i)
+ url = url.slice(0, i)
+ const open = url.split('(').length - 1
+ let closed = url.split(')').length - 1
+ for (let close = rest.indexOf(')'); close !== -1 && open > closed; close = rest.indexOf(')')) {
+ url += rest.slice(0, close + 1)
+ rest = rest.slice(close + 1)
+ closed++
+ }
+ return url
+}
+
+/**
+ * Every GFM autolink literal in `value`, in order. `www` and `email` set
+ * whether `www.` links and emails without `mailto:` count. With `first`, it
+ * stops at the first link it finds, which says whether there is one.
+ */
+function find(value: string, www = true, email = true, first = false): Link[] {
+ text = value
+ n = value.length
+ const links: Link[] = []
+ const add = (schema: string, index: number, lastIndex: number, prefix = '') => {
+ const raw = value.slice(index, lastIndex)
+ links.push({ schema, index, lastIndex, text: raw, url: prefix + raw })
+ }
+ // What each kind of link needs somewhere in the text, so text without it
+ // isn't searched for that kind.
+ const hasAt = value.includes('@')
+ const hasScheme = value.includes('://')
+ const hasWww = www && /www\./i.test(value)
+ email &&= hasAt
+
+ // micromark's step, at every position: an email that starts with a
+ // letter, digit, `+`, `-`, `.` or `_` after none of those or `/`, then
+ // `http(s)://` at an `h` not after a letter, or `www.` at a `w` at the
+ // start or after whitespace, `(`, `*`, `_`, `[`, `]` or `~`.
+ for (let i = 0; i < (email || hasScheme || hasWww ? n : 0);) {
+ const c = at(i)
+ const previous = i ? at(i - 1) : -1
+ let stop = -1
+ if (email && atext(c) && !atext(previous) && previous !== 47) {
+ let j = i
+ while (atext(at(j))) j++
+ if (at(j) === 64) {
+ let data = false
+ let dot = false
+ for (let d = at(++j); ; d = at(++j)) {
+ if (d === 46 && alnum(at(j + 1)))
+ dot = true
+ else if (d === 45 || d === 95 || alnum(d))
+ data = true
+ else break
+ }
+ if (data && dot && alpha(at(j - 1)))
+ add('mailto:', i, (stop = j), 'mailto:')
+ }
+ }
+ if (stop < 0 && hasScheme && (c | 32) === 104 && !alpha(previous)) {
+ const found = protocol(i)
+ if (found)
+ add(found[0], i, (stop = found[1]))
+ }
+ if (
+ stop < 0 &&
+ hasWww &&
+ (c | 32) === 119 &&
+ (at(i + 1) | 32) === 119 &&
+ (at(i + 2) | 32) === 119 &&
+ at(i + 3) === 46 &&
+ i + 4 < n &&
+ (previous < 0 || space(previous) || [40, 42, 95, 91, 93, 126].includes(previous))
+ ) {
+ const host = domain(i)
+ if (host >= 0)
+ add('', i, (stop = path(host)), 'http://')
+ }
+ if (first && stop >= 0)
+ return links
+ i = stop < 0 ? i + 1 : stop
+ }
+
+ // mdast-util-gfm-autolink-literal's search, of the text between links:
+ // URLs, then xmpp:, mailto: and emails, each through the text the one
+ // before left. A match it turns down, it searches again from the next
+ // character.
+ const needs = [hasScheme || hasWww, value.includes('xmpp:'), value.includes('mailto:'), hasAt]
+ for (let s = 0; s < 4; s++) {
+ const search = SEARCHES[s]!
+ if (!needs[s])
+ continue
+ links.sort((a, b) => a.index - b.index)
+ const gaps: number[] = []
+ let from = 0
+ for (const link of links) {
+ if (link.index > from)
+ gaps.push(from, link.index)
+ from = link.lastIndex
+ }
+ if (from < n)
+ gaps.push(from, n)
+ for (let g = 0; g < gaps.length; g += 2) {
+ const start = gaps[g]!
+ const run = value.slice(start, gaps[g + 1])
+ search.lastIndex = 0
+ for (let m = search.exec(run); m; m = search.exec(run)) {
+ const index = start + m.index
+ const [whole, a = '', b = '', rest] = m
+ let ok = !/[\d\-_]$/.test(b)
+ if (search === URL) {
+ const c = run.charCodeAt(m.index - 1)
+ let host = b
+ let scheme = a
+ let prefix = ''
+ if (/^w/i.test(scheme)) {
+ host = scheme + host
+ scheme = ''
+ prefix = 'http://'
+ }
+ const labels = host.split('.')
+ ok =
+ (!m.index || whitespace(c) || punctuation(c)) &&
+ (www || !prefix) &&
+ !punctuation(host.charCodeAt(0)) &&
+ labels.length > 1 &&
+ !badLabel(labels.at(-1)) &&
+ !badLabel(labels.at(-2))
+ if (ok) {
+ add(
+ scheme.slice(0, -2).toLowerCase(),
+ index,
+ index + scheme.length + trim(host + rest).length,
+ prefix,
+ )
+ }
+ } else if (search === XMPP) {
+ ok &&= !(rest && (!/[A-Z]$/i.test(rest) || run[m.index + whole.length] === '@'))
+ if (ok)
+ add('xmpp:', index, index + whole.length)
+ } else if (search === MAILTO) {
+ if (ok)
+ add('mailto:', index, index + whole.length)
+ } else {
+ ok = ok && email
+ if (ok)
+ add('mailto:', index, index + whole.length, 'mailto:')
+ }
+ if (!ok)
+ search.lastIndex = m.index + 1
+ else if (first)
+ return links
+ }
+ }
+ }
+ return links.sort((a, b) => a.index - b.index)
+}
+
+/** The `http://` or `https://` link at the start of `value`, if there's one. */
+function findAtStart(value: string): Link | undefined {
+ text = value
+ n = value.length
+ if ((at(0) | 32) !== 104)
+ return
+ const found = protocol(0)
+ if (!found)
+ return
+ const raw = value.slice(0, found[1])
+ return { schema: found[0], index: 0, lastIndex: found[1], text: raw, url: raw }
+}
+
+// What every link has: `www.`, `://`, or an address character before an `@`.
+const PRETEST = /www\.|:\/\/|[\w+.-]@/i
+
+export interface GfmLinkifyOptions {
+ /** Link `www.` URLs. Default `true`. */
+ fuzzyLink?: boolean
+ /** Link emails without `mailto:`. Default `true`. */
+ fuzzyEmail?: boolean
+}
+
+export interface GfmLinkifyMatch extends Link {
+ /** The link as written, the same as `text`. */
+ raw: string
+}
+
+function toMatch({ schema, index, lastIndex, text, url }: Link): GfmLinkifyMatch {
+ return { schema, index, lastIndex, raw: text, text, url }
+}
+
+/**
+ * Finds links the way GitHub does, with the methods markdown-exit calls on
+ * `md.linkify`. It has no TLD list and no custom schemas, so `tlds` and `add`
+ * throw.
+ */
+export class GfmLinkify {
+ private fuzzyLink = true
+ private fuzzyEmail = true
+ // markdown-exit tests a text and then matches it, so the links of the last
+ // text are kept for the match.
+ private last: { text: string, links: Link[] } | undefined
+
+ constructor(options?: GfmLinkifyOptions) {
+ if (options)
+ this.set(options)
+ }
+
+ set(options: GfmLinkifyOptions): this {
+ this.fuzzyLink = options.fuzzyLink ?? this.fuzzyLink
+ this.fuzzyEmail = options.fuzzyEmail ?? this.fuzzyEmail
+ this.last = undefined
+ return this
+ }
+
+ test(text: string): boolean {
+ if (this.last?.text === text)
+ return this.last.links.length > 0
+ return PRETEST.test(text) && find(text, this.fuzzyLink, this.fuzzyEmail, true).length > 0
+ }
+
+ match(text: string): GfmLinkifyMatch[] | null {
+ if (this.last?.text !== text)
+ this.last = { text, links: PRETEST.test(text) ? find(text, this.fuzzyLink, this.fuzzyEmail) : [] }
+ return this.last.links.length ? this.last.links.map(toMatch) : null
+ }
+
+ matchAtStart(text: string): GfmLinkifyMatch | null {
+ const link = findAtStart(text)
+ return link ? toMatch(link) : null
+ }
+
+ tlds(): never {
+ throw new Error('GfmLinkify has no TLD list: GFM links only `www.`, `http(s)://` and email addresses.')
+ }
+
+ add(): never {
+ throw new Error('GfmLinkify has no custom schemas: GFM links only `www.`, `http(s)://` and email addresses.')
+ }
+}
+
+/**
+ * Plugin: links URLs and emails in text the way GitHub does.
+ *
+ * ```ts
+ * import { createMarkdownExit } from 'markdown-exit/core'
+ * import linkifyGfm from 'markdown-exit/linkify-gfm'
+ *
+ * const md = createMarkdownExit().use(linkifyGfm)
+ * ```
+ */
+export default function linkifyGfm(md: MarkdownExit, options?: GfmLinkifyOptions): void {
+ md.linkify = new GfmLinkify(options) as unknown as LinkifyIt
+ md.set({ linkify: true })
+}
diff --git a/packages/markdown-exit/tests/linkify-gfm.test.ts b/packages/markdown-exit/tests/linkify-gfm.test.ts
new file mode 100644
index 0000000..d64e970
--- /dev/null
+++ b/packages/markdown-exit/tests/linkify-gfm.test.ts
@@ -0,0 +1,82 @@
+import type { Rollup } from 'vite'
+import { fileURLToPath } from 'node:url'
+import { build } from 'vite'
+import { assert, describe, it } from 'vitest'
+import MarkdownExit from '../src/index.core'
+import linkifyGfm, { GfmLinkify } from '../src/linkify-gfm'
+
+const md = MarkdownExit().use(linkifyGfm)
+
+// The autolink examples of the GFM spec 0.29, https://github.github.com/gfm/#autolinks-extension-
+const spec: [string, string][] = [
+ ['www.commonmark.org', 'www.commonmark.org
\n'],
+ ['Visit www.commonmark.org/help for more information.', 'Visit www.commonmark.org/help for more information.
\n'],
+ ['Visit www.commonmark.org.\n\nVisit www.commonmark.org/a.b.', 'Visit www.commonmark.org.
\nVisit www.commonmark.org/a.b.
\n'],
+ ['www.google.com/search?q=Markup+(business)\n\nwww.google.com/search?q=Markup+(business)))\n\n(www.google.com/search?q=Markup+(business))\n\n(www.google.com/search?q=Markup+(business)', 'www.google.com/search?q=Markup+(business)
\nwww.google.com/search?q=Markup+(business)))
\n(www.google.com/search?q=Markup+(business))
\n(www.google.com/search?q=Markup+(business)
\n'],
+ ['www.google.com/search?q=(business))+ok', 'www.google.com/search?q=(business))+ok
\n'],
+ ['www.google.com/search?q=commonmark&hl=en\n\nwww.google.com/search?q=commonmark&hl;', 'www.google.com/search?q=commonmark&hl=en
\nwww.google.com/search?q=commonmark&hl;
\n'],
+ ['www.commonmark.org/hewww.commonmark.org/he<lp
\n'],
+ ['foo@bar.baz', 'foo@bar.baz
\n'],
+ ['hello@mail+xyz.example isn\'t valid, but hello+xyz@mail.example is.', 'hello@mail+xyz.example isn\'t valid, but hello+xyz@mail.example is.
\n'],
+ ['a.b-c_d@a.b\n\na.b-c_d@a.b.\n\na.b-c_d@a.b-\n\na.b-c_d@a.b_', 'a.b-c_d@a.b
\na.b-c_d@a.b.
\na.b-c_d@a.b-
\na.b-c_d@a.b_
\n'],
+]
+
+describe('markdown-exit/linkify-gfm', () => {
+ it.each(spec)('links GFM spec example %j', (src, html) => {
+ assert.strictEqual(md.render(src), html)
+ })
+
+ it('links http(s):// but not ftp://, the same as remark-gfm', () => {
+ assert.strictEqual(
+ md.render('(Visit https://encrypted.google.com/search?q=Markup+(business))\n\nftp://foo.bar.baz.'),
+ '(Visit https://encrypted.google.com/search?q=Markup+(business))
\nftp://foo.bar.baz.
\n',
+ )
+ })
+
+ it('leaves bare domains and mentions as text', () => {
+ assert.strictEqual(md.render('see hackmd.io/@x/abc cc @alice'), 'see hackmd.io/@x/abc cc @alice
\n')
+ })
+
+ it('reads fuzzyLink and fuzzyEmail', () => {
+ const urls = (linkify: GfmLinkify) => linkify.match('www.a.com b@c.de mailto:e@f.gh https://i.jk')?.map(m => m.url)
+ assert.deepEqual(urls(new GfmLinkify()), ['http://www.a.com', 'mailto:b@c.de', 'mailto:e@f.gh', 'https://i.jk'])
+ assert.deepEqual(urls(new GfmLinkify({ fuzzyLink: false })), ['mailto:b@c.de', 'mailto:e@f.gh', 'https://i.jk'])
+ assert.deepEqual(urls(new GfmLinkify().set({ fuzzyEmail: false })), ['http://www.a.com', 'mailto:e@f.gh', 'https://i.jk'])
+ })
+
+ it('returns linkify-it\'s match fields', () => {
+ const linkify = new GfmLinkify()
+ assert.isTrue(linkify.test('see www.example.com.'))
+ assert.deepEqual(linkify.match('see www.example.com.'), [
+ { schema: '', index: 4, lastIndex: 19, raw: 'www.example.com', text: 'www.example.com', url: 'http://www.example.com' },
+ ])
+ assert.isNull(linkify.match('@alice see you'))
+ assert.deepEqual(linkify.matchAtStart('https://a.com/b_c_ and more'), {
+ schema: 'https:',
+ index: 0,
+ lastIndex: 17,
+ raw: 'https://a.com/b_c',
+ text: 'https://a.com/b_c',
+ url: 'https://a.com/b_c',
+ })
+ assert.isNull(linkify.matchAtStart('www.a.com'))
+ })
+
+ it('throws on tlds and add', () => {
+ assert.throws(() => new GfmLinkify().tlds(), /TLD/)
+ assert.throws(() => new GfmLinkify().add(), /schemas/)
+ })
+
+ it('does not bundle linkify-it', async () => {
+ const result = await build({
+ configFile: false,
+ logLevel: 'silent',
+ build: {
+ write: false,
+ lib: { entry: fileURLToPath(new URL('../src/linkify-gfm.ts', import.meta.url)), formats: ['es'] },
+ rollupOptions: { external: id => !id.startsWith('.') && !id.startsWith('/') },
+ },
+ }) as Rollup.RollupOutput[]
+ assert.notInclude(result[0].output.flatMap(chunk => chunk.type === 'chunk' ? chunk.imports : []), 'linkify-it')
+ })
+})
diff --git a/packages/markdown-exit/tsdown.config.ts b/packages/markdown-exit/tsdown.config.ts
index 8fbf384..e447ba1 100644
--- a/packages/markdown-exit/tsdown.config.ts
+++ b/packages/markdown-exit/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
export default defineConfig([
{
- entry: { index: './src/index.ts', core: './src/index.core.ts' },
+ entry: { 'index': './src/index.ts', 'core': './src/index.core.ts', 'linkify-gfm': './src/linkify-gfm.ts' },
platform: 'neutral',
dts: true,
},