// The docs site: a page per Markdown file, each written for one reader, rendered into the docs // shell with the site's pages down the left. Every page is also served as its Markdown // (/docs/.md), and /llms.txt lists them all, so agents can read the docs as easily as people. import fs from 'node:fs' import { Marked, type Tokens } from 'marked' import { TURN_MAP_HTML } from './docs-turn.ts' import { COPY_INNER, DOCS_JS_HREF, esc, installCommand, installCommandWindows, LOGO, loginCommand, page, type Page } from './web.ts' const SOURCE = 'https://tangled.org/cameron.stream/languid' export interface DocPage { /** The page's path under /docs; '' is /docs itself. */ slug: string title: string /** Who reads it and what it gets them, in one line: the sidebar's tooltip and llms.txt's entry. */ description: string section: string /** The Markdown, relative to the repo root. */ file: string } export const DOC_PAGES: DocPage[] = [ { slug: '', title: 'Quick start', section: 'Get started', file: 'docs/site/quickstart.md', description: 'Install the CLI, sign in, and talk to your first agent.' }, { slug: 'computers', title: 'Computers', section: 'Get started', file: 'docs/site/computers.md', description: 'Let your agents read files and run commands on your computers, and choose what they may do without asking.' }, { slug: 'models', title: 'Models', section: 'Get started', file: 'docs/site/models.md', description: "Choose an agent's model: Languid's hosted models on your credit, or your own ChatGPT plan, Anthropic key or OpenRouter account." }, { slug: 'agents', title: 'Agents and memory', section: 'Using Languid', file: 'docs/site/agents.md', description: 'What an agent is: threads, memory blocks, pinning, and its instructions.' }, { slug: 'discord', title: 'Discord', section: 'Using Languid', file: 'docs/site/discord.md', description: 'Give an agent a Discord bot and talk to it there.' }, { slug: 'mcp', title: 'Languid MCP', section: 'Using Languid', file: 'docs/site/mcp.md', description: "Use your agents from any MCP client, such as Claude, ChatGPT, Claude Code or your own scripts." }, { slug: 'sites', title: 'Sites', section: 'Using Languid', file: 'docs/site/sites.md', description: 'Let an agent publish a small static website to its own atproto repo.' }, { slug: 'approvals', title: 'Approvals for apps', section: 'Using Languid', file: 'docs/site/approvals.md', description: "Run your agents from your own app, and answer the calls they ask you about." }, { slug: 'evals', title: 'Evals', section: 'Using Languid', file: 'docs/evals.md', description: 'Test an agent before you change it, let it improve itself against cases it can\'t game, and keep every trial as training data.' }, { slug: 'commands', title: 'Commands', section: 'Using Languid', file: 'docs/site/commands.md', description: 'Every languid command an owner uses, and what it does.' }, { slug: 'self-host', title: 'Self-host', section: 'Self-hosting', file: 'docs/hosting.md', description: 'Run your own Languid on Fly.io: the PDS, the service and runners.' }, { slug: 'how-it-works', title: 'How it works', section: 'How it works', file: 'docs/site/how-it-works.md', description: 'How Languid keeps agents on atproto: accounts, Spaces, records and the service.' }, { slug: 'turn', title: 'A turn, step by step', section: 'How it works', file: 'docs/site/turn.md', description: 'What happens between Send and the answer: which machine does each part, what is written where, and what has to stay running.' }, { slug: 'records', title: 'Records', section: 'How it works', file: 'docs/site/records.md', description: "The ai.languid.* records that hold an agent's state, and where each one lives." }, ] const href = (p: DocPage) => (p.slug ? `/docs/${p.slug}` : '/docs') const mdHref = (p: DocPage) => `/docs/${p.slug || 'index'}.md` /** The page at a path under /docs (`/docs`, `/docs/computers`), and whether it asks for the Markdown. */ export function docAt(pathname: string): { doc: DocPage; markdown: boolean } | undefined { const m = /^\/docs(?:\/([a-z-]+?))?(\.md)?\/?$/.exec(pathname) if (!m) return undefined const slug = m[1] === 'index' ? '' : (m[1] ?? '') if (m[2] && !m[1]) return undefined const doc = DOC_PAGES.find((p) => p.slug === slug) return doc && { doc, markdown: !!m[2] } } const sources = new Map() const read = (file: string) => { let s = sources.get(file) if (s === undefined) sources.set(file, (s = fs.readFileSync(new URL(`../${file}`, import.meta.url), 'utf8'))) return s } /** * A page's Markdown, with this service's own commands filled in, and links between files turned * into links that work wherever it's read: other docs pages by their path, repo files on Tangled. */ export function docMarkdown(doc: DocPage, origin: string): string { const fileDir = doc.file.slice(0, doc.file.lastIndexOf('/') + 1) return read(doc.file) .replaceAll('@INSTALL_WINDOWS@', installCommandWindows(origin) ?? `irm ${origin}/install.ps1 | iex`) .replaceAll('@INSTALL@', installCommand(origin) ?? `curl -fsSL ${origin}/install | sh`) .replaceAll('@LOGIN@', loginCommand(origin)) .replaceAll('@SERVICE@', origin) .replace(/\]\((?!https?:|\/|#|mailto:)([^)\s]+)\)/g, (_, target: string) => { const [path, hash] = target.split('#') const file = new URL(path, `file:///${fileDir}`).pathname.slice(1) const page = DOC_PAGES.find((p) => p.file === file) const to = page ? href(page) : `${SOURCE}/blob/main/${file}` return `](${to}${hash ? `#${hash}` : ''})` }) } const slugify = (s: string) => s .toLowerCase() .replace(/<[^>]+>|&[a-z#0-9]+;/g, '') .replace(/[^a-z0-9]+/g, '-') .replace(/^-|-$/g, '') function safeHref(raw: string | null | undefined): string | undefined { if (!raw) return undefined const trimmed = raw.trim() if (/^(?:https?:|mailto:)/i.test(trimmed)) return trimmed if (trimmed.startsWith('/') && !trimmed.startsWith('//') && !trimmed.startsWith('/\\')) return trimmed if (trimmed.startsWith('#')) return trimmed return undefined } /** The Markdown as HTML for the docs shell: ids on headings, copy buttons on one-line commands. */ export function renderDoc(md: string): { html: string; title: string; headings: { id: string; text: string }[] } { let title = '' const headings: { id: string; text: string }[] = [] const marked = new Marked({ gfm: true, renderer: { heading({ tokens, depth }: Tokens.Heading) { const text = this.parser.parseInline(tokens) if (depth === 1) { title ||= text.replace(/<[^>]+>/g, '') return `

