From 8a34c7be3e03a4ac8fed3fa882970969b98fdf20 Mon Sep 17 00:00:00 2001 From: petradonka Date: Fri, 15 May 2026 07:02:48 +0000 Subject: [PATCH 1/2] Automated SEO fixes: resolve title_too_short on artifacts CLI reference Update frontmatter title from 'Artifacts' to 'Artifact commands' to meet the 20-char minimum for tags. Sidebar label remains 'Artifacts'. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/reference/cli/artifacts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/reference/cli/artifacts.mdx b/src/content/docs/reference/cli/artifacts.mdx index b497da97..6fad2c85 100644 --- a/src/content/docs/reference/cli/artifacts.mdx +++ b/src/content/docs/reference/cli/artifacts.mdx @@ -1,5 +1,5 @@ --- -title: Artifacts +title: Artifact commands description: >- Get metadata for and download files produced by an Oz agent run using the `oz artifact` subcommands. From 79a022c3b5d27f7f2308fe585de7d9b3ecbc2adb Mon Sep 17 00:00:00 2001 From: Petra Donka <donkapetra@gmail.com> Date: Fri, 15 May 2026 12:25:14 +0200 Subject: [PATCH 2/2] docs: preserve artifacts title and fix API reference Co-Authored-By: Oz <oz-agent@warp.dev> --- .agents/skills/docs-seo-audit/SKILL.md | 13 +++-- .../docs-seo-audit/scripts/seo_audit.py | 19 ++++++- src/components/WarpTopbar.astro | 56 +++++++++++++------ src/content/docs/reference/cli/artifacts.mdx | 2 +- src/pages/api.astro | 14 ++++- 5 files changed, 77 insertions(+), 27 deletions(-) diff --git a/.agents/skills/docs-seo-audit/SKILL.md b/.agents/skills/docs-seo-audit/SKILL.md index f658602d..74506f79 100644 --- a/.agents/skills/docs-seo-audit/SKILL.md +++ b/.agents/skills/docs-seo-audit/SKILL.md @@ -3,14 +3,14 @@ name: docs-seo-audit description: >- Audit docs.warp.dev for SEO issues like duplicate titles, missing meta descriptions, title length problems, and H1 tag issues. Crawls the live - sitemap, generates a report, and fixes issues in the source markdown. Use + sitemap, generates a report, and fixes issues in the source files. Use when asked to check SEO, fix duplicate titles, audit meta tags, improve search rankings, or run an SEO check on the docs site. --- # SEO Audit -Crawl the live docs.warp.dev sitemap to find SEO issues and fix them in the source markdown files. +Crawl the live docs.warp.dev sitemap to find SEO issues and fix them in the source files. ## Running the audit @@ -48,7 +48,7 @@ The JSON report contains: Each issue includes: - `url` — The live page URL -- `source_file` — The local markdown file (if `--repo-root` was provided) +- `source_file` — The local source file (if `--repo-root` was provided) - `severity` — `error` (must fix), `warning` (should fix), or `info` (nice to fix) - `type` — Issue category (see below) - `message` — Human-readable description @@ -145,6 +145,7 @@ Some page titles are intentionally short or specific and must **not** be changed - **`src/content/docs/terminal/windows/split-panes.mdx`** (`Split panes`) — Same rationale: the section header disambiguates the terminal context. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal split panes". - **`src/content/docs/terminal/windows/tab-configs.mdx`** (`Tab Configs`) — Same rationale: the section header disambiguates the terminal context. Additionally, "Tab Configs" is a proper feature name and should not be prefixed. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal Tab Configs". - **`src/content/docs/terminal/sessions/index.mdx`** (`Sessions`) — The sidebar section header ("Sessions") already provides terminal context. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal sessions". +- **`src/content/docs/reference/cli/artifacts.mdx`** (`Artifacts`) — The Reference > CLI section provides context, and "Artifacts" matches the `oz artifact` resource that the page documents. The `title_too_short` warning is intentionally suppressed. When the audit flags these pages for `title_too_short`, exclude them from your fix list and include a note in your report explaining they are intentional exceptions. @@ -244,7 +245,7 @@ If instructed to send a report to Slack, post a summary after the audit complete **Categorizing issues in the summary:** Before composing the message, cross-reference every issue against the title exceptions list above and check whether the issue has a local source file. Classify each issue into exactly one bucket: - **Fixed** — issues you resolved in this run -- **Unfixable** — issues with no local source file (e.g., auto-generated API pages) +- **Unfixable** — issues with no local source file - **Allowlisted** — issues that match a title exception entry (these are intentional, not problems) - **Remaining** — everything else (genuine issues that still need attention) @@ -261,7 +262,7 @@ Only include a section in the Slack message if its count is > 0. Never list allo • Trimmed 3 overly long descriptions to ≤160 chars *Unfixable (<count>):* -• <N> pages missing meta descriptions (auto-generated, no local source) +• <N> pages missing meta descriptions (no local source) *Allowlisted (<count>):* • <page1>, <page2>, <page3> (intentionally short titles) @@ -287,7 +288,7 @@ PR: <pr_url> <total_pages> pages scanned | <total_issues> issues found (<errors> errors, <warnings> warnings, <info> info) *Unfixable (<count>):* -• <N> pages missing meta descriptions (auto-generated, no local source) +• <N> pages missing meta descriptions (no local source) *Allowlisted (<count>):* • <page1>, <page2> (intentionally short titles) diff --git a/.agents/skills/docs-seo-audit/scripts/seo_audit.py b/.agents/skills/docs-seo-audit/scripts/seo_audit.py index bd7ac48c..e1da7f44 100644 --- a/.agents/skills/docs-seo-audit/scripts/seo_audit.py +++ b/.agents/skills/docs-seo-audit/scripts/seo_audit.py @@ -192,12 +192,15 @@ def extract_seo(url): # --------------------------------------------------------------------------- def url_to_source_path(url, repo_root): - """Best-effort mapping from a live URL to the local markdown source file. + """Best-effort mapping from a live URL to the local source file. Astro Starlight serves content from src/content/docs/. URL paths map directly to that directory. Files use .mdx (preferred) or .md extensions, and directory landing pages are index.mdx (not README.md). + Standalone Astro routes are served from src/pages/ and can be edited + directly even when their content is generated from a spec or runtime data. + Returns the relative path from repo_root, or None if no file is found. """ from urllib.parse import urlparse @@ -225,6 +228,20 @@ def url_to_source_path(url, repo_root): candidate = os.path.join(base, path, "index" + ext) if os.path.isfile(candidate): return os.path.relpath(candidate, repo_root) + # Standalone Astro routes live outside Starlight content in src/pages/. + # This maps pages like /api/ -> src/pages/api.astro and + # /openapi.yaml -> src/pages/openapi.yaml.ts so generated docs shells + # are treated as locally fixable when their source exists. + pages_base = os.path.join(repo_root, "src", "pages") + for ext in (".astro", ".ts", ".js", ".tsx", ".jsx"): + candidate = os.path.join(pages_base, path + ext) + if os.path.isfile(candidate): + return os.path.relpath(candidate, repo_root) + + for ext in (".astro", ".ts", ".js", ".tsx", ".jsx"): + candidate = os.path.join(pages_base, path, "index" + ext) + if os.path.isfile(candidate): + return os.path.relpath(candidate, repo_root) return None diff --git a/src/components/WarpTopbar.astro b/src/components/WarpTopbar.astro index 28d98ab0..0b8a6ff9 100644 --- a/src/components/WarpTopbar.astro +++ b/src/components/WarpTopbar.astro @@ -1,8 +1,8 @@ --- /** * Slim Warp brand topbar for standalone pages that don't sit inside Starlight - * (currently just `/api`). Renders the Warp wordmark + a breadcrumb + a small - * nav so the page reads as part of the same surface as the docs. + * (currently just `/api`). Renders the Warp wordmark + docs breadcrumb + a + * small nav so the page reads as part of the same surface as the docs. * * The host page must reserve `--warp-topbar-height` (3.5rem by default) at * the top of the viewport — see `src/pages/api.astro` where the same value @@ -44,23 +44,21 @@ const { --- <header class="warp-topbar" role="banner"> - {/* Wordmark links to warp.dev (matches CustomSiteTitle.astro on Starlight - pages). Users still get to docs root via the explicit "← Docs" link in - the right nav below. */} - <a href="https://warp.dev" class="warp-topbar__home" aria-label="Visit warp.dev"> - <span class="warp-topbar__logo warp-topbar__logo--dark" aria-hidden="true" set:html={logoDark} /> - <span class="warp-topbar__logo warp-topbar__logo--light" aria-hidden="true" set:html={logoLight} /> + <div class="warp-topbar__left"> + {/* Wordmark links to warp.dev (matches CustomSiteTitle.astro on Starlight + pages). Users get to docs root via the adjacent "← Docs" breadcrumb. */} + <a href="https://warp.dev" class="warp-topbar__home" aria-label="Visit warp.dev"> + <span class="warp-topbar__logo warp-topbar__logo--dark" aria-hidden="true" set:html={logoDark} /> + <span class="warp-topbar__logo warp-topbar__logo--light" aria-hidden="true" set:html={logoLight} /> + </a> + <a href="/" class="warp-topbar__docs"> + <span>Docs</span> + </a> <span class="warp-topbar__sep" aria-hidden="true">/</span> <span class="warp-topbar__crumb">{crumb}</span> - </a> + </div> <div class="warp-topbar__right"> <nav class="warp-topbar__nav" aria-label="Site"> - <a href="/" class="warp-topbar__link"> - <svg aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> - <path d="M19 12H5"/><path d="m12 19-7-7 7-7"/> - </svg> - <span>Docs</span> - </a> {links.map((link) => ( <a href={link.href} @@ -123,19 +121,24 @@ const { font-family: var(--scalar-font, 'Inter', sans-serif); color: var(--scalar-color-1, #fafafa); } - .warp-topbar__home { + .warp-topbar__left { display: inline-flex; align-items: center; gap: 0.625rem; + min-width: 0; + } + .warp-topbar__home { + display: inline-flex; + align-items: center; text-decoration: none; color: inherit; - min-width: 0; padding: 0.25rem 0.375rem; margin-left: -0.375rem; border-radius: var(--sl-radius-md); } .warp-topbar__home:hover { background: var(--scalar-background-2); } - .warp-topbar__home:focus-visible { + .warp-topbar__home:focus-visible, + .warp-topbar__docs:focus-visible { outline: 2px solid var(--scalar-color-accent); outline-offset: 2px; } @@ -169,6 +172,23 @@ const { overflow: hidden; text-overflow: ellipsis; } + .warp-topbar__docs { + display: inline-flex; + align-items: center; + gap: 0.375rem; + padding: 0 0.125rem; + text-decoration: none; + color: var(--scalar-color-3); + font-size: 0.8125rem; + font-weight: 500; + line-height: 1.25; + transition: color 0.15s ease; + white-space: nowrap; + border-radius: var(--sl-radius-xs); + } + .warp-topbar__docs:hover { + color: var(--scalar-color-1); + } /* Right group wraps the nav and the theme select so the topbar's `justify-content: space-between` keeps the home/crumb pinned left and the whole right cluster pinned right. */ diff --git a/src/content/docs/reference/cli/artifacts.mdx b/src/content/docs/reference/cli/artifacts.mdx index 6fad2c85..b497da97 100644 --- a/src/content/docs/reference/cli/artifacts.mdx +++ b/src/content/docs/reference/cli/artifacts.mdx @@ -1,5 +1,5 @@ --- -title: Artifact commands +title: Artifacts description: >- Get metadata for and download files produced by an Oz agent run using the `oz artifact` subcommands. diff --git a/src/pages/api.astro b/src/pages/api.astro index 84c4d00c..dc0f183d 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -159,6 +159,17 @@ const specJson = JSON.stringify(specObject); body { background-color: inherit; } + .api-visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; + } </style> </head> <body> @@ -179,6 +190,7 @@ const specJson = JSON.stringify(specObject); })(); </script> <WarpTopbar crumb="API Reference" /> + <h1 class="api-visually-hidden">Warp & Oz HTTP API reference</h1> <script is:inline id="api-reference" @@ -339,7 +351,7 @@ const specJson = JSON.stringify(specObject); } })(); </script> - <script is:inline src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.52.2" integrity="sha384-lQKcRGSJRRAHGfUX6ajRHvcWdCi8lgITkVTftrhsN5rVkWmsjVaW0encVdMEhGhi" crossorigin="anonymous"></script> + <script is:inline src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.57.1" crossorigin="anonymous"></script> <FeedbackButtons question="Was this helpful?" class="api-feedback-widget"