From ed54233c0a7d5333e280ad3f937a4a79356ef440 Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Thu, 11 Jun 2026 09:11:27 +0300
Subject: [PATCH] fix: pin per-page canonical URLs to the /docs subpath

Mintlify's auto-canonical resolves the page path against the canonical
base origin, dropping the /docs prefix on the rendobar.mintlify.app
subdomain. Every subdomain page pointed its canonical at a 404
(e.g. rendobar.com/quickstart instead of rendobar.com/docs/quickstart),
so search engines ignore it and the subdomain competes with the real
docs in the index. The docs.json seo.metatags.canonical base alone
(#19) did not fix this.

Pin an explicit canonical in every page's frontmatter and enforce the
exact value in validate-frontmatter.mjs so new pages can't regress.
scripts/add-canonical.mjs regenerates them.
---
 authentication.mdx               |  1 +
 cli/authentication.mdx           |  1 +
 cli/ci-cd.mdx                    |  1 +
 cli/commands.mdx                 |  1 +
 cli/installation.mdx             |  1 +
 cli/overview.mdx                 |  1 +
 cli/troubleshooting.mdx          |  1 +
 concepts/credits.mdx             |  1 +
 concepts/job-lifecycle.mdx       |  1 +
 concepts/job-output.mdx          |  1 +
 guides/ffmpeg.mdx                |  1 +
 guides/webhooks.mdx              |  1 +
 job-types/caption-burn.mdx       |  1 +
 job-types/captions-animate.mdx   |  1 +
 job-types/ffmpeg.mdx             |  1 +
 mcp/examples.mdx                 |  1 +
 mcp/installation.mdx             |  1 +
 mcp/overview.mdx                 |  1 +
 mcp/tools.mdx                    |  1 +
 mcp/troubleshooting.mdx          |  1 +
 mcp/web-and-mobile.mdx           |  1 +
 quickstart.mdx                   |  1 +
 scripts/add-canonical.mjs        | 47 ++++++++++++++++++++++++++++++++
 scripts/validate-frontmatter.mjs | 18 ++++++++++++
 support/errors.mdx               |  1 +
 support/faq.mdx                  |  1 +
 support/limits.mdx               |  1 +
 27 files changed, 90 insertions(+)
 create mode 100644 scripts/add-canonical.mjs

diff --git a/authentication.mdx b/authentication.mdx
index 41d023a..1970328 100644
--- a/authentication.mdx
+++ b/authentication.mdx
@@ -4,6 +4,7 @@ description: "Authenticate API requests with a Bearer API key. Same keys cover R
 sidebarTitle: "Authentication"
 icon: "key"
 keywords: ["rendobar authentication", "api key", "bearer token", "rb_ key", "mcp oauth", "rest api auth"]
+canonical: "https://rendobar.com/docs/authentication"
 ---
 
 <script
diff --git a/cli/authentication.mdx b/cli/authentication.mdx
index ddf5e1a..e9ffe07 100644
--- a/cli/authentication.mdx
+++ b/cli/authentication.mdx
@@ -3,6 +3,7 @@ title: "Authenticate the CLI"
 description: "Sign in via browser OAuth, paste an API key for non-interactive use, or set RENDOBAR_API_KEY for CI. Tokens auto-refresh every hour."
 icon: "key"
 keywords: ["rb login", "rendobar cli auth", "rendobar api key", "rendobar oauth", "rb whoami"]
+canonical: "https://rendobar.com/docs/cli/authentication"
 ---
 
 <script
diff --git a/cli/ci-cd.mdx b/cli/ci-cd.mdx
index 449e5ed..aa8a70a 100644
--- a/cli/ci-cd.mdx
+++ b/cli/ci-cd.mdx
@@ -4,6 +4,7 @@ description: "Install rb in GitHub Actions, GitLab CI, or Docker. Authenticate f
 sidebarTitle: "CI/CD"
 icon: "infinity"
 keywords: ["rendobar github actions", "rendobar cli ci", "rendobar gitlab", "rendobar docker", "rb ci secret"]
+canonical: "https://rendobar.com/docs/cli/ci-cd"
 ---
 
 <script
diff --git a/cli/commands.mdx b/cli/commands.mdx
index 3b982a7..4d64cdb 100644
--- a/cli/commands.mdx
+++ b/cli/commands.mdx
@@ -5,6 +5,7 @@ sidebarTitle: "Commands"
 icon: "list"
 keywords: ["rb commands", "rendobar cli reference", "rb ffmpeg flags", "rb exit codes", "rb doctor"]
 mode: "wide"
+canonical: "https://rendobar.com/docs/cli/commands"
 ---
 
 <script
diff --git a/cli/installation.mdx b/cli/installation.mdx
index 4363819..db433bc 100644
--- a/cli/installation.mdx
+++ b/cli/installation.mdx
@@ -3,6 +3,7 @@ title: "Install the CLI"
 description: "Install the rb binary on macOS, Linux, or Windows in one command. Pin a version, change the install path, run inside Docker, or uninstall."
 icon: "download"
 keywords: ["install rendobar cli", "rb install", "rendobar windows install", "rendobar docker", "rb doctor"]
+canonical: "https://rendobar.com/docs/cli/installation"
 ---
 
 <script
diff --git a/cli/overview.mdx b/cli/overview.mdx
index 107d541..201d301 100644
--- a/cli/overview.mdx
+++ b/cli/overview.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Overview"
 description: "Run FFmpeg in the cloud from your terminal. Pass real ffmpeg flags; the CLI uploads local files, runs the job, and downloads the result."
 icon: "terminal"
 keywords: ["rb cli", "rendobar command line", "ffmpeg cli", "cloud ffmpeg", "rb ffmpeg"]
+canonical: "https://rendobar.com/docs/cli/overview"
 ---
 
 <script
diff --git a/cli/troubleshooting.mdx b/cli/troubleshooting.mdx
index cb67c27..a3aa589 100644
--- a/cli/troubleshooting.mdx
+++ b/cli/troubleshooting.mdx
@@ -4,6 +4,7 @@ description: "Fix common rb CLI errors: install failures, PATH issues, port conf
 sidebarTitle: "Troubleshooting"
 icon: "stethoscope"
 keywords: ["rb cli error", "rendobar cli not found", "rendobar login failed", "rb doctor", "rb update failed"]
+canonical: "https://rendobar.com/docs/cli/troubleshooting"
 ---
 
 <script
diff --git a/concepts/credits.mdx b/concepts/credits.mdx
index 1bc963c..715436c 100644
--- a/concepts/credits.mdx
+++ b/concepts/credits.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Credits"
 description: "Get per-job nanodollar billing from a prepaid balance. Free plan grants $5, Pro is $9/mo. Credits never expire. Every terminal job pays actual compute."
 icon: "coins"
 keywords: ["credit-based billing", "nanodollar pricing", "rendobar credits", "video api credits", "prepaid balance"]
+canonical: "https://rendobar.com/docs/concepts/credits"
 ---
 
 <script
diff --git a/concepts/job-lifecycle.mdx b/concepts/job-lifecycle.mdx
index 2bb99f8..5845859 100644
--- a/concepts/job-lifecycle.mdx
+++ b/concepts/job-lifecycle.mdx
@@ -4,6 +4,7 @@ description: "View job status transitions across 6 states from waiting to comple
 sidebarTitle: "Job lifecycle"
 icon: "rotate"
 keywords: ["job lifecycle", "job status", "waiting complete failed", "video processing job states", "rendobar status"]
+canonical: "https://rendobar.com/docs/concepts/job-lifecycle"
 ---
 
 <script
diff --git a/concepts/job-output.mdx b/concepts/job-output.mdx
index 5d32fa6..94f6185 100644
--- a/concepts/job-output.mdx
+++ b/concepts/job-output.mdx
@@ -4,6 +4,7 @@ description: "Read the output shape every Rendobar job returns: data, file, file
 sidebarTitle: "Job output"
 icon: "box-open"
 keywords: ["job output", "output shape", "output.data", "output.file", "output.files", "file type enum", "rendobar response"]
+canonical: "https://rendobar.com/docs/concepts/job-output"
 ---
 
 <script
diff --git a/guides/ffmpeg.mdx b/guides/ffmpeg.mdx
index df144c2..c22c43e 100644
--- a/guides/ffmpeg.mdx
+++ b/guides/ffmpeg.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "FFmpeg"
 description: "Run any FFmpeg command in the cloud. ~120 whitelisted flags, 8-layer sandboxed execution, signed download URL. Same FFmpeg syntax you know."
 icon: "terminal"
 keywords: ["ffmpeg guide", "ffmpeg in cloud", "ffmpeg sandboxed execution", "ffmpeg flags whitelist", "ffmpeg command api"]
+canonical: "https://rendobar.com/docs/guides/ffmpeg"
 ---
 
 <script
diff --git a/guides/webhooks.mdx b/guides/webhooks.mdx
index 5362d7c..591629f 100644
--- a/guides/webhooks.mdx
+++ b/guides/webhooks.mdx
@@ -4,6 +4,7 @@ description: "Receive job status events via signed HMAC POST. Setup, payload for
 sidebarTitle: "Webhooks"
 icon: "bell"
 keywords: ["webhooks", "hmac signature", "job status webhook", "rendobar webhook setup", "signed webhook"]
+canonical: "https://rendobar.com/docs/guides/webhooks"
 ---
 
 <script
diff --git a/job-types/caption-burn.mdx b/job-types/caption-burn.mdx
index eca6847..1156430 100644
--- a/job-types/caption-burn.mdx
+++ b/job-types/caption-burn.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "caption.burn"
 description: "Burn styled subtitles into a video from an SRT, VTT, or ASS file, or auto-transcribe in any language. Web-hex styling, deterministic sizing."
 icon: "closed-captioning"
 tag: "Live"
+canonical: "https://rendobar.com/docs/job-types/caption-burn"
 ---
 
 <Check>
diff --git a/job-types/captions-animate.mdx b/job-types/captions-animate.mdx
index d8b9bd5..cd2d11d 100644
--- a/job-types/captions-animate.mdx
+++ b/job-types/captions-animate.mdx
@@ -4,6 +4,7 @@ description: "Burn animated word-level captions onto a video at $0.10/min. Pick
 icon: "captions"
 tag: "Live"
 keywords: ["animated captions", "burn subtitles", "auto captions", "tiktok captions", "subtitles", "captions.animate"]
+canonical: "https://rendobar.com/docs/job-types/captions-animate"
 ---
 
 <script
diff --git a/job-types/ffmpeg.mdx b/job-types/ffmpeg.mdx
index 6f153f6..334f877 100644
--- a/job-types/ffmpeg.mdx
+++ b/job-types/ffmpeg.mdx
@@ -5,6 +5,7 @@ description: "Execute a custom FFmpeg command via API with ~120 whitelisted flag
 icon: "terminal"
 tag: "Live"
 keywords: ["ffmpeg api reference", "ffmpeg cloud", "ffmpeg sandboxed", "ffmpeg rest api", "ffmpeg command api"]
+canonical: "https://rendobar.com/docs/job-types/ffmpeg"
 ---
 
 <script
diff --git a/mcp/examples.mdx b/mcp/examples.mdx
index 781a25b..dfb13db 100644
--- a/mcp/examples.mdx
+++ b/mcp/examples.mdx
@@ -4,6 +4,7 @@ description: "Build a captioned video with Claude Desktop in 8 minutes. Install
 sidebarTitle: "Examples"
 icon: "play"
 keywords: ["mcp example", "claude desktop video", "burn captions agent", "rendobar mcp tutorial", "ai video agent"]
+canonical: "https://rendobar.com/docs/mcp/examples"
 ---
 
 <script
diff --git a/mcp/installation.mdx b/mcp/installation.mdx
index 2d581f1..49e4d07 100644
--- a/mcp/installation.mdx
+++ b/mcp/installation.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Installation"
 description: "Configure the local stdio MCP server for Claude Desktop, Cursor, Cline, Windsurf, Zed, VS Code, Claude Code, or Continue. Takes 2 minutes."
 icon: "download"
 keywords: ["install rendobar mcp", "claude desktop config", "cursor mcp install", "npx rendobar mcp", "windsurf mcp"]
+canonical: "https://rendobar.com/docs/mcp/installation"
 ---
 
 <script
diff --git a/mcp/overview.mdx b/mcp/overview.mdx
index 6ce5bda..2504067 100644
--- a/mcp/overview.mdx
+++ b/mcp/overview.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Overview"
 description: "Connect AI agents via two transports: a local stdio server for IDE clients (Claude Desktop, Cursor) and a remote HTTP server for web and mobile."
 icon: "plug"
 keywords: ["mcp server", "model context protocol", "claude desktop mcp", "cursor mcp", "ai agent video tools", "rendobar mcp"]
+canonical: "https://rendobar.com/docs/mcp/overview"
 ---
 
 <script
diff --git a/mcp/tools.mdx b/mcp/tools.mdx
index 4b0ae53..81157fe 100644
--- a/mcp/tools.mdx
+++ b/mcp/tools.mdx
@@ -4,6 +4,7 @@ description: "View schemas, parameters, response shapes, and annotations for the
 sidebarTitle: "Tools reference"
 icon: "wrench"
 keywords: ["mcp tools", "submit_job", "get_job", "list_jobs", "probe_media", "upload_media", "upload_file"]
+canonical: "https://rendobar.com/docs/mcp/tools"
 ---
 
 <script
diff --git a/mcp/troubleshooting.mdx b/mcp/troubleshooting.mdx
index daf210e..e45f8ec 100644
--- a/mcp/troubleshooting.mdx
+++ b/mcp/troubleshooting.mdx
@@ -4,6 +4,7 @@ description: "Fix common MCP server failures: missing API key, Cursor PATH on ma
 sidebarTitle: "Troubleshooting"
 icon: "wrench"
 keywords: ["rendobar mcp error", "mcp not loading", "claude desktop mcp not working", "cursor mcp path", "mcp api key"]
+canonical: "https://rendobar.com/docs/mcp/troubleshooting"
 ---
 
 <script
diff --git a/mcp/web-and-mobile.mdx b/mcp/web-and-mobile.mdx
index 7d50f1b..a9732b2 100644
--- a/mcp/web-and-mobile.mdx
+++ b/mcp/web-and-mobile.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Web and mobile"
 description: "Connect web and mobile AI clients to the remote HTTP MCP at api.rendobar.com/mcp. Local file uploads require an extra curl step to upload first."
 icon: "globe"
 keywords: ["claude.ai mcp", "chatgpt mcp", "remote mcp server", "rendobar streamable http", "browser mcp"]
+canonical: "https://rendobar.com/docs/mcp/web-and-mobile"
 ---
 
 <script
diff --git a/quickstart.mdx b/quickstart.mdx
index ee1e4c9..863b73f 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Quickstart"
 description: "Submit your first ffmpeg job, poll to completion, and download the result. Under 5 minutes from API key to finished MP4."
 icon: "rocket"
 keywords: ["rendobar quickstart", "ffmpeg api tutorial", "first api call", "video processing quickstart", "ffmpeg job"]
+canonical: "https://rendobar.com/docs/quickstart"
 ---
 
 <script
diff --git a/scripts/add-canonical.mjs b/scripts/add-canonical.mjs
new file mode 100644
index 0000000..a8a25f6
--- /dev/null
+++ b/scripts/add-canonical.mjs
@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// One-off: insert canonical frontmatter into every docs page.
+// canonical = https://rendobar.com/docs/<path-without-.mdx>
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const BASE = 'https://rendobar.com/docs/';
+
+function walkMdx(dir, files = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (['snippets', '.claude', 'node_modules', 'superpowers', '.git'].includes(entry)) continue;
+      walkMdx(full, files);
+    } else if (entry.endsWith('.mdx')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+let changed = 0;
+for (const file of walkMdx(ROOT)) {
+  const content = readFileSync(file, 'utf8');
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(eol);
+  if (lines[0] !== '---') { console.error(`SKIP no frontmatter: ${file}`); continue; }
+  const close = lines.indexOf('---', 1);
+  if (close === -1) { console.error(`SKIP unterminated frontmatter: ${file}`); continue; }
+  const slug = relative(ROOT, file).replace(/\\/g, '/').replace(/\.mdx$/, '');
+  const canonical = `canonical: "${BASE}${slug}"`;
+  const existing = lines.findIndex((l, i) => i > 0 && i < close && l.startsWith('canonical:'));
+  if (existing !== -1) {
+    if (lines[existing] === canonical) continue;
+    lines[existing] = canonical;
+  } else {
+    lines.splice(close, 0, canonical);
+  }
+  writeFileSync(file, lines.join(eol));
+  changed++;
+  console.log(`${slug} -> ${BASE}${slug}`);
+}
+console.log(`Done. ${changed} files updated.`);
diff --git a/scripts/validate-frontmatter.mjs b/scripts/validate-frontmatter.mjs
index c2dc497..d36e96a 100644
--- a/scripts/validate-frontmatter.mjs
+++ b/scripts/validate-frontmatter.mjs
@@ -6,6 +6,9 @@
  * - title: 13-52 chars, sentence case, no em/en-dash, no pipe, no --, no "Rendobar"
  * - description: 100-160 chars, starts with allowed action verb, no em-dash, no "Rendobar" prefix
  * - description must be present on every page (except snippets)
+ * - canonical: must equal https://rendobar.com/docs/<page-path>. Mintlify's
+ *   auto-canonical drops the /docs subpath on the rendobar.mintlify.app
+ *   subdomain (points at a 404), so every page pins its canonical explicitly.
  *
  * Exit 0 = all pass. Exit 1 = at least one violation.
  */
@@ -148,6 +151,21 @@ function validate(filePath, fm, violations) {
       });
     }
   }
+
+  // --- Canonical checks ---
+  const expectedCanonical =
+    'https://rendobar.com/docs/' + rel.replace(/\\/g, '/').replace(/\.mdx$/, '');
+  if (!fm.canonical) {
+    violations.push({
+      file: rel, field: 'canonical',
+      message: `Missing canonical field (expected "${expectedCanonical}")`,
+    });
+  } else if (fm.canonical !== expectedCanonical) {
+    violations.push({
+      file: rel, field: 'canonical',
+      message: `Canonical "${fm.canonical}" does not match expected "${expectedCanonical}"`,
+    });
+  }
 }
 
 function main() {
diff --git a/support/errors.mdx b/support/errors.mdx
index 4f81fd0..cda1c53 100644
--- a/support/errors.mdx
+++ b/support/errors.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Error codes"
 description: "View 13 API error codes, their HTTP status, and recommended action. Errors follow the {error: {code, message}} envelope on every endpoint."
 icon: "triangle-exclamation"
 keywords: ["rendobar error codes", "api error reference", "ffmpeg error troubleshooting", "insufficient credits", "rate limited"]
+canonical: "https://rendobar.com/docs/support/errors"
 ---
 
 <script
diff --git a/support/faq.mdx b/support/faq.mdx
index d9c8460..90fab14 100644
--- a/support/faq.mdx
+++ b/support/faq.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "FAQ"
 description: "Get quick answers about Rendobar pricing, supported formats, AI agent access, rate limits, and what counts as a failed job."
 icon: "circle-question"
 keywords: ["rendobar faq", "video api faq", "rendobar pricing faq", "ffmpeg api questions"]
+canonical: "https://rendobar.com/docs/support/faq"
 ---
 
 <script
diff --git a/support/limits.mdx b/support/limits.mdx
index a4fc3ce..7168a01 100644
--- a/support/limits.mdx
+++ b/support/limits.mdx
@@ -4,6 +4,7 @@ sidebarTitle: "Limits"
 description: "Compare Free and Pro plan limits across rate limits (30 vs 300/min), file size caps (100 MB vs 2 GB), retention, concurrency, storage."
 icon: "gauge"
 keywords: ["rendobar limits", "api rate limits", "plan limits", "file size limit", "concurrent jobs"]
+canonical: "https://rendobar.com/docs/support/limits"
 ---
 
 <script