g1t/apps/web/app/lib/markdown-plugins.ts
| 1 | /** |
| 2 | * g1t's additions to GitHub flavoured markdown. They run on the HTML tree |
| 3 | * after it has been sanitized, so what they add is trusted and what the |
| 4 | * author wrote never is. |
| 5 | */ |
| 6 | |
| 7 | type Text = { type: "text"; value: string }; |
| 8 | type Element = { |
| 9 | type: "element"; |
| 10 | tagName: string; |
| 11 | properties: Record<string, unknown>; |
| 12 | children: Node[]; |
| 13 | }; |
| 14 | /** A node of the HTML tree, loosely: only what these plugins read. */ |
| 15 | type Node = { type: string; value?: string; tagName?: string; properties?: Record<string, unknown>; children?: Node[] }; |
| 16 | |
| 17 | /** The repository a document belongs to, so `#12` can name its issues. */ |
| 18 | export type MarkdownRepo = { namespace: string; name: string }; |
| 19 | |
| 20 | /** The repository a site path like `/acme/web` names. */ |
| 21 | export function repoAt(base?: string): MarkdownRepo | undefined { |
| 22 | const [namespace, name] = (base ?? "").split("/").filter(Boolean); |
| 23 | return namespace && name ? { namespace, name } : undefined; |
| 24 | } |
| 25 | |
| 26 | export const ALERTS = ["note", "tip", "important", "warning", "caution"] as const; |
| 27 | export type AlertKind = (typeof ALERTS)[number]; |
| 28 | |
| 29 | const ALERT_MARKER = /^\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*\n?/i; |
| 30 | |
| 31 | function isElement(node: Node, tag?: string): node is Element { |
| 32 | return node.type === "element" && (tag == null || (node as Element).tagName === tag); |
| 33 | } |
| 34 | |
| 35 | /** |
| 36 | * GitHub's alerts: a quote that starts with `[!NOTE]`, `[!TIP]`, |
| 37 | * `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` becomes a callout. |
| 38 | */ |
| 39 | export function rehypeAlerts() { |
| 40 | return (tree: Node) => { |
| 41 | const walk = (node: Node) => { |
| 42 | for (const child of node.children ?? []) { |
| 43 | if (isElement(child, "blockquote")) { |
| 44 | const first = child.children.find((c): c is Element => isElement(c, "p")); |
| 45 | const text = first?.children[0]; |
| 46 | const match = text?.type === "text" ? ALERT_MARKER.exec((text as Text).value) : null; |
| 47 | if (first && text && match) { |
| 48 | (text as Text).value = (text as Text).value.slice(match[0].length); |
| 49 | // A marker on a line of its own leaves an empty paragraph behind. |
| 50 | if (first.children.length === 1 && !(text as Text).value.trim()) { |
| 51 | child.children = child.children.filter((c) => c !== first); |
| 52 | } |
| 53 | child.properties = { ...child.properties, dataAlert: match[1]!.toLowerCase() }; |
| 54 | } |
| 55 | } |
| 56 | walk(child); |
| 57 | } |
| 58 | }; |
| 59 | walk(tree); |
| 60 | }; |
| 61 | } |
| 62 | |
| 63 | /** `owner/repo#12`, `#12`, `@name` and commit hashes, in one pass. */ |
| 64 | const REFERENCE = |
| 65 | /(?<![\w/@#])(?:([a-z0-9][a-z0-9-]*\/[a-z0-9._-]+)#(\d+)|#(\d+)|@([a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38})|([0-9a-f]{7,40}))(?![\w-])/gi; |
| 66 | |
| 67 | function link(href: string, text: string, kind: string): Element { |
| 68 | return { |
| 69 | type: "element", |
| 70 | tagName: "a", |
| 71 | properties: { href, dataRef: kind }, |
| 72 | children: [{ type: "text", value: text }], |
| 73 | }; |
| 74 | } |
| 75 | |
| 76 | /** |
| 77 | * Links what a forge's text refers to: `#12` to an issue or pull request |
| 78 | * in this repository (the issue page sends a pull request's number on to |
| 79 | * it), `owner/repo#12` to one elsewhere, `@name` to a person or workspace, |
| 80 | * and a commit hash to its commit. Nothing inside code or a link changes. |
| 81 | */ |
| 82 | export function rehypeReferences(options: { repo?: MarkdownRepo }) { |
| 83 | const { repo } = options; |
| 84 | return (tree: Node) => { |
| 85 | const walk = (node: Node) => { |
| 86 | const children = node.children; |
| 87 | if (!children) return; |
| 88 | for (let index = 0; index < children.length; index++) { |
| 89 | const child = children[index]!; |
| 90 | if (isElement(child)) { |
| 91 | if (child.tagName === "a" || child.tagName === "code" || child.tagName === "pre") continue; |
| 92 | walk(child); |
| 93 | continue; |
| 94 | } |
| 95 | if (child.type !== "text") continue; |
| 96 | const value = (child as Text).value; |
| 97 | const parts: Node[] = []; |
| 98 | let last = 0; |
| 99 | for (const match of value.matchAll(REFERENCE)) { |
| 100 | const [whole, other, otherNumber, number, name, hash] = match; |
| 101 | let replacement: Element | null = null; |
| 102 | if (other && otherNumber) { |
| 103 | replacement = link(`/${other}/issues/${otherNumber}`, whole, "issue"); |
| 104 | } else if (number && repo) { |
| 105 | replacement = link(`/${repo.namespace}/${repo.name}/issues/${number}`, whole, "issue"); |
| 106 | } else if (name) { |
| 107 | replacement = link(`/${name.toLowerCase()}`, whole, "mention"); |
| 108 | } else if (hash && repo && /\d/.test(hash) && /[a-f]/i.test(hash)) { |
| 109 | replacement = link(`/${repo.namespace}/${repo.name}/commit/${hash}`, hash.slice(0, 7), "commit"); |
| 110 | } |
| 111 | if (!replacement) continue; |
| 112 | if (match.index! > last) parts.push({ type: "text", value: value.slice(last, match.index) }); |
| 113 | parts.push(replacement); |
| 114 | last = match.index! + whole.length; |
| 115 | } |
| 116 | if (parts.length === 0) continue; |
| 117 | if (last < value.length) parts.push({ type: "text", value: value.slice(last) }); |
| 118 | children.splice(index, 1, ...parts); |
| 119 | index += parts.length - 1; |
| 120 | } |
| 121 | }; |
| 122 | walk(tree); |
| 123 | }; |
| 124 | } |