blume 2.0.2 → 2.1.0

package/src/core/ui-packs/th.ts

@@ -5,6 +5,7 @@ export const th: UIStringsOverride = {
   actions: {
     addToCursor: "เพิ่มไปยัง Cursor",
     addToVscode: "เพิ่มไปยัง VS Code",
+    askAboutCode: "ถามเกี่ยวกับโค้ดนี้",
     connectMcp: "เชื่อมต่อกับ MCP",
     copied: "คัดลอกแล้ว!",
     copyClaudeCode: "คัดลอกคำสั่ง Claude Code",
@@ -30,11 +31,18 @@ export const th: UIStringsOverride = {
     copy: "คัดลอกการสนทนา",
     empty: "ถามคำถามเกี่ยวกับเอกสาร",
     error: "ขออภัย เกิดข้อผิดพลาดบางอย่าง",
+    explainCode: "อธิบายโค้ดนี้",
     label: "ถามคำถาม",
+    open: "เปิดผู้ช่วย",
     placeholder: "ถามคำถาม…",
+    rateLimited: "คุณถามคำถามจำนวนมากแล้ว โปรดลองอีกครั้งในอีกไม่กี่นาที",
+    removeCode: "นำโค้ดออก",
     send: "ส่ง",
+    support: "ติดต่อฝ่ายสนับสนุน",
+    supportSubject: "คำถามจากเอกสาร",
     tip: "เคล็ดลับ: คุณสามารถเปิดและปิดแชทได้ด้วย",
     title: "ผู้ช่วย",
+    verifyFailed: "เราไม่สามารถยืนยันได้ว่าคุณเป็นมนุษย์ โปรดลองอีกครั้ง",
     you: "คุณ",
   },
   banner: { dismiss: "ปิดประกาศ" },
@@ -42,6 +50,14 @@ export const th: UIStringsOverride = {
     description: "อัปเดตผลิตภัณฑ์และบันทึกประจำรุ่น",
     title: "บันทึกการเปลี่ยนแปลง",
   },
+  consent: {
+    accept: "ยอมรับ",
+    decline: "ปฏิเสธ",
+    label: "ความยินยอมคุกกี้",
+    message: "เราต้องการใช้คุกกี้เพื่อทำความเข้าใจว่าเอกสารนี้ถูกใช้งานอย่างไร",
+    policy: "นโยบายความเป็นส่วนตัว",
+    settings: "การตั้งค่าคุกกี้",
+  },
   content: {
     code: "โค้ด",
     copyColor: "คัดลอกสี {name} {value}",
@@ -52,6 +68,8 @@ export const th: UIStringsOverride = {
     preview: "ตัวอย่าง",
     prop: "คุณสมบัติ",
     selectTab: "เลือกแท็บ",
+    selectView: "เลือกมุมมอง",
+    showLess: "แสดงน้อยลง",
     showMore: "แสดงเพิ่มเติม",
     stars: "ดาว",
     tab: "แท็บ {n}",
@@ -59,12 +77,36 @@ export const th: UIStringsOverride = {
     update: "อัปเดต",
   },
   feedback: {
+    comment: "บอกเราเพิ่มเติม (ไม่บังคับ)",
     no: "ไม่",
     question: "หน้านี้มีประโยชน์หรือไม่?",
+    send: "ส่ง",
     thanks: "ขอบคุณสำหรับความคิดเห็นของคุณ!",
     yes: "ใช่",
   },
   languageSwitcher: { label: "ภาษา", untranslated: "ยังไม่ได้แปล" },
+  narration: {
+    cueDanger: "อันตราย",
+    cueInfo: "ข้อมูล",
+    cueNote: "หมายเหตุ",
+    cueSection: "ส่วนที่ขยายได้",
+    cueStep: "ขั้นตอนที่ {n}",
+    cueSuccess: "สำเร็จ",
+    cueTab: "แท็บ {title}",
+    cueTip: "เคล็ดลับ",
+    cueWarning: "คำเตือน",
+    error: "ไม่สามารถโหลดเสียงบรรยายได้",
+    follow: "ติดตามการอ่าน",
+    label: "ฟังหน้านี้",
+    minutes: "{n} นาที",
+    next: "ประโยคถัดไป",
+    pause: "หยุดชั่วคราว",
+    play: "เล่น",
+    previous: "ประโยคก่อนหน้า",
+    progress: "ความคืบหน้าการบรรยาย",
+    speed: "ความเร็วในการเล่น",
+    stop: "หยุดฟัง",
+  },
   nav: {
     back: "ย้อนกลับ",
     breadcrumb: "เส้นทางนำทาง",
@@ -89,6 +131,7 @@ export const th: UIStringsOverride = {
     next: "ถัดไป",
     pagination: "การแบ่งหน้า",
     previous: "ก่อนหน้า",
+    related: "หน้าที่เกี่ยวข้อง",
     skipToContent: "ข้ามไปยังเนื้อหา",
   },
   search: {

package/src/core/ui-packs/tr.ts

@@ -5,6 +5,7 @@ export const tr: UIStringsOverride = {
   actions: {
     addToCursor: "Cursor'a ekle",
     addToVscode: "VS Code'a ekle",
+    askAboutCode: "Bu kod hakkında sor",
     connectMcp: "MCP'ye bağlan",
     copied: "Kopyalandı!",
     copyClaudeCode: "Claude Code komutunu kopyala",
@@ -31,11 +32,19 @@ export const tr: UIStringsOverride = {
     copy: "Konuşmayı kopyala",
     empty: "Belgeler hakkında bir soru sorun.",
     error: "Üzgünüz, bir şeyler ters gitti.",
+    explainCode: "Bu kodu açıkla.",
     label: "Bir soru sorun",
+    open: "Asistanı aç",
     placeholder: "Bir soru sorun…",
+    rateLimited:
+      "Çok sayıda soru sordunuz. Birkaç dakika sonra yeniden deneyin.",
+    removeCode: "Kodu kaldır",
     send: "Gönder",
+    support: "Destekle iletişime geç",
+    supportSubject: "Belgelerden soru",
     tip: "İpucu: Sohbeti şu tuşla açıp kapatabilirsiniz:",
     title: "Asistan",
+    verifyFailed: "İnsan olduğunuzu doğrulayamadık. Yeniden deneyin.",
     you: "Siz",
   },
   banner: { dismiss: "Duyuruyu kapat" },
@@ -43,6 +52,15 @@ export const tr: UIStringsOverride = {
     description: "Ürün güncellemeleri ve sürüm notları.",
     title: "Değişiklik günlüğü",
   },
+  consent: {
+    accept: "Kabul et",
+    decline: "Reddet",
+    label: "Çerez onayı",
+    message:
+      "Bu belgelerin nasıl kullanıldığını anlamak için çerez kullanmak istiyoruz.",
+    policy: "Gizlilik politikası",
+    settings: "Çerez ayarları",
+  },
   content: {
     code: "Kod",
     copyColor: "Rengi kopyala: {name} {value}",
@@ -53,6 +71,8 @@ export const tr: UIStringsOverride = {
     preview: "Önizleme",
     prop: "Özellik",
     selectTab: "Sekme seç",
+    selectView: "Görünüm seç",
+    showLess: "Daha az göster",
     showMore: "Daha fazla göster",
     stars: "Yıldızlar",
     tab: "Sekme {n}",
@@ -60,12 +80,36 @@ export const tr: UIStringsOverride = {
     update: "Güncelleme",
   },
   feedback: {
+    comment: "Bize daha fazlasını anlatın (isteğe bağlı)",
     no: "Hayır",
     question: "Bu sayfa yardımcı oldu mu?",
+    send: "Gönder",
     thanks: "Geri bildiriminiz için teşekkürler!",
     yes: "Evet",
   },
   languageSwitcher: { label: "Dil", untranslated: "Çevrilmemiş" },
+  narration: {
+    cueDanger: "Tehlike.",
+    cueInfo: "Bilgi.",
+    cueNote: "Not.",
+    cueSection: "Genişletilebilir bölüm.",
+    cueStep: "Adım {n}.",
+    cueSuccess: "Başarılı.",
+    cueTab: "{title} sekmesi.",
+    cueTip: "İpucu.",
+    cueWarning: "Uyarı.",
+    error: "Seslendirme yüklenemedi.",
+    follow: "Okumayı takip et",
+    label: "Bu sayfayı dinle",
+    minutes: "{n} dk",
+    next: "Sonraki cümle",
+    pause: "Duraklat",
+    play: "Oynat",
+    previous: "Önceki cümle",
+    progress: "Seslendirme ilerlemesi",
+    speed: "Oynatma hızı",
+    stop: "Dinlemeyi durdur",
+  },
   nav: {
     back: "Geri",
     breadcrumb: "Gezinme yolu",
@@ -90,6 +134,7 @@ export const tr: UIStringsOverride = {
     next: "Sonraki",
     pagination: "Sayfalama",
     previous: "Önceki",
+    related: "İlgili sayfalar",
     skipToContent: "İçeriğe geç",
   },
   search: {

package/src/core/ui-packs/uk.ts

@@ -5,6 +5,7 @@ export const uk: UIStringsOverride = {
   actions: {
     addToCursor: "Додати до Cursor",
     addToVscode: "Додати до VS Code",
+    askAboutCode: "Запитати про цей код",
     connectMcp: "Підключитися до MCP",
     copied: "Скопійовано!",
     copyClaudeCode: "Скопіювати команду Claude Code",
@@ -31,11 +32,19 @@ export const uk: UIStringsOverride = {
     copy: "Скопіювати бесіду",
     empty: "Поставте запитання щодо документації.",
     error: "Вибачте, щось пішло не так.",
+    explainCode: "Поясни цей код.",
     label: "Поставити запитання",
+    open: "Відкрити асистента",
     placeholder: "Поставте запитання…",
+    rateLimited:
+      "Ви поставили багато запитань. Спробуйте знову за кілька хвилин.",
+    removeCode: "Прибрати код",
     send: "Надіслати",
+    support: "Зв'язатися з підтримкою",
+    supportSubject: "Питання з документації",
     tip: "Порада: чат можна відкрити й закрити за допомогою",
     title: "Асистент",
+    verifyFailed: "Не вдалося підтвердити, що ви людина. Спробуйте знову.",
     you: "Ви",
   },
   banner: { dismiss: "Закрити оголошення" },
@@ -43,6 +52,15 @@ export const uk: UIStringsOverride = {
     description: "Оновлення продукту та примітки до випусків.",
     title: "Журнал змін",
   },
+  consent: {
+    accept: "Прийняти",
+    decline: "Відхилити",
+    label: "Згода на cookie",
+    message:
+      "Ми хотіли б використовувати файли cookie, щоб розуміти, як використовується ця документація.",
+    policy: "Політика конфіденційності",
+    settings: "Налаштування cookie",
+  },
   content: {
     code: "Код",
     copyColor: "Скопіювати колір {name} {value}",
@@ -53,6 +71,8 @@ export const uk: UIStringsOverride = {
     preview: "Попередній перегляд",
     prop: "Властивість",
     selectTab: "Вибрати вкладку",
+    selectView: "Вибрати подання",
+    showLess: "Показати менше",
     showMore: "Показати більше",
     stars: "Зірки",
     tab: "Вкладка {n}",
@@ -60,12 +80,36 @@ export const uk: UIStringsOverride = {
     update: "Оновлення",
   },
   feedback: {
+    comment: "Розкажіть докладніше (необов'язково)",
     no: "Ні",
     question: "Чи була ця сторінка корисною?",
+    send: "Надіслати",
     thanks: "Дякуємо за ваш відгук!",
     yes: "Так",
   },
   languageSwitcher: { label: "Мова", untranslated: "Не перекладено" },
+  narration: {
+    cueDanger: "Небезпека.",
+    cueInfo: "Інформація.",
+    cueNote: "Примітка.",
+    cueSection: "Розгортуваний розділ.",
+    cueStep: "Крок {n}.",
+    cueSuccess: "Успіх.",
+    cueTab: "Вкладка {title}.",
+    cueTip: "Порада.",
+    cueWarning: "Попередження.",
+    error: "Не вдалося завантажити озвучення.",
+    follow: "Стежити за читанням",
+    label: "Прослухати сторінку",
+    minutes: "{n} хв",
+    next: "Наступне речення",
+    pause: "Пауза",
+    play: "Відтворити",
+    previous: "Попереднє речення",
+    progress: "Хід відтворення",
+    speed: "Швидкість відтворення",
+    stop: "Зупинити прослуховування",
+  },
   nav: {
     back: "Назад",
     breadcrumb: "Навігаційний ланцюжок",
@@ -90,6 +134,7 @@ export const uk: UIStringsOverride = {
     next: "Далі",
     pagination: "Пагінація",
     previous: "Назад",
+    related: "Пов'язані сторінки",
     skipToContent: "Перейти до вмісту",
   },
   search: {

package/src/core/ui-packs/vi.ts

@@ -5,6 +5,7 @@ export const vi: UIStringsOverride = {
   actions: {
     addToCursor: "Thêm vào Cursor",
     addToVscode: "Thêm vào VS Code",
+    askAboutCode: "Hỏi về đoạn mã này",
     connectMcp: "Kết nối với MCP",
     copied: "Đã sao chép!",
     copyClaudeCode: "Sao chép lệnh Claude Code",
@@ -30,11 +31,19 @@ export const vi: UIStringsOverride = {
     copy: "Sao chép cuộc trò chuyện",
     empty: "Đặt câu hỏi về tài liệu.",
     error: "Xin lỗi, đã xảy ra sự cố.",
+    explainCode: "Giải thích đoạn mã này.",
     label: "Đặt câu hỏi",
+    open: "Mở trợ lý",
     placeholder: "Đặt câu hỏi…",
+    rateLimited: "Bạn đã hỏi rất nhiều câu hỏi. Hãy thử lại sau vài phút.",
+    removeCode: "Xóa mã",
     send: "Gửi",
+    support: "Liên hệ hỗ trợ",
+    supportSubject: "Câu hỏi từ tài liệu",
     tip: "Mẹo: Bạn có thể mở và đóng trò chuyện bằng",
     title: "Trợ lý",
+    verifyFailed:
+      "Chúng tôi không thể xác minh bạn là người thật. Hãy thử lại.",
     you: "Bạn",
   },
   banner: { dismiss: "Đóng thông báo" },
@@ -42,6 +51,15 @@ export const vi: UIStringsOverride = {
     description: "Cập nhật sản phẩm và ghi chú phát hành.",
     title: "Nhật ký thay đổi",
   },
+  consent: {
+    accept: "Chấp nhận",
+    decline: "Từ chối",
+    label: "Đồng ý cookie",
+    message:
+      "Chúng tôi muốn sử dụng cookie để hiểu cách tài liệu này được sử dụng.",
+    policy: "Chính sách quyền riêng tư",
+    settings: "Cài đặt cookie",
+  },
   content: {
     code: "Mã",
     copyColor: "Sao chép màu {name} {value}",
@@ -52,6 +70,8 @@ export const vi: UIStringsOverride = {
     preview: "Xem trước",
     prop: "Thuộc tính",
     selectTab: "Chọn tab",
+    selectView: "Chọn chế độ xem",
+    showLess: "Ẩn bớt",
     showMore: "Hiển thị thêm",
     stars: "Sao",
     tab: "Tab {n}",
@@ -59,12 +79,36 @@ export const vi: UIStringsOverride = {
     update: "Cập nhật",
   },
   feedback: {
+    comment: "Cho chúng tôi biết thêm (không bắt buộc)",
     no: "Không",
     question: "Trang này có hữu ích không?",
+    send: "Gửi",
     thanks: "Cảm ơn phản hồi của bạn!",
     yes: "Có",
   },
   languageSwitcher: { label: "Ngôn ngữ", untranslated: "Chưa dịch" },
+  narration: {
+    cueDanger: "Nguy hiểm.",
+    cueInfo: "Thông tin.",
+    cueNote: "Ghi chú.",
+    cueSection: "Mục có thể mở rộng.",
+    cueStep: "Bước {n}.",
+    cueSuccess: "Thành công.",
+    cueTab: "Tab {title}.",
+    cueTip: "Mẹo.",
+    cueWarning: "Cảnh báo.",
+    error: "Không thể tải âm thanh.",
+    follow: "Theo dõi lời đọc",
+    label: "Nghe trang này",
+    minutes: "{n} phút",
+    next: "Câu tiếp theo",
+    pause: "Tạm dừng",
+    play: "Phát",
+    previous: "Câu trước",
+    progress: "Tiến độ đọc",
+    speed: "Tốc độ phát",
+    stop: "Dừng nghe",
+  },
   nav: {
     back: "Quay lại",
     breadcrumb: "Đường dẫn điều hướng",
@@ -89,6 +133,7 @@ export const vi: UIStringsOverride = {
     next: "Tiếp theo",
     pagination: "Phân trang",
     previous: "Trước",
+    related: "Trang liên quan",
     skipToContent: "Chuyển đến nội dung",
   },
   search: {

package/src/core/ui-packs/zh-tw.ts

@@ -5,6 +5,7 @@ export const zhTW: UIStringsOverride = {
   actions: {
     addToCursor: "新增至 Cursor",
     addToVscode: "新增至 VS Code",
+    askAboutCode: "詢問這段程式碼",
     connectMcp: "連線至 MCP",
     copied: "已複製！",
     copyClaudeCode: "複製 Claude Code 指令",
@@ -30,11 +31,18 @@ export const zhTW: UIStringsOverride = {
     copy: "複製對話",
     empty: "針對文件提出問題。",
     error: "抱歉，發生了一些問題。",
+    explainCode: "解釋這段程式碼。",
     label: "提出問題",
+    open: "開啟助理",
     placeholder: "提出問題…",
+    rateLimited: "你提出的問題太多了，請幾分鐘後再試。",
+    removeCode: "移除程式碼",
     send: "傳送",
+    support: "聯絡支援團隊",
+    supportSubject: "來自文件的問題",
     tip: "提示：可透過以下快捷鍵開啟和關閉聊天",
     title: "助理",
+    verifyFailed: "無法確認你是真人，請再試一次。",
     you: "你",
   },
   banner: { dismiss: "關閉公告" },
@@ -42,6 +50,14 @@ export const zhTW: UIStringsOverride = {
     description: "產品更新與版本說明。",
     title: "更新日誌",
   },
+  consent: {
+    accept: "接受",
+    decline: "拒絕",
+    label: "Cookie 同意",
+    message: "我們希望使用 Cookie 來了解這份文件的使用情況。",
+    policy: "隱私權政策",
+    settings: "Cookie 設定",
+  },
   content: {
     code: "程式碼",
     copyColor: "複製顏色 {name} {value}",
@@ -52,6 +68,8 @@ export const zhTW: UIStringsOverride = {
     preview: "預覽",
     prop: "屬性",
     selectTab: "選擇分頁",
+    selectView: "選擇檢視",
+    showLess: "顯示較少",
     showMore: "顯示更多",
     stars: "星標",
     tab: "分頁 {n}",
@@ -59,12 +77,36 @@ export const zhTW: UIStringsOverride = {
     update: "更新",
   },
   feedback: {
+    comment: "告訴我們更多（選填）",
     no: "沒有幫助",
     question: "這個頁面有幫助嗎？",
+    send: "送出",
     thanks: "感謝你的意見回饋！",
     yes: "有幫助",
   },
   languageSwitcher: { label: "語言", untranslated: "未翻譯" },
+  narration: {
+    cueDanger: "危險。",
+    cueInfo: "資訊。",
+    cueNote: "備註。",
+    cueSection: "可展開區段。",
+    cueStep: "第 {n} 步。",
+    cueSuccess: "成功。",
+    cueTab: "{title} 分頁。",
+    cueTip: "提示。",
+    cueWarning: "警告。",
+    error: "無法載入朗讀音訊。",
+    follow: "跟隨朗讀",
+    label: "收聽此頁面",
+    minutes: "{n} 分鐘",
+    next: "下一句",
+    pause: "暫停",
+    play: "播放",
+    previous: "上一句",
+    progress: "朗讀進度",
+    speed: "播放速度",
+    stop: "停止收聽",
+  },
   nav: {
     back: "返回",
     breadcrumb: "麵包屑導覽",
@@ -89,6 +131,7 @@ export const zhTW: UIStringsOverride = {
     next: "下一頁",
     pagination: "分頁",
     previous: "上一頁",
+    related: "相關頁面",
     skipToContent: "跳至內容",
   },
   search: {

package/src/core/ui-packs/zh.ts

@@ -5,6 +5,7 @@ export const zh: UIStringsOverride = {
   actions: {
     addToCursor: "添加到 Cursor",
     addToVscode: "添加到 VS Code",
+    askAboutCode: "询问这段代码",
     connectMcp: "连接到 MCP",
     copied: "已复制！",
     copyClaudeCode: "复制 Claude Code 命令",
@@ -30,11 +31,18 @@ export const zh: UIStringsOverride = {
     copy: "复制对话",
     empty: "就文档提出问题。",
     error: "抱歉，出了点问题。",
+    explainCode: "解释这段代码。",
     label: "提出问题",
+    open: "打开助手",
     placeholder: "提出问题…",
+    rateLimited: "你提的问题太多了，请几分钟后再试。",
+    removeCode: "移除代码",
     send: "发送",
+    support: "联系支持团队",
+    supportSubject: "来自文档的问题",
     tip: "提示：可通过以下快捷键打开和关闭聊天",
     title: "助手",
+    verifyFailed: "无法确认你是真人，请重试。",
     you: "你",
   },
   banner: { dismiss: "关闭公告" },
@@ -42,6 +50,14 @@ export const zh: UIStringsOverride = {
     description: "产品更新与版本说明。",
     title: "更新日志",
   },
+  consent: {
+    accept: "接受",
+    decline: "拒绝",
+    label: "Cookie 同意",
+    message: "我们希望使用 Cookie 来了解本文档的使用情况。",
+    policy: "隐私政策",
+    settings: "Cookie 设置",
+  },
   content: {
     code: "代码",
     copyColor: "复制颜色 {name} {value}",
@@ -52,6 +68,8 @@ export const zh: UIStringsOverride = {
     preview: "预览",
     prop: "属性",
     selectTab: "选择标签页",
+    selectView: "选择视图",
+    showLess: "显示更少",
     showMore: "显示更多",
     stars: "星标",
     tab: "标签页 {n}",
@@ -59,12 +77,36 @@ export const zh: UIStringsOverride = {
     update: "更新",
   },
   feedback: {
+    comment: "告诉我们更多（选填）",
     no: "没有帮助",
     question: "这个页面有帮助吗？",
+    send: "发送",
     thanks: "感谢你的反馈！",
     yes: "有帮助",
   },
   languageSwitcher: { label: "语言", untranslated: "未翻译" },
+  narration: {
+    cueDanger: "危险。",
+    cueInfo: "信息。",
+    cueNote: "备注。",
+    cueSection: "可展开部分。",
+    cueStep: "第 {n} 步。",
+    cueSuccess: "成功。",
+    cueTab: "{title} 标签页。",
+    cueTip: "提示。",
+    cueWarning: "警告。",
+    error: "无法加载朗读音频。",
+    follow: "跟随朗读",
+    label: "收听此页面",
+    minutes: "{n} 分钟",
+    next: "下一句",
+    pause: "暂停",
+    play: "播放",
+    previous: "上一句",
+    progress: "朗读进度",
+    speed: "播放速度",
+    stop: "停止收听",
+  },
   nav: {
     back: "返回",
     breadcrumb: "面包屑导航",
@@ -89,6 +131,7 @@ export const zh: UIStringsOverride = {
     next: "下一页",
     pagination: "分页",
     previous: "上一页",
+    related: "相关页面",
     skipToContent: "跳到内容",
   },
   search: {

package/src/core/variables.ts

@@ -0,0 +1,103 @@
+import { nextFenceState } from "./code-fences.ts";
+import type { FenceState } from "./code-fences.ts";
+
+/**
+ * Content variables: `variables: { version: "2.1.0" }` in `blume.config.ts`
+ * makes `{{version}}` in a page read `2.1.0` wherever it appears in the body,
+ * code and links included. The syntax is Mintlify's, so migrated pages keep
+ * working.
+ *
+ * Substitution is textual, before any parsing, so a page's HTML, its search
+ * entry, its `.md` mirror, and `llms-full.txt` all agree: the MDX pipeline
+ * substitutes in a Vite transform ahead of the compiler (an MDX parser would
+ * read `{{version}}` as a JavaScript expression), the Markdown pipeline in a
+ * plugin over the parsed text, includes as their files are read, and the raw
+ * readers through {@link substituteVariables}. Only defined names are
+ * replaced; an undefined one in prose is a build error
+ * (`BLUME_UNDEFINED_VARIABLE`), and inside code it is left alone, since
+ * templating examples (`{{name}}` in a Handlebars snippet) are common there.
+ */
+
+/** The variables a site defines, name to value. */
+export type ContentVariables = Readonly<Record<string, string>>;
+
+/** A variable name: letters, digits, `_`, and `-` (Mintlify's `api-url`). */
+export const VARIABLE_NAME = /^[\w-]+$/u;
+
+/** A `{{name}}` reference, spaces inside the braces allowed. */
+const REFERENCE = /\{\{\s*(?<name>[\w-]+)\s*\}\}/gu;
+
+/** Whether a site defines any variables, so the rest can be skipped. */
+export const hasVariables = (
+  variables?: ContentVariables
+): variables is ContentVariables =>
+  variables !== undefined && Object.keys(variables).length > 0;
+
+/** `text` with every reference to a defined variable replaced by its value. */
+export const substituteVariables = (
+  text: string,
+  variables?: ContentVariables
+): string => {
+  if (!(hasVariables(variables) && text.includes("{{"))) {
+    return text;
+  }
+  return text.replaceAll(REFERENCE, (match, name: string) =>
+    Object.hasOwn(variables, name) ? (variables[name] ?? match) : match
+  );
+};
+
+// A leading front matter block: variables apply to the body, not to it.
+const FRONT_MATTER = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/u;
+
+/**
+ * {@link substituteVariables} over a page's raw source, leaving its front
+ * matter as written: the rendered page reads its title and description from
+ * the unsubstituted front matter, so the other surfaces must too.
+ */
+export const substituteVariablesInBody = (
+  source: string,
+  variables?: ContentVariables
+): string => {
+  const head = FRONT_MATTER.exec(source)?.[0] ?? "";
+  return head + substituteVariables(source.slice(head.length), variables);
+};
+
+/** An undefined variable referenced in prose, with its 1-based line. */
+export interface UndefinedVariable {
+  line: number;
+  name: string;
+}
+
+// A backtick code span: the same run of backticks opens and closes it.
+const CODE_SPAN = /(?<ticks>`+)[^`][\s\S]*?\k<ticks>/gu;
+
+/**
+ * The undefined variables `text` references outside code: fenced blocks and
+ * inline code spans are skipped, so a templating example never fails a
+ * build. Empty when the site defines no variables at all, so a page that
+ * shows `{{…}}` literally keeps working until the site opts in.
+ */
+export const undefinedVariables = (
+  text: string,
+  variables?: ContentVariables
+): UndefinedVariable[] => {
+  if (!(hasVariables(variables) && text.includes("{{"))) {
+    return [];
+  }
+  const found: UndefinedVariable[] = [];
+  let fence: FenceState = null;
+  for (const [index, line] of text.split("\n").entries()) {
+    const wasInFence = fence !== null;
+    fence = nextFenceState(line, fence);
+    if (wasInFence || fence !== null) {
+      continue;
+    }
+    for (const match of line.replaceAll(CODE_SPAN, "").matchAll(REFERENCE)) {
+      const name = match.groups?.name ?? "";
+      if (!Object.hasOwn(variables, name)) {
+        found.push({ line: index + 1, name });
+      }
+    }
+  }
+  return found;
+};