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.

\n

Visit 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)

\n

www.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

\n

www.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

\n

a.b-c_d@a.b.

\n

a.b-c_d@a.b-

\n

a.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))

\n

ftp://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, },