blume 2.0.2 → 2.1.0

package/src/search/documents.ts

@@ -23,7 +23,12 @@ import { HTML_COMMENT } from "../core/sources/normalize.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, PageRecord } from "../core/types.ts";
 import { parseCodeTitle } from "../markdown/code-title.ts";
-import { MARKDOWN_FEATURES, MDX_FEATURES } from "../markdown/features.ts";
+import { directiveSource } from "../markdown/directives.ts";
+import type { DirectiveNode } from "../markdown/directives.ts";
+import {
+  MARKDOWN_BODY_FEATURES,
+  MDX_BODY_FEATURES,
+} from "../markdown/features.ts";
 import { pageFacets } from "./facets.ts";
 
 /** A document indexed by the client-side search providers (Orama, FlexSearch). */
@@ -49,6 +54,10 @@ export interface SearchDocument {
    * Filterable through the MCP tools' `filters` input.
    */
   facets?: Record<string, string>;
+  /** Frontmatter `search.boost`: the page's relevance multiplier, when set. */
+  boost?: number;
+  /** Frontmatter `search.keywords`: extra terms the page is found by. */
+  keywords?: string[];
 }
 
 /**
@@ -72,6 +81,13 @@ export interface SearchRecord {
   version: string;
   /** Single faceting tag (the first frontmatter tag, when present). */
   tag?: string;
+  /**
+   * The page's relevance multiplier, 1 unless `search.boost` sets it: a
+   * ranking attribute every record carries, so the backend can sort by it.
+   */
+  boost: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
 // Tag-shaped only: a name (or closing slash/fragment) right after `<`, and no
@@ -94,7 +110,6 @@ const INLINE_PARENTS = new Set([
   "strong",
   "subscript",
   "superscript",
-  "textDirective",
 ]);
 
 // Nodes that never render as prose: image alt text was never indexed, MDX
