// The pages' links, written to read in the repository, made the site's: // a link to a file the site makes a page of goes to that page, any other // to the file in the repository. A link to a file or heading that is not // there fails the build, so a renamed page or section is caught where it // is linked. In the specification, which names its pages as code // (`LIMITS.md`) rather than linking them, each such name is made a link. // A method named as code (`createSession`, or its NSID) links to its entry // in the methods reference, the first time in each section, so a page that // names it often is not a page of links. And a link to a page of the site // that reads as the file's name reads as the page's title instead: what // the reader sees in the sidebar and at the top of the page. import { existsSync, readFileSync, statSync } from 'node:fs' import { join, posix } from 'node:path' import { methodNamed, pageAt, pages, REPO, root, title, url } from './content.mjs' const text = (node) => (node.value ?? '') + (node.children ?? []).map(text).join('') const titles = new Map() /** The title of the site's page made from `source`. */ function titleOf(source) { if (!titles.has(source)) titles.set(source, title(readFileSync(join(root, source), 'utf8'), source)) return titles.get(source) } const walk = (node, visit, parent) => { visit(node, parent) for (const child of node.children ?? []) walk(child, visit, node) } /** A heading's anchor, as GitHub and the site make it. */ const slug = (s) => s .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') .trim() .toLowerCase() .replace(/[^\p{L}\p{N}_\- ]/gu, '') .replaceAll(' ', '-') const anchorsOf = new Map() /** The anchors of a Markdown file's headings, outside its code blocks. */ function anchors(path) { if (!anchorsOf.has(path)) { const seen = new Map() const out = new Set() let fenced = false for (const line of readFileSync(join(root, path), 'utf8').split('\n')) { if (line.startsWith('```')) fenced = !fenced const m = !fenced && line.match(/^#{1,6}\s+(.*)/) if (!m) continue const s = slug(m[1]) const n = seen.get(s) ?? 0 seen.set(s, n + 1) out.add(n ? `${s}-${n}` : s) } anchorsOf.set(path, out) } return anchorsOf.get(path) } /** The repository file a relative link written in `source` names, or null for any other link. */ const targetOf = (source, link) => { if (/^[a-z]+:|^\//.test(link)) return null const path = link.split('#')[0] return path ? posix.normalize(posix.join(posix.dirname(source), path)).replace(/\/$/, '') : source } /** Where a link written in `source` lands: a page of the site, or a file in the repository. */ function resolve(source, link) { const target = targetOf(source, link) if (target === null) return link const [path, anchor] = link.split('#') if (!existsSync(join(root, target))) throw new Error(`${source}: a link to ${path}, which is not there`) if (anchor && target.endsWith('.md') && !anchors(target).has(anchor)) throw new Error(`${source}: a link to #${anchor}, no heading of ${target}`) const hash = anchor ? `#${anchor}` : '' const page = pages().find((p) => p.source === target) if (page) return url(page.slug) + hash const away = upstream(target) if (away) return away.url + hash const kind = statSync(join(root, target)).isDirectory() ? 'tree' : 'blob' return `${REPO}/${kind}/main/${target}${hash}` } /** The MCP revision `spec/mcp/` holds, as its schema names it. */ const MCP_REVISION = readFileSync(join(root, 'spec/mcp/schema.ts'), 'utf8').match( /LATEST_PROTOCOL_VERSION = "([^"]+)"/, )[1] /** A vendored page's title: its MDX header's, or its frontmatter's, or its first heading's. */ const vendoredTitle = (path) => { const t = readFileSync(join(root, path), 'utf8') return (t.match(/^\s*title:\s*'([^']+)'/m) ?? t.match(/^title:\s*(.+)$/m) ?? t.match(/^# (.+)$/m))?.[1].trim() } /** * Where a spec the repository keeps a copy of is published, and how to name * it: atproto's on atproto.com, the RFCs on rfc-editor.org, the draft on the * IETF's datatracker, MCP's on modelcontextprotocol.io. The copies are the * spec's to build from; the reader of the site is better served by the * published page. Null for a file published nowhere else. */ function upstream(target) { let m if ((m = target.match(/^spec\/atproto\/([\w-]+)\.md$/))) return { url: `https://atproto.com/specs/${m[1]}`, text: `atproto's ${vendoredTitle(target)} spec` } if ((m = target.match(/^spec\/rfc\/rfc(\d+)\.txt$/))) return { url: `https://www.rfc-editor.org/rfc/rfc${m[1]}`, text: `RFC ${m[1]}` } if (target === 'spec/rfc/draft-client-id-metadata-document.txt') return { url: 'https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/', text: 'the client ID metadata document draft', } if ((m = target.match(/^spec\/mcp\/(?:legacy\/([\d-]+)\/)?([\w/-]*?)(?:\/index)?(?:\.md)?\/?$/))) { if (target.endsWith('LICENSE') || target.endsWith('.json') || target.endsWith('.ts')) return null const page = m[2] ? `/${m[2]}` : '' const file = statSync(join(root, target)).isDirectory() ? join(target, 'index.md') : target const name = existsSync(join(root, file)) ? vendoredTitle(file) : null return { url: `https://modelcontextprotocol.io/specification/${m[1] ?? MCP_REVISION}${page}`, text: name ? `MCP's ${name} spec${m[1] ? ` (${m[1]})` : ''}` : null, } } return null } /** * A link's words, when they are only the name of the file it goes to: the * title of the site's page made from it, or the name of the published spec * it is a copy of. */ function titleFor(source, link, words) { const target = targetOf(source, link) if (target === null) return null const path = link.split('#')[0] if (![path, target, posix.basename(target)].includes(words.trim())) return null if (pages().some((p) => p.source === target && !p.generated)) return titleOf(target) return upstream(target)?.text ?? null } export function remarkLinks() { return (tree, file) => { const page = pageAt(file.path) if (!page) throw new Error(`${file.path}: no page of the site`) const spec = page.source.startsWith('spec/') const methodsPage = url('reference/methods') let linked = new Set() walk(tree, (node, parent) => { if (node.type === 'heading') linked = new Set() // The spec heads a table's column of what each row is "Is"; a reader // of the site looks for "Description". if (node.type === 'table') { const head = node.children[0]?.children ?? [] for (const cell of head) if (cell.children.length === 1 && cell.children[0].type === 'text' && cell.children[0].value === 'Is') cell.children[0].value = 'Description' } if (node.type === 'link') { const named = titleFor(page.source, node.url, text(node)) if (named) node.children = [{ type: 'text', value: named }] node.url = resolve(page.source, node.url) } else if (node.type === 'definition') node.url = resolve(page.source, node.url) else if ( spec && node.type === 'inlineCode' && parent?.type !== 'link' && /^[\w./-]+(\.md|\.txt|\/)$/.test(node.value) && existsSync(join(root, posix.join(posix.dirname(page.source), node.value))) ) { const named = titleFor(page.source, node.value, node.value) const shown = named ? { type: 'text', value: named } : { ...node } node.type = 'link' node.url = resolve(page.source, node.value) node.children = [shown] delete node.value } else if ( node.type === 'inlineCode' && parent?.type !== 'link' && parent?.type !== 'heading' && page.source !== 'spec/.methods.md' ) { const id = methodNamed(node.value, page.source) if (!id || linked.has(id)) return linked.add(id) node.children = [{ ...node }] node.type = 'link' node.url = `${methodsPage}#${slug(id)}` delete node.value } }) } }