blume 1.1.3 → 1.1.4

package/src/core/graph.ts

@@ -116,7 +116,13 @@ const buildLocaleNavigation = (
     basePath: options.basePath ?? "",
     diagnostics,
     display: options.navigation.sidebar.display,
-    featured: options.navigation.featured,
+    // Internal featured hrefs are localized like tab paths — a pinned
+    // `/changelog` link rendered on `/fr/…` pages must stay inside the
+    // reader's locale, not kick them back to the default one.
+    featured: options.navigation.featured?.map((link) => ({
+      ...link,
+      href: localizePath(link.href),
+    })),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise):
     // the tab pointing here spans the whole tree and must not be treated as a

package/src/core/i18n.ts

@@ -105,11 +105,19 @@ export const localePlacement = (
 ): { navPath: string; locales: string[] } => {
   const base = rel.slice(0, rel.length - ext.length);
 
-  // Shared `$` file: the same content in every locale.
+  // Shared `$` file: the same content in every locale. A shared file placed
+  // inside a locale directory (`fr/changelog.$.mdx`) still sheds that
+  // directory from its nav path — otherwise every locale's record would route
+  // under `/fr/…`, nesting the default locale inside the French namespace and
+  // the French copy at `/fr/fr/…`.
   if (base.endsWith(".$")) {
+    const shared = `${base.slice(0, -2)}${ext}`;
     return {
       locales: i18n.locales.map((locale) => locale.code),
-      navPath: `${base.slice(0, -2)}${ext}`,
+      navPath:
+        i18n.parser === "dir"
+          ? detectLocale(shared.split("/"), i18n).rest.join("/")
+          : shared,
     };
   }
 

package/src/core/navigation.ts

@@ -473,9 +473,13 @@ const normalizeRef = (ref: string): string => {
     return "/";
   }
   const withSlash = ref.startsWith("/") ? ref : `/${ref}`;
-  const trimmed = withSlash.endsWith("/index")
-    ? withSlash.slice(0, -"/index".length)
-    : withSlash;
+  // Routes are stored slashless (`/guides`, not `/guides/`); a hand-written
+  // `"guides/"` ref must still find its page instead of being silently
+  // dropped from the sidebar.
+  const noTrailing = withSlash.replace(/\/+$/u, "");
+  const trimmed = noTrailing.endsWith("/index")
+    ? noTrailing.slice(0, -"/index".length)
+    : noTrailing;
   // "/index" trims to "" — that's the root, not an empty route.
   return trimmed === "" ? "/" : trimmed;
 };

package/src/core/sources/normalize.ts

@@ -38,6 +38,15 @@ export const slugify = (text: string): string =>
     .replaceAll(/-+/gu, "-")
     .replaceAll(/^-|-$/gu, "");
 
+/**
+ * {@link slugify} for a slug that may span path segments (`guides/setup`).
+ * `slugify` deletes `/` along with all other punctuation, which would mash
+ * `guides/setup` into `guidessetup` — and collide it with a genuine `guidessetup`
+ * document. Each segment is slugged on its own and the separators kept.
+ */
+export const slugifyPath = (text: string): string =>
+  text.split("/").map(slugify).filter(Boolean).join("/");
+
 /** Title-case a slug segment for display. */
 const titleCase = (value: string): string =>
   value