@@ -120,9 +135,9 @@ interface Walk {
 
 // Front matter is already off (core/frontmatter.ts) by the time a body gets
 // here, so a body that opens with a `---` divider must read as a thematic
-// break rather than a second front matter block.
-const MD_PARSE = { features: { ...MARKDOWN_FEATURES, frontmatter: false } };
-const MDX_PARSE = { features: { ...MDX_FEATURES, frontmatter: false } };
+// break rather than a second front matter block — as the renderer reads it.
+const MD_PARSE = { features: MARKDOWN_BODY_FEATURES };
+const MDX_PARSE = { features: MDX_BODY_FEATURES };
 
 const parseMdx = (markdown: string): Nodes | undefined => {
   try {
@@ -170,6 +185,25 @@ const collectCode = (
   out.push(node.value, " ");
 };
 
+/**
+ * A text or leaf directive as the page shows it. Blume renders neither (see
+ * `markdown/directives.ts`), and prose is full of text that parses as one —
+ * `16:9`, `og:image` — so the page shows the source the author wrote, and the
+ * index reads the same text rather than dropping the `:name` part.
+ */
+const directiveText = (
+  node: Extract<Nodes, { type: "leafDirective" | "textDirective" }>,
+  walk: Walk
+): string =>
+  directiveSource(
+    // SAFETY: DirectiveNode is a structural subset of Satteri's directive
+    // nodes — a `name`, optional attributes and children, and a position.
+    node as DirectiveNode,
+    node.type === "textDirective" ? ":" : "::",
+    // The walked tree was parsed from this text, so its offsets index into it.
+    walk.downlevel.source
+  );
+
 // Block boundaries separate words; so does an empty inline element (`<br />`,
 // a self-closing icon), which otherwise fuses its neighbors.
 const separatesWords = (node: Extract<Nodes, { children: unknown }>): boolean =>
@@ -223,28 +257,17 @@ const collectText = (node: Nodes, out: string[], walk: Walk): void => {
       out.push(" ");
       return;
     }
-    // Trailing heading markers (`[#custom-id]`, `{#custom-id}`, `[!toc]`,
-    // `[toc]`) are anchor
-
-    // metadata, not prose — strip them so they never pollute the index. Only
-    // a marker that ends the heading's final plain-text child counts,
-    // mirroring the renderer: a heading ending in inline code or an image
-    // keeps its bracketed text on the page (so it stays searchable), and a
-    // heading that is nothing but markers renders them literally.
+    case "textDirective": {
+      out.push(directiveText(node, walk));
+      return;
+    }
+    case "leafDirective": {
+      out.push(directiveText(node, walk), " ");
+      return;
+    }
     case "heading": {
-      const last = node.children.at(-1);
-      const trailing = last?.type === "text" ? last : undefined;
-      const inner: string[] = [];
-      const kept = trailing ? node.children.slice(0, -1) : node.children;
-      for (const child of kept) {
-        collectText(child, inner, walk);
-      }
-      if (trailing) {
-        const stripped = parseHeadingMarkers(trailing.value).text;
-        const literal = stripped === "" && node.children.length === 1;
-        inner.push(literal ? trailing.value : stripped);
-      }
-      out.push(inner.join("").trimEnd(), " ");
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion: a heading's children are walked like any others
+      collectHeading(node, out, walk);
       return;
     }
     default: {
@@ -265,6 +288,35 @@ const collectText = (node: Nodes, out: string[], walk: Walk): void => {
   }
 };
 
+/**
+ * Fold a heading into the accumulator. Trailing heading markers
+ * (`[#custom-id]`, `{#custom-id}`, `[!toc]`, `[toc]`) are anchor metadata,
+ * not prose — strip them so they never pollute the index. Only a marker that
+ * ends the heading's final plain-text child counts, mirroring the renderer: a
+ * heading ending in inline code or an image keeps its bracketed text on the
+ * page (so it stays searchable), and a heading that is nothing but markers
+ * renders them literally.
+ */
+const collectHeading = (
+  node: Extract<Nodes, { type: "heading" }>,
+  out: string[],
+  walk: Walk
+): void => {
+  const last = node.children.at(-1);
+  const trailing = last?.type === "text" ? last : undefined;
+  const inner: string[] = [];
+  const kept = trailing ? node.children.slice(0, -1) : node.children;
+  for (const child of kept) {
+    collectText(child, inner, walk);
+  }
+  if (trailing) {
+    const stripped = parseHeadingMarkers(trailing.value).text;
+    const literal = stripped === "" && node.children.length === 1;
+    inner.push(literal ? trailing.value : stripped);
+  }
+  out.push(inner.join("").trimEnd(), " ");
+};
+
 /**
  * Reduce Markdown/MDX to plain, searchable text: parse (GFM included) and walk
  * the tree instead of regex-stripping the source, so reference-style links,
@@ -373,6 +425,17 @@ const pageBody = async (
   });
 };
 
+/** The ranking a page asks for: its `search.boost` and `search.keywords`. */
+const rankingFields = (
+  search: PageRecord["meta"]["search"] | undefined
+): Pick<SearchDocument, "boost" | "keywords"> => {
+  const { boost, keywords } = search ?? {};
+  return {
+    ...(boost !== undefined && boost !== 1 && { boost }),
+    ...(keywords && keywords.length > 0 && { keywords }),
+  };
+};
+
 /**
  * Build search documents from the content graph. Only indexable pages are
  * included (per the route manifest), and content comes from the source files,
@@ -490,7 +553,7 @@ export const buildSearchDocuments = async (
       if (facets) {
         document.facets = facets;
       }
-      return document;
+      return { ...document, ...rankingFields(page?.meta?.search) };
     })
   );
 };
@@ -498,13 +561,15 @@ export const buildSearchDocuments = async (
 /**
  * Map per-page search documents to the flat record shape hosted backends
  * ingest. One record per page, keyed by route; the first tag becomes the
- * faceting `tag`.
+ * faceting `tag`, and every record carries a `boost` (1 by default).
  */
 export const toSearchRecords = (documents: SearchDocument[]): SearchRecord[] =>
   documents.map((doc) => ({
     _id: doc.route,
+    boost: doc.boost ?? 1,
     content: doc.content,
     description: doc.description,
+    ...(doc.keywords && { keywords: doc.keywords }),
     locale: doc.locale,
     tag: doc.tags?.[0],
     title: doc.title,

package/src/search/orama-index.ts

@@ -31,6 +31,10 @@ export interface OramaDoc {
    * but not indexed, so they ride along on the returned document untouched. */
   breadcrumb?: string[];
   section?: string;
+  /** The page's relevance multiplier (`search.boost`); stored, not indexed. */
+  boost?: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
 const SCHEMA = {
@@ -42,6 +46,7 @@ const SCHEMA = {
   // serves every project's facet keys, with `containsAll` matching a filter
   // set. Derived from `facets` at insert time.
   facetTerms: "enum[]",
+  keywords: "string[]",
   locale: "enum",
   route: "string",
   title: "string",
@@ -52,8 +57,21 @@ const SCHEMA = {
 const toFacetTerms = (facets: Record<string, string>): string[] =>
   Object.entries(facets).map(([key, value]) => `${key}:${value}`);
 
-/** Title and description outrank body text, matching the search dialog. */
-const BOOST = { description: 2, title: 3 };
+/**
+ * Title and description outrank body text, matching the search dialog; a
+ * page's keywords count as much as its title, since its author chose them.
+ */
+const BOOST = { description: 2, keywords: 3, title: 3 };
+
+/** Databases holding a boosted page, which rank by boosted score. */
+const boostedDatabases = new WeakSet<AnyOrama>();
+
+/** A search match as Orama's sort function sees it: id, score, document. */
+type RankedMatch = [unknown, number, OramaDoc];
+
+/** Rank matches by relevance times the page's `search.boost`. */
+const byBoostedScore = (a: RankedMatch, b: RankedMatch): number =>
+  b[1] * (b[2].boost ?? 1) - a[1] * (a[2].boost ?? 1);
 
 /**
  * The script whose text Orama's default tokenizer keeps mostly intact. Its
@@ -322,6 +340,9 @@ export const buildOramaIndex = async (
       doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
     )
   );
+  if (documents.some((doc) => (doc.boost ?? 1) !== 1)) {
+    boostedDatabases.add(db);
+  }
   return db;
 };
 
@@ -391,10 +412,14 @@ export const queryOramaIndex = async (
   if (facetTerms.length > 0) {
     where.facetTerms = { containsAll: facetTerms };
   }
+  // Boosts multiply every match's score before the limit applies (Orama
+  // sorts the whole match set with a sort function), so a boosted page can
+  // rise past matches outside the first page.
   const unfiltered = {
     boost: BOOST,
     limit,
-    properties: ["title", "description", "content"],
+    properties: ["title", "keywords", "description", "content"],
+    ...(boostedDatabases.has(db) && { sortBy: byBoostedScore }),
     term,
   };
   const params =

package/src/search/pagefind-ranking.ts

@@ -0,0 +1,39 @@
+/**
+ * A page's `search.boost` and `search.keywords`, as Pagefind reads them from
+ * the built page. Pagefind has no page-level boost, only element weights, so
+ * the page's body carries its boost as its weight: a boosted page's matches
+ * count for more and it ranks higher. Pagefind damps repeated matches, so the
+ * lift is smaller than the full multiplier: a boost of 5 scored its page about
+ * 1.5 to 2 times higher in testing. A boost past Pagefind's largest weight,
+ * 10, counts as 10.
+ * Keywords go on an empty element as an indexed attribute, found like text
+ * and never shown.
+ */
+
+/** The largest weight Pagefind takes. */
+const MAX_WEIGHT = 10;
+
+/** The attribute a page's keywords ride on. */
+export const KEYWORDS_ATTRIBUTE = "data-blume-keywords";
+
+/** What the page body carries for Pagefind. */
+export interface PagefindRanking {
+  /** `data-pagefind-weight` for the body, when the page is boosted. */
+  weight?: string;
+  /** The keywords, space-separated, when the page sets any. */
+  keywords?: string;
+}
+
+export const pagefindRanking = (search: {
+  boost?: number;
+  keywords?: string[];
+}): PagefindRanking => {
+  const { boost, keywords } = search;
+  return {
+    ...(boost !== undefined &&
+      boost !== 1 && {
+        weight: String(Math.min(boost, MAX_WEIGHT)),
+      }),
+    ...(keywords && keywords.length > 0 && { keywords: keywords.join(" ") }),
+  };
+};

package/src/search/popular.ts

@@ -17,7 +17,8 @@ export interface SearchPopularPage {
  * `page.route`). `withBasePath` is idempotent and skips external URLs.
  *
  * `deployment.base` is deliberately *not* applied: routes stay deploy-base-less
- * so `createLinkRow` can prefix it at click time, same as sidebar-derived pages.
+ * so `Search.astro` can add it when it renders the entry, same as
+ * sidebar-derived pages.
  *
  * `icon` stays a name here (like `navigation.featured`): the icon set is a
  * server-only module, so `Search.astro` resolves it to inline SVG at render.

package/src/search/sync/algolia.ts

@@ -16,6 +16,9 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  */
 const FILTER_ATTRIBUTES = ["locale", "version"] as const;
 
+/** The custom ranking rule that orders close matches by `search.boost`. */
+const BOOST_RANKING = "desc(boost)";
+
 /** A faceting declaration's attribute: `filterOnly(locale)` → `locale`. */
 const facetAttribute = (declaration: string): string =>
   declaration.replace(/^\w+\((?<name>.*)\)$/u, "$<name>");
@@ -48,12 +51,17 @@ export const syncAlgolia = async (
     indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });
-  const { attributesForFaceting = [] } = await client.getSettings({
-    indexName,
-  });
+  const { attributesForFaceting = [], customRanking = [] } =
+    await client.getSettings({ indexName });
   const declared = new Set(attributesForFaceting.map(facetAttribute));
   const missing = FILTER_ATTRIBUTES.filter((name) => !declared.has(name));
-  if (missing.length === 0) {
+  // Every record carries `boost` (search.boost, 1 by default): ranking by it
+  // after textual relevance puts boosted pages first among close matches.
+  // A ranking the site set in the dashboard keeps its place ahead of it.
+  const ranksByBoost = customRanking.some((rule) =>
+    /^(?:asc|desc)\(boost\)$/u.test(rule)
+  );
+  if (missing.length === 0 && ranksByBoost) {
     return;
   }
   const { taskID } = await client.setSettings({
@@ -63,6 +71,9 @@ export const syncAlgolia = async (
         ...attributesForFaceting,
         ...missing.map((name) => `filterOnly(${name})`),
       ],
+      customRanking: ranksByBoost
+        ? customRanking
+        : [...customRanking, BOOST_RANKING],
     },
   });
   await client.waitForTask({ indexName, taskID });

package/src/search/sync/orama-cloud.ts

@@ -31,9 +31,12 @@ export const syncOramaCloud = async (
   const index = manager.index(config.indexId);
   await index.snapshot(
     records.map((record) => ({
+      // The dialog multiplies each hit's score by it (search.boost).
+      boost: record.boost,
       content: record.content,
       description: record.description,
       id: record._id,
+      keywords: record.keywords ?? [],
       // Carried so an i18n site can filter hosted results per language.
       locale: record.locale,
       tag: record.tag,

package/src/search/sync/typesense.ts

@@ -57,6 +57,9 @@ export const syncTypesense = async (
       { name: "description", optional: true, type: "string" },
       { name: "content", type: "string" },
       { name: "url", type: "string" },
+      { name: "keywords", optional: true, type: "string[]" },
+      // The dialog sorts close matches by it (search.boost, 1 by default).
+      { name: "boost", type: "float" },
       { facet: true, name: "tag", optional: true, type: "string" },
       // Carried as facets so hosted results can filter per language and per
       // docs version (the SearchRecord contract; current docs = "current").
@@ -67,9 +70,11 @@ export const syncTypesense = async (
   });
 
   const documents = records.map((record) => ({
+    boost: record.boost,
     content: record.content,
     description: record.description,
     id: record._id,
+    keywords: record.keywords ?? [],
     locale: record.locale,
     tag: record.tag,
     title: record.title,

package/src/seo/jsonld.ts

@@ -1,5 +1,9 @@
 import type { Crumb } from "../components/layout/nav-utils.ts";
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
 
 /** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
 type DateInput = string | Date | null;
@@ -301,7 +305,7 @@ const breadcrumbNode = (
     "@type": "BreadcrumbList",
     itemListElement: linked.map((crumb, index) => ({
       "@type": "ListItem",
-      item: absolute(base, withBasePath(deployBase, crumb.route)),
+      item: absolute(base, mountBasePath(deployBase, crumb.route)),
       name: crumb.label,
       position: index + 1,
     })),
@@ -323,7 +327,7 @@ export const buildStructuredData = (
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
   // so JSON-LD URLs match the served location.
   const deployBase = normalizeBasePath(input.base);
-  const pageUrl = absolute(base, withBasePath(deployBase, input.route));
+  const pageUrl = absolute(base, mountBasePath(deployBase, input.route));
   const rootUrl = absolute(base, deployBase);
   const graph: JsonLdNode[] = [];
 

package/src/seo/metatags.ts

@@ -0,0 +1,67 @@
+/**
+ * Site-wide meta tags (`seo.metatags`): tags written into every page's head,
+ * for what Blume has no setting of its own for, such as site-verification
+ * tokens, `theme-color`, or an app banner. The tags Blume writes itself are
+ * refused, each pointing at the setting that controls it, so a page never
+ * carries two values for one tag.
+ */
+
+const IMAGE =
+  "`seo.og` for the generated cards, or `seo.image` in a page's frontmatter";
+const TITLE = "`title`, or `seo.title` in a page's frontmatter";
+const DESCRIPTION =
+  "`description` in a page's frontmatter or the config, or a page's `seo.description`";
+const FROM_PAGE = "Blume sets it from each page's type and dates";
+
+/** The tags Blume writes itself, by lowercase name, and what sets each. */
+const OWNED = new Map([
+  ["article:modified_time", FROM_PAGE],
+  ["article:published_time", FROM_PAGE],
+  ["description", DESCRIPTION],
+  ["og:description", DESCRIPTION],
+  ["og:site_name", "the config's `title`"],
+  ["og:title", TITLE],
+  ["og:type", FROM_PAGE],
+  ["og:url", "`deployment.site`, which sets each page's canonical URL"],
+  ["robots", "`seo.noindex` in a page's frontmatter"],
+  ["twitter:card", "Blume sets it from each page's image"],
+  ["twitter:creator", "`seo.x.creator` in the config or a page's frontmatter"],
+  ["twitter:description", DESCRIPTION],
+  ["twitter:site", "`seo.x.handle`"],
+  ["twitter:title", TITLE],
+  ["viewport", "Blume sets it for every page"],
+]);
+
+/** `og:image` and `twitter:image`, and their sub-properties. */
+const IMAGE_TAG = /^(?:og|twitter):image(?::|$)/u;
+
+/**
+ * What sets a tag Blume writes itself, or `undefined` for a tag the site can
+ * add.
+ */
+export const ownedMetatag = (name: string): string | undefined => {
+  const key = name.trim().toLowerCase();
+  return IMAGE_TAG.test(key) ? IMAGE : OWNED.get(key);
+};
+
+/**
+ * The Open Graph families, which the protocol names with `property`; every
+ * other tag takes `name`.
+ */
+const PROPERTY_TAG =
+  /^(?:og|fb|article|book|profile|music|video|al|product):/iu;
+
+/** One site-wide tag, as its `<meta>` element's attributes. */
+export interface MetatagAttributes {
+  content: string;
+  name?: string;
+  property?: string;
+}
+
+/** The site's `seo.metatags` as `<meta>` attributes, in the order written. */
+export const metatagAttributes = (
+  tags?: Readonly<Record<string, string>> | null
+): MetatagAttributes[] =>
+  Object.entries(tags ?? {}).map(([name, content]) =>
+    PROPERTY_TAG.test(name) ? { content, property: name } : { content, name }
+  );

package/src/theme/chrome-icons.ts

@@ -19,6 +19,7 @@ interface ChromeIconSet {
 
 export const chromeIcons: ChromeIconSet = {
   check: '<path d="M20 6 9 17l-5-5"/>',
+  "chevron-down": '<path d="m6 9 6 6 6-6"/>',
   copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
   file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
   search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',