llms.mjs

Functions

Imports

It imports no other module of this repo. Imported by index.mjs.

Source

1/**
2 * @typedef {object} LlmsLink
3 * @property {string} title
4 * @property {string} url
5 * @property {string} [description]
6 */
7
8/**
9 * @typedef {object} LlmsLinkSection
10 * @property {string} heading
11 * @property {LlmsLink[]} links
12 */
13
14/**
15 * @typedef {object} LlmsProseSection
16 * @property {string} heading
17 * @property {string[]} body paragraphs, kept as written and separated by a blank line
18 */
19
20/** @typedef {LlmsLinkSection | LlmsProseSection} LlmsSection */
21
22/**
23 * The llms.txt skeleton (llmstxt.org): title, a blockquote summary, optional intro paragraphs, then H2 sections of link lists.
24 * A link's title is Markdown link text, so `[` and `]` are escaped; everything else is kept as written, because the titles are
25 * prose and the sites' own files carry quotes and ampersands in them. A section with no links is dropped rather than left a
26 * bare heading. A prose section (`body` in place of `links`) is its heading, a blank line, then its paragraphs as written, for a
27 * file that mixes prose with its lists; one with no paragraphs is dropped the same way.
28 *
29 * @param {{ title: string, summary: string, intro?: string[], sections: LlmsSection[] }} doc
30 * @returns {string}
31 */
32export function llmsDocument(doc) {
33  const blocks = [`# ${doc.title}`, `> ${doc.summary}`, ...(doc.intro ?? [])];
34  for (const section of doc.sections) {
35    if ("body" in section) {
36      if (section.body.length > 0) blocks.push(`## ${section.heading}`, ...section.body);
37    } else if (section.links.length > 0) {
38      blocks.push(`## ${section.heading}\n${section.links.map(llmsLink).join("\n")}`);
39    }
40  }
41  return `${blocks.join("\n\n")}\n`;
42}
43
44/** @param {LlmsLink} link */
45export function llmsLink(link) {
46  // One line per link: a newline in the title or description would end the list item, and a ")" in the URL would end the link.
47  const oneLine = (/** @type {string} */ text) => text.replace(/\s*[\r\n]+\s*/g, " ");
48  const title = oneLine(link.title).replace(/[[\]]/g, (bracket) => "\\" + bracket);
49  const url = link.url.replace(/\)/g, "%29");
50  return `- [${title}](${url})${link.description ? `: ${oneLine(link.description)}` : ""}`;
51}