${text}

` } const id = slugify(text) if (depth === 2) headings.push({ id, text: text.replace(/<[^>]+>/g, '') }) // already escaped by parseInline return `${text}` }, code({ text, lang }: Tokens.Code) { if ((lang === 'sh' || lang === 'bash') && !text.includes('\n') && !text.includes('#')) return `
${esc(text)}
` return `
${esc(text)}
` }, table(token: Tokens.Table) { const cell = (c: Tokens.TableCell, tag: string) => `<${tag}>${this.parser.parseInline(c.tokens)}` return ( `
${token.header.map((c) => cell(c, 'th')).join('')}` + `${token.rows.map((r) => `${r.map((c) => cell(c, 'td')).join('')}`).join('')}
` ) }, blockquote({ tokens }: Tokens.Blockquote) { return `
${this.parser.parse(tokens)}
` }, html({ text }: Tokens.HTML | Tokens.Tag) { // Pictures drawn in code, where the Markdown marks them; all other raw HTML is escaped. if (text.trim() === '') return TURN_MAP_HTML return esc(text) }, link({ href, title, tokens }: Tokens.Link) { const label = this.parser.parseInline(tokens) const safe = safeHref(href) if (!safe) return label const titleAttr = title ? ` title="${esc(title)}"` : '' return `${label}` }, image({ href, title, text }: Tokens.Image) { const safe = safeHref(href) if (!safe) return esc(text) const titleAttr = title ? ` title="${esc(title)}"` : '' return `${esc(text)}` }, }, }) const html = marked.parse(md, { async: false }) as string return { html, title, headings } } const rendered = new Map>() /** A docs page: the site's pages down the left (this one's sections under it), the page beside them. */ export function docsPage(doc: DocPage, origin: string): Page { const key = `${doc.slug}\n${origin}` let r = rendered.get(key) if (!r) rendered.set(key, (r = renderDoc(docMarkdown(doc, origin)))) const sections = [...new Set(DOC_PAGES.map((p) => p.section))] const list = (current: boolean) => sections .map( (s) => `

${esc(s)}

    ` + DOC_PAGES.filter((p) => p.section === s) .map((p) => p === doc ? `
  • ${esc(p.title)}` + (current && r.headings.length ? `
      ${r.headings.map((h) => `
    • ${h.text}
    • `).join('')}
    ` : '') + `
  • ` : `
  • ${esc(p.title)}
  • `, ) .join('') + `
`, ) .join('') const i = DOC_PAGES.indexOf(doc) const next = DOC_PAGES[i + 1] const path = href(doc) return page( 200, doc.slug ? `${doc.title} · Languid docs` : 'Languid docs', `` + `
${esc(doc.section)} · ${esc(doc.title)}
` + ``, { path, script: true, bodyClass: 'docs', headers: { link: `<${mdHref(doc)}>; rel="alternate"; type="text/markdown"` } }, ) } /** /llms.txt: what Languid is and every docs page, as Markdown links an agent can follow. */ export function llmsTxt(origin: string): string { const sections = [...new Set(DOC_PAGES.map((p) => p.section))] return ( `# Languid\n\n` + `> Stateful agents on the AT Protocol. Each agent is its own atproto account, its memory and conversations are records in a private Space, and its tools run on its owner's own computers.\n\n` + `Every docs page is Markdown at the address below. Source: ${SOURCE}\n\n` + sections .map((s) => `## ${s}\n\n${DOC_PAGES.filter((p) => p.section === s).map((p) => `- [${p.title}](${origin}${mdHref(p)}): ${p.description}`).join('\n')}\n`) .join('\n') ) }