@@ -104,13 +113,24 @@ type FenceState = "```" | "~~~" | null;
  * the state untouched.
  */
 const nextFenceState = (line: string, fence: FenceState): FenceState => {
-  const delimiter = line.trimStart().match(CODE_FENCE)?.groups?.delimiter as
+  const trimmed = line.trimStart();
+  const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter as
     | Exclude<FenceState, null>
     | undefined;
   if (delimiter === undefined) {
     return fence;
   }
   if (fence === null) {
+    // A backtick fence's info string cannot itself contain a backtick
+    // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
+    // opening a phantom fence on it would swallow every heading and link
+    // after it. Tilde fences carry no such rule.
+    if (delimiter === "```") {
+      const run = trimmed.match(/^`+/u)?.[0].length ?? 0;
+      if (trimmed.slice(run).includes("`")) {
+        return fence;
+      }
+    }
     return delimiter;
   }
   return fence === delimiter ? null : fence;
@@ -159,6 +179,13 @@ const linesWithoutFrontMatter = (body: string): string[] => {
   if (!/^-{3}\s*$/u.test(lines[0] ?? "")) {
     return lines;
   }
+  // A blank line directly after the dashes means the body *opens* with a
+  // thematic break, not front matter — YAML metadata starts on the very next
+  // line. Treating it as an unclosed block ate everything up to the next
+  // `---`/`...` line of an already-stripped body.
+  if ((lines[1] ?? "").trim() === "") {
+    return lines;
+  }
   const close = lines.findIndex(
     (line, index) => index > 0 && FRONT_MATTER_CLOSE.test(line)
   );
@@ -304,9 +331,26 @@ export const extractHeadings = (body: string): Heading[] => {
   return headings;
 };
 
-const MD_LINK = /\[[^\]]*\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)/gu;
+// The label admits one level of nested brackets so an image-wrapped link
+// (`[![alt](/img.png)](/target)`) matches as the *outer* link — with a flat
+// `[^\]]*` label the match stopped at the image's `]` and the outer target was
+// never seen. The target admits one level of balanced parens so a Wikipedia-
+// style URL (`/wiki/Foo_(bar)`) isn't truncated at its first `)`.
+const MD_LINK =
+  /\[(?<label>(?:[^[\]]|\[[^\]]*\])*)\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
+// An image inside a link label; its target was matched (and so validated) as a
+// link of its own before labels admitted nesting, and still should be.
+const MD_IMAGE =
+  /!\[[^\]]*\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
 const INLINE_CODE = /`[^`]*`/gu;
 
+/** Column (0-based, within `matched`) where a link/image match's target starts. */
+const targetOffsetIn = (
+  matched: string,
+  target: string,
+  title: string | undefined
+): number => matched.length - 1 - (title?.length ?? 0) - target.length;
+
 /**
  * Extract link targets from a markdown body for later validation, recording the
  * 1-based line/column of each target. Skips fenced code blocks and inline code.
@@ -335,16 +379,33 @@ const scanLinkLine = (
     if (target === undefined || match.index === undefined) {
       continue;
     }
-    // Locate the target from the `](` boundary rather than searching for the
-    // target text from the match start — otherwise a label that contains the
-    // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
-    // label can't contain `]`, so `](` is unambiguous.
-    const targetOffset = match.index + match[0].indexOf("](") + "](".length;
+    // Locate the target by arithmetic from the match end rather than searching
+    // for its text — a label that contains the same text (e.g. `[/a/b](/a/b)`)
+    // would otherwise report the column inside the label.
+    const targetOffset = targetOffsetIn(match[0], target, match.groups?.title);
     links.push({
-      column: targetOffset + 1,
+      column: match.index + targetOffset + 1,
       line: lineNumber,
       target,
     });
+    // An image nested in the label (`[![alt](/img.png)](/target)`) carries its
+    // own target; surface it too so a missing image is still caught.
+    const label = match[0].slice(0, targetOffset - "](".length);
+    for (const image of label.matchAll(MD_IMAGE)) {
+      const imageTarget = image.groups?.target;
+      if (imageTarget === undefined || image.index === undefined) {
+        continue;
+      }
+      links.push({
+        column:
+          match.index +
+          image.index +
+          targetOffsetIn(image[0], imageTarget, image.groups?.title) +
+          1,
+        line: lineNumber,
+        target: imageTarget,
+      });
+    }
   }
   return next;
 };

package/src/core/sources/notion.ts

@@ -12,7 +12,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
-import { slugify } from "./normalize.ts";
+import { slugifyPath } from "./normalize.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -432,7 +432,9 @@ export const notionSource = (
     const slugProp = richToMarkdown(
       page.properties[props.slug ?? "Slug"]?.rich_text
     );
-    const slug = slugify(slugProp || title) || page.id;
+    // Path-aware: a `guides/setup` slug keeps its `/` (per-segment slugging)
+    // instead of mashing into `guidessetup`.
+    const slug = slugifyPath(slugProp || title) || page.id;
     return { data, slug };
   };
 

package/src/core/sources/sanity.ts

@@ -8,7 +8,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
-import { slugify } from "./normalize.ts";
+import { slugify, slugifyPath } from "./normalize.ts";
 import { portableTextToMarkdown } from "./portable-text.ts";
 import type { PortableTextBlock } from "./portable-text.ts";
 import type {
@@ -142,9 +142,11 @@ export const sanitySource = (
       "untitled";
     // Fall back to the unique `_id` when a slug (e.g. a non-ASCII `slug.current`)
     // slugifies to empty, so distinct documents don't all collapse to the same
-    // `untitled.md` ref and silently overwrite each other.
+    // `untitled.md` ref and silently overwrite each other. Path-aware: a
+    // `guides/setup` slug keeps its `/` (per-segment slugging) instead of
+    // mashing into `guidessetup`.
     const slug =
-      slugify(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
+      slugifyPath(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
     const data: Record<string, unknown> = {};
     const title = asString(getPath(doc, fields.title ?? "title"));

package/src/markdown/code-title.ts

@@ -51,7 +51,13 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
   }
-  const explicit = raw.match(TITLE_ATTR);
+  // Blank every *other* quoted attr first, so a `title="…"` embedded in
+  // another attribute's value (`caption='set title="X" here'`) can't be
+  // promoted to the block title.
+  const scrubbed = raw.replace(QUOTED_ATTR, (attr) =>
+    attr.startsWith("title=") ? attr : " "
+  );
+  const explicit = scrubbed.match(TITLE_ATTR);
   const attrTitle = explicit?.groups?.dq ?? explicit?.groups?.sq;
   if (attrTitle) {
     return attrTitle;

package/src/openapi/model.ts

@@ -101,6 +101,32 @@ export type OpenApiData = Record<string, ApiSpecData>;
 const isOperation = (value: unknown): value is OperationObject =>
   typeof value === "object" && value !== null;
 
+/**
+ * Assign each distinct tag name a unique slug. `slugify` can collapse
+ * different names onto one value — any two all-non-ASCII tags (`ペット`,
+ * `注文`) both fall through to the `operations` fallback — and a shared slug
+ * silently merges the tags' routes, sidebar groups, and overview sections.
+ * Collisions gain `-2`, `-3`, … in first-seen order.
+ */
+const tagSlugger = (): ((name: string) => string) => {
+  const assigned = new Map<string, string>();
+  const taken = new Set<string>();
+  return (name) => {
+    const existing = assigned.get(name);
+    if (existing) {
+      return existing;
+    }
+    const base = slugify(name) || "operations";
+    let slug = base;
+    for (let suffix = 2; taken.has(slug); suffix += 1) {
+      slug = `${base}-${suffix}`;
+    }
+    taken.add(slug);
+    assigned.set(name, slug);
+    return slug;
+  };
+};
+
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
@@ -119,6 +145,7 @@ export const extractOperations = (
   );
   const seen = new Set<string>();
   const warnings: string[] = [];
+  const slugForTag = tagSlugger();
 
   for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
     const item = rawItem as PathItemObject | undefined;
@@ -137,7 +164,7 @@ export const extractOperations = (
         continue;
       }
       const tag = operation.tags?.[0] ?? UNTAGGED;
-      const tagSlug = slugify(tag) || "operations";
+      const tagSlug = slugForTag(tag);
       if (!tagsSeen.has(tag)) {
         tagsSeen.add(tag);
         tagOrder.push(tag);
@@ -166,7 +193,9 @@ export const extractOperations = (
   const tags: ApiTagRef[] = tagOrder.map((name) => ({
     description: tagMeta.get(name) ?? "",
     name,
-    slug: slugify(name) || "operations",
+    // The same slugger instance, so every tag resolves to the slug its
+    // operations were routed under.
+    slug: slugForTag(name),
   }));
 
   return { operations, tags, warnings };

package/src/openapi/render-mdx.ts

@@ -11,13 +11,14 @@ import type { ApiOperationRef, ApiSpecData } from "./model.ts";
  * omit their own top heading.
  */
 
-// Neutralize the few characters MDX treats specially (`{` expressions, `<` JSX)
-// so an arbitrary spec description can be embedded in the body verbatim without
-// breaking compilation. They render as their literal selves.
-const MDX_UNSAFE = /[<>{}]/gu;
+// Neutralize the few characters MDX treats specially (`{` expressions, `<`
+// JSX) so an arbitrary spec description can be embedded in the body verbatim
+// without breaking compilation. They render as their literal selves. `>` is
+// deliberately not escaped: it isn't MDX-special on its own, and escaping it
+// turns a `> Note:` blockquote into literal "&gt; Note:" text.
+const MDX_UNSAFE = /[<{}]/gu;
 const ENTITIES: Record<string, string> = {
   "<": "&lt;",
-  ">": "&gt;",
   "{": "&#123;",
   "}": "&#125;",
 };
@@ -28,8 +29,12 @@ const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
 // Backtick code — inline spans and fences alike — is already literal in MDX,
 // and entities are NOT decoded inside it, so escaping there would render the
 // entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
-// backtick run covers `code`, ``code``, and ```fences``` in one shot.
-const BACKTICK_CODE = /(?<bt>`+)[\s\S]*?\k<bt>/gu;
+// backtick run covers `code`, ``code``, and ```fences``` in one shot. Both
+// runs are pinned by the backtick lookarounds: CommonMark pairs a span only
+// with an *equal-length* run, so without them a lone backtick would "close" on
+// the first backtick of a longer fence run — leaving `{` in the real prose
+// unescaped (a compile error) and escaping entities into the fence body.
+const BACKTICK_CODE = /(?<!`)(?<bt>`+)(?!`)[\s\S]*?(?<!`)\k<bt>(?!`)/gu;
 
 const escapeProse = (text: string): string =>
   text