@escape-game-over/atlas 0.1.1

package/src/llms.ts

@@ -0,0 +1,160 @@
+import type { GeneratedFile } from "./file.ts";
+import { type HttpsUrl, joinUrl } from "./url.ts";
+
+/**
+ * One link in an `llms.txt` section.
+ *
+ * `description` is optional because the format tolerates a bare link, but a list
+ * of titles is barely more use to a model than the sitemap it already has — the
+ * sentence is the part that says what the page is *for*.
+ */
+export interface LlmsItem {
+    readonly name: string;
+    readonly url: HttpsUrl;
+    readonly description?: string;
+}
+
+/**
+ * One `##` section: a heading, optional prose, and a list of links.
+ *
+ * Both halves are optional so a section can be pure prose — opening hours, an
+ * address, a phone number — which is a large part of why the file exists and is
+ * exactly the kind of thing lib cannot derive.
+ */
+export interface LlmsSection {
+    readonly heading: string;
+    /**
+     * Makes the heading itself a link — for a section whose pages sit under an
+     * index page, so that page is named once instead of appearing both as a
+     * heading and as an entry in some other list.
+     */
+    readonly url?: HttpsUrl;
+    /** Free markdown, rendered under the heading and above the links. */
+    readonly body?: string;
+    readonly items?: readonly LlmsItem[];
+}
+
+/**
+ * Declaring this on a site says it publishes an `llms.txt`.
+ *
+ * That is what puts `<link rel="describedby">` in every page's head, so the
+ * declaration is the switch rather than a second flag: a link to a file that was
+ * never generated is worse than no link, and lib cannot tell from `metaFor`
+ * whether `site.llms()` was called somewhere.
+ */
+export interface LlmsConfig {
+    /** Filename it is served under. Defaults to `llms.txt`. */
+    readonly name?: string;
+}
+
+export interface LlmsInput {
+    readonly name: string;
+    readonly siteUrl: HttpsUrl;
+    /** `# ` heading — the site's own name. */
+    readonly title: string;
+    /** The `>` block under the title: one or two sentences on what this site is. */
+    readonly summary?: string;
+    /** Absolute URL of the sitemap, advertised the way `robots.txt` does. */
+    readonly sitemap: string;
+    /**
+     * The language the links are written in, and the others that exist.
+     *
+     * Stated rather than implied: every URL in the file is in one language, and
+     * a model that cannot tell which one — or that the others exist — will read
+     * the site as though it were monolingual.
+     */
+    readonly language: { readonly tag: string; readonly url: HttpsUrl };
+    readonly otherLanguages?: readonly {
+        readonly tag: string;
+        readonly url: HttpsUrl;
+    }[];
+    readonly sections: readonly LlmsSection[];
+}
+
+/**
+ * Renders `llms.txt` — what `robots.txt` is for crawlers, for readers that
+ * arrive wanting the content rather than the markup.
+ *
+ * Markdown, and deliberately small: the file competes for a context window, so
+ * it is a map of the site rather than a copy of it.
+ *
+ * Structure follows the proposal at https://llmstxt.org — an `#` title, a `>`
+ * summary block, then `##` sections of `- [name](url): description`.
+ *
+ * Two things there are not done here. The proposal also suggests a clean
+ * markdown copy of every *page* at `page.md`, advertised with
+ * `rel="alternate" type="text/markdown"`; lib generates no such copies, so it
+ * emits no such link. The companion `rel="describedby"` — which points at this
+ * file — is emitted, from `meta/`.
+ */
+export function buildLlms(input: LlmsInput): GeneratedFile {
+    const lines: string[] = [`# ${input.title}`, ""];
+
+    if (input.summary !== undefined) {
+        lines.push(`> ${input.summary}`, "");
+    }
+
+    lines.push(`> Sitemap: ${input.sitemap}`);
+    lines.push(`> Language: ${input.language.tag} (${input.language.url})`);
+    for (const other of input.otherLanguages ?? []) {
+        lines.push(`> Also in: ${other.tag} (${other.url})`);
+    }
+    lines.push("");
+
+    // Which language the links are in, and how to get to the others — stated
+    // only when there *are* others.
+    //
+    // Not "swap the prefix": a slug is translated too, so the Greek `/about-us`
+    // is `/el-GR/sxetika-me-emas` and a reader told to substitute the prefix
+    // would construct a URL that 404s. The sitemap is where that mapping
+    // actually lives, one `xhtml:link` per page per language, so this points at
+    // it rather than describing a rule that does not hold.
+    if (input.otherLanguages !== undefined && input.otherLanguages.length > 0) {
+        lines.push(
+            `Every URL below is the ${input.language.tag} version. Other languages translate their slugs, so the same page is not this URL with a different prefix — the sitemap lists each page in every language.`,
+            ""
+        );
+    }
+
+    for (const section of input.sections) {
+        // A heading with nothing under it says a category exists and is empty,
+        // which is worse than not mentioning it: the file is a map, and a
+        // labelled blank is a gap a reader has to interpret.
+        //
+        // Skipped here rather than by each caller, because both kinds of
+        // section can arrive empty. `siteFor`'s derived "Pages" holds whatever
+        // is not nested under a prefix, and a site whose every route sits in a
+        // family leaves it with none; a project's own `sections` are a public
+        // slot and can be handed anything. One rule, at the point of writing.
+        //
+        // `body` counts as content — a section of pure prose is the reason both
+        // halves are optional, and an address under a heading is a real entry
+        // with no links in it.
+        const empty =
+            section.body === undefined && (section.items ?? []).length === 0;
+        if (empty) continue;
+
+        lines.push(
+            section.url === undefined
+                ? `## ${section.heading}`
+                : `## [${section.heading}](${section.url})`,
+            ""
+        );
+        if (section.body !== undefined) {
+            lines.push(section.body.trim(), "");
+        }
+        for (const item of section.items ?? []) {
+            const description =
+                item.description === undefined ? "" : `: ${item.description}`;
+            lines.push(`- [${item.name}](${item.url})${description}`);
+        }
+        lines.push("");
+    }
+
+    return {
+        name: input.name,
+        url: joinUrl(input.siteUrl, `/${input.name}`),
+        body: `${lines.join("\n").trimEnd()}\n`,
+        contentType: "text/markdown; charset=utf-8",
+    };
+}

package/src/meta/content.ts

@@ -0,0 +1,190 @@
+import type { ImageAsset } from "../image.ts";
+import type {
+    BusinessId,
+    JsonLdNode,
+    OrganizationId,
+} from "../jsonld/index.ts";
+import type { IsoDate } from "../types.ts";
+import type { RobotsPolicy } from "./robots.ts";
+import type { ShareImage } from "./share-image.ts";
+
+/**
+ * What only a consumer can supply: a page's words, and what kind of thing it is.
+ */
+
+/**
+ * What kind of thing a page represents, for `og:type`.
+ *
+ * The whole vocabulary Open Graph defines, and a union for the reason
+ * `RobotsDirective` is one: it is small and closed, and a value outside it is
+ * not an error anywhere — a scraper that does not recognise `og:type` falls
+ * back to `website` and renders a perfectly ordinary card. So `"artcile"` costs
+ * you the article treatment and looks exactly like success.
+ *
+ * `website` is the default and the right answer for most pages. `article` is
+ * the one that earns anything extra: it is what tells a scraper this is a dated
+ * piece of writing rather than a section of the site.
+ *
+ * Reference: <https://ogp.me/#types>
+ */
+export type OpenGraphType =
+    | "website"
+    | "article"
+    | "book"
+    | "profile"
+    | `music.${"song" | "album" | "playlist" | "radio_station"}`
+    | `video.${"movie" | "episode" | "tv_show" | "other"}`;
+
+/**
+ * A page that is a dated piece of writing, said once.
+ *
+ * The half of `ArticleInput` a page actually knows. Everything else lib already
+ * holds and fills in: the URL is the canonical, the description is the page's,
+ * the image is the share image it has just resolved to an absolute URL, and the
+ * headline defaults to the title. Asking a view for those again would be asking
+ * it to repeat what it just handed over — and to repeat it *correctly*, which is
+ * the part that eventually fails.
+ *
+ * Supplying this is what emits the `Article` node, `og:type: article` and the
+ * `article:*` properties together. They are three statements of one fact, and a
+ * page that could make them separately is a page that could make two of them.
+ * That is why `MetaContent.type` cannot be set to `"article"`: saying a page is
+ * an article without saying when it was published is the half-statement this
+ * exists to prevent, and it is also the half that carries no benefit — the date
+ * is the whole reason the type is worth claiming.
+ */
+export interface ArticleContent {
+    /**
+     * The headline, where it differs from the page title.
+     *
+     * Usually it does not, which is why this is optional. Worth setting when
+     * the `<title>` carries something the headline should not — a site name, a
+     * section — since Google reads this as the article's own name.
+     */
+    readonly headline?: string;
+    /** When it was published. The field that makes the whole thing worth it. */
+    readonly datePublished: IsoDate;
+    /** When it last changed, if it has. See `ArticleInput.dateModified`. */
+    readonly dateModified?: IsoDate;
+    /** Who wrote it, as an `@id` — the venue, or the brand. */
+    readonly author?: OrganizationId | BusinessId;
+    /** Who published it. Usually the same node as `author` — see `ArticleInput`. */
+    readonly publisher?: OrganizationId | BusinessId;
+    /**
+     * What it is about. One `article:tag` each, and `keywords` on the node.
+     *
+     * No `article:section`: that names the one part of a publication a piece
+     * lives in, and a site with a single feed would repeat its own URL on every
+     * post. It becomes worth having when the feed splits.
+     */
+    readonly tags?: readonly string[];
+    /** Which flavour of article. Defaults to `Article`. */
+    readonly kind?: "Article" | "NewsArticle" | "BlogPosting";
+    /**
+     * The post's own photograph, at each ratio a result may render it in.
+     *
+     * The one thing lib cannot derive from what it already holds. Everything
+     * else about this node comes from the head it just built — but the share
+     * image is a single 1200x630 card, often with type burnt into it, and
+     * Google asks for something else: *"multiple high-resolution images with
+     * the following aspect ratios: 16x9, 4x3, and 1x1"*. A result renders the
+     * picture in whichever shape its surface uses, so supplying one ratio
+     * leaves the other two cropped by rules nobody here controls.
+     *
+     * Pass `await photoSet(source)` from the package's `astro/images`, which cuts
+     * exactly those three from one import. Omit it and the node falls back to
+     * the share image, which is a worse picture and a real one — the same
+     * trade `llms.txt` makes when nobody supplies `describe`.
+     */
+    readonly images?: readonly ImageAsset[];
+}
+
+/**
+ * What kind of page this is: an ordinary one, or an article.
+ *
+ * A union rather than two optional fields, so the pair cannot both be set. They
+ * answer the same question — `article` decides `og:type` — and a page that
+ * supplied both would have one of them silently ignored, which is the shape of
+ * mistake this folder keeps removing rather than reporting.
+ *
+ * Both branches allow the fields to be absent, so an ordinary page writes
+ * neither and gets `website`.
+ */
+export type PageKind =
+    | {
+          readonly type?: Exclude<OpenGraphType, "article">;
+          readonly article?: never;
+      }
+    | {
+          readonly type?: never;
+          /**
+           * This page's publication details, if it is a dated piece of writing.
+           *
+           * One field, three outputs — see `ArticleContent`.
+           */
+          readonly article: ArticleContent;
+      };
+
+/** The fields every page has, whatever kind it is. */
+export interface MetaContentBase {
+    readonly title: string;
+    /**
+     * Required: a page without a description leaves search engines and every
+     * share preview to invent one from the body copy.
+     */
+    readonly description: string;
+    /**
+     * Overrides the default `width=device-width, initial-scale=1`, for the rare
+     * page that needs `viewport-fit=cover` or similar.
+     */
+    readonly viewport?: string;
+    /**
+     * What a crawler may do with this page, e.g. `{ index: true, follow: true }`.
+     *
+     * Required, and per page: whether a page should be indexed is a decision,
+     * and leaving the tag off to inherit the crawler's default hides it.
+     * Site-wide crawl rules belong in `robots.txt`, which lib also generates.
+     */
+    readonly robots: RobotsPolicy;
+    /**
+     * This page's share image and its alt text, as one unit.
+     *
+     * Required, and supplied per page rather than looked up from a registry:
+     * routes can be generated dynamically, and a product page's image is part of
+     * the product, not of the route table.
+     */
+    readonly image: ShareImage;
+    /**
+     * Structured-data nodes for this page, added to the same graph as the
+     * breadcrumb.
+     *
+     * A slot for what lib cannot derive. lib knows the route table, so it can
+     * build a breadcrumb; it does not know the business, its address or its
+     * hours, and will not invent them. Nodes are built with the helpers in
+     * `jsonld/`, so this takes shaped data rather than arbitrary JSON.
+     *
+     * Mark up what the page shows. Google requires it outright — content not
+     * visible to a reader is a guidelines violation rather than a free extra
+     * signal — and it is also what decides whether anything else sees it: a
+     * model reading the page gets the rendered text, and a `<script>` block is
+     * what its extractor drops first. A fact that exists only here is a fact
+     * that mostly does not exist. Nothing checks this, because lib builds nodes
+     * and never sees the page they end up on.
+     */
+    readonly jsonLd?: readonly JsonLdNode[];
+}
+
+/**
+ * What a page passes to `metaFor`: its words, its picture, and what kind of
+ * thing it is.
+ *
+ * An intersection rather than one interface because `PageKind` is a union, and
+ * that union is the whole point — see it for why `type` and `article` cannot
+ * both be written.
+ */
+export type MetaContent = MetaContentBase & PageKind;
+
+/** Browser-UI tint. A single colour, or one per `prefers-color-scheme`. */
+export type ThemeColor =
+    | string
+    | { readonly light: string; readonly dark: string };