Automated SEO fixes: improve docs link anchors by rachaelrenk · Pull Request #169 · warpdotdev/docs

rachaelrenk · 2026-06-02T17:33:17Z

Summary

Applies Petra’s SEO link audit to docs by replacing redirecting URLs, raw or generic link text, and gaps on under-linked docs pages.
Improves link quality across docs, guides, changelog entries, and enterprise pages with descriptive anchors, contextual link intros, and more natural sentence structure.
Adds specific title props to VideoEmbed components so embeds have meaningful metadata for accessibility and SEO.
Adds style guide guidance and style_lint checks so future docs updates catch link and embed issues before review.

What changed

SEO link cleanup

Updated redirecting URLs to final destinations, including Warp marketing, legal, pricing, blog, and Oz web app links.
Replaced raw URL anchors and generic anchors like "here," "learn more," and "this page" with descriptive link text.
Added contextual internal links to improve discoverability for under-linked docs pages.

Video embeds

Added missing VideoEmbed title props across the docs.
Refined generic video titles into specific descriptions that identify the feature, workflow, integration, or task shown.

Review follow-ups and wording polish

Removed redundant bold prefixes where the link text already provided the needed context.
Added missing articles before named destination pages, such as the Runs page in the Oz web app.
Tightened awkward wording from 1:1 link replacements around the Oz web app, Warp pricing, login, admin, download, contact, and related destination links.

Style guide and linting

Expanded the docs style guide with rules for descriptive anchors, contextual link sentences, raw URL anchors, redundant prefixes, destination-page articles, and specific VideoEmbed titles.
Added style_lint checks for link anchor quality, link context quality, and VideoEmbed title coverage/specificity.
Updated changed-file linting behavior so PR-focused runs skip changelog files consistently with the full audit.

Validation

Targeted SEO scan: TOTAL_ISSUES=0
npm run build: passed
python3 -m py_compile .agents/skills/style_lint/style_lint.py: passed
python3 .agents/skills/style_lint/style_lint.py --changed --output /tmp/style-lint-link-quality.json: passed
git --no-pager diff --check: passed
trunk check: skipped because Trunk is not installed locally

Artifacts

Co-Authored-By: Oz oz-agent@warp.dev

Replace redirecting URLs, improve generic link anchors, add VideoEmbed titles, and add contextual internal links for under-linked docs pages. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-06-02T17:33:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 3, 2026 12:49am

oz-for-oss · 2026-06-02T17:33:35Z

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR applies broad documentation SEO cleanup by replacing redirecting or raw URLs, adding descriptive anchors, and filling in missing VideoEmbed titles. I did not find broken internal links in the changed additions, security concerns, or spec drift; spec_context.md is empty for this run.

Concerns

Several automated rewrites still leave generic or awkward link/video labels that do not fully achieve the SEO/accessibility goal.
No security findings.

Verdict

Found: 0 critical, 0 important, 3 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-06-02T17:38:21Z

 :::

-<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" />
+<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" title="Codebase Context video 1" />


💡 [SUGGESTION] Codebase Context video 1 is still a generic numbered title, so it gives screen readers and search snippets little context about this embed.

Suggested change

<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" title="Codebase Context video 1" />

<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" title="Managing Codebase Context indexing in Warp" />

Remove redundant vendor prefixes from web search documentation links so the bullets jump directly to descriptive anchors. Co-Authored-By: Oz <oz-agent@warp.dev>

Make VideoEmbed title attributes more specific and clean up Oz web app link copy in integration quickstarts. Validation: npm run build passed locally. Co-Authored-By: Oz <oz-agent@warp.dev>

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>

Document link treatment standards in the docs style guide and extend style_lint to flag generic anchors, raw URL link text, redundant link prefixes, named-page article issues, and missing or generic VideoEmbed titles. Co-Authored-By: Oz <oz-agent@warp.dev>

Clean up awkward link phrasing from SEO anchor updates, including missing articles, duplicated Oz web app wording, and pricing/login destination language. Co-Authored-By: Oz <oz-agent@warp.dev>

rachaelrenk · 2026-06-02T20:15:49Z

/oz-review

oz-for-oss · 2026-06-02T20:16:08Z

@rachaelrenk

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR applies broad SEO-oriented documentation link cleanup, adds VideoEmbed titles, and extends the docs style lint skill with link and embed-title checks. The changes are functional overall, and I did not find security issues or spec-drift concerns; spec_context.md was empty.

Concerns

A few changed link rewrites still violate the new link guidance by omitting required articles or repeating list prefixes that the new linter flags.
One changed file still contains a raw URL anchor in the same resource list being cleaned up; the inline suggestion fixes that hunk, and similar pre-existing raw URL anchors outside commentable lines can be handled in a follow-up pass.

Verdict

Found: 0 critical, 0 important, 4 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-06-02T20:22:18Z

 The simplest way to set up the integration is **using the Oz web app**:

-1. Navigate to the Oz web app at [oz.warp.dev/integrations](https://oz.warp.dev/integrations).
+1. Navigate to the Oz web app at [Integrations page in the Oz web app](https://oz.warp.dev/integrations).


💡 [SUGGESTION] This link text needs the article required by the new style guide, and removing the extra "Oz web app at" avoids repeating the destination.

Suggested change

1. Navigate to the Oz web app at [Integrations page in the Oz web app](https://oz.warp.dev/integrations).

1. Navigate to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations).

oz-for-oss · 2026-06-02T20:22:19Z

+* **Privacy policy** - [Warp privacy policy](https://www.warp.dev/legal/privacy-policy)
 * **Trust center** - [trust.warp.dev](https://trust.warp.dev) — security documentation and compliance reports. See also [Trust Center](/enterprise/security-and-compliance/trust-center/) for details on requesting SOC 2 reports, subprocessors, and vendor security assessments.
-* **Subprocessors** - [warp.dev/legal/subprocessors](https://www.warp.dev/legal/subprocessors)
+* **Subprocessors** - [Warp subprocessors list](https://www.warp.dev/legal/subprocessors)


💡 [SUGGESTION] These resource links still trip the new link-context/raw-URL checks; make the links themselves the list items and name the Trust Center destination.

Suggested change

* **Privacy policy** - [Warp privacy policy](https://www.warp.dev/legal/privacy-policy)

* **Trust center** - [trust.warp.dev](https://trust.warp.dev) — security documentation and compliance reports. See also [Trust Center](/enterprise/security-and-compliance/trust-center/) for details on requesting SOC 2 reports, subprocessors, and vendor security assessments.

* **Subprocessors** - [warp.dev/legal/subprocessors](https://www.warp.dev/legal/subprocessors)

* **Subprocessors** - [Warp subprocessors list](https://www.warp.dev/legal/subprocessors)

* [Warp privacy policy](https://www.warp.dev/legal/privacy-policy)

* [Warp Trust Center](https://trust.warp.dev) — security documentation and compliance reports. See also [Trust Center](/enterprise/security-and-compliance/trust-center/) for details on requesting SOC 2 reports, subprocessors, and vendor security assessments.

* [Warp subprocessors list](https://www.warp.dev/legal/subprocessors)

oz-for-oss · 2026-06-02T20:22:19Z

 ## 1. Install Warp

-Download Warp from [warp.dev](https://www.warp.dev/download) and follow the installer for your platform.
+Download Warp from [Warp download page](https://www.warp.dev/download) and follow the installer for your platform.


💡 [SUGGESTION] Add the article before this named destination page to match the new guidance.

Suggested change

Download Warp from [Warp download page](https://www.warp.dev/download) and follow the installer for your platform.

Download Warp from the [Warp download page](https://www.warp.dev/download) and follow the installer for your platform.

oz-for-oss · 2026-06-02T20:22:19Z

  </TabItem>
  <TabItem label="Linux">
-    Download the package for your distribution from [warp.dev/download](https://www.warp.dev/download). For Debian/Ubuntu:
+    Download the package for your distribution from [Warp download page](https://www.warp.dev/download). For Debian/Ubuntu:


💡 [SUGGESTION] Add the article before this named destination page to match the new guidance.

Suggested change

Download the package for your distribution from [Warp download page](https://www.warp.dev/download). For Debian/Ubuntu:

Download the package for your distribution from the [Warp download page](https://www.warp.dev/download). For Debian/Ubuntu:

Co-Authored-By: Oz <oz-agent@warp.dev>

hongyi-chen

nice fixes!

Improve docs link SEO

56ae035

Replace redirecting URLs, improve generic link anchors, add VideoEmbed titles, and add contextual internal links for under-linked docs pages. Co-Authored-By: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label Jun 2, 2026

rachaelrenk self-assigned this Jun 2, 2026

Merge branch 'main' into docs/seo-link-cleanup

da23cf9

vercel Bot deployed to Preview June 2, 2026 17:36 View deployment

oz-for-oss Bot reviewed Jun 2, 2026

View reviewed changes

Simplify web search documentation links

342b31e

Remove redundant vendor prefixes from web search documentation links so the bullets jump directly to descriptive anchors. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 2, 2026 18:43 View deployment

Refine video titles for docs SEO

fcbdf65

Make VideoEmbed title attributes more specific and clean up Oz web app link copy in integration quickstarts. Validation: npm run build passed locally. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 2, 2026 18:58 View deployment

Apply suggestions from code review

38e18d4

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>

vercel Bot deployed to Preview June 2, 2026 19:01 View deployment

Add docs link quality linting

9c13d61

Document link treatment standards in the docs style guide and extend style_lint to flag generic anchors, raw URL link text, redundant link prefixes, named-page article issues, and missing or generic VideoEmbed titles. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 2, 2026 19:47 View deployment

Refine docs link wording

66908a9

Clean up awkward link phrasing from SEO anchor updates, including missing articles, duplicated Oz web app wording, and pricing/login destination language. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 2, 2026 20:12 View deployment

oz-for-oss Bot reviewed Jun 2, 2026

View reviewed changes

Address review link wording suggestions

3d265fa

Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview June 2, 2026 20:30 View deployment

Merge branch 'main' into docs/seo-link-cleanup

6e26a6a

hongyi-chen approved these changes Jun 3, 2026

View reviewed changes

vercel Bot deployed to Preview June 3, 2026 00:49 View deployment

	<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" title="Codebase Context video 1" />
	<VideoEmbed url="https://youtu.be/11rz9OYQ8Hg" title="Managing Codebase Context indexing in Warp" />

	1. Navigate to the Oz web app at [Integrations page in the Oz web app](https://oz.warp.dev/integrations).
	1. Navigate to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations).

	Download Warp from [Warp download page](https://www.warp.dev/download) and follow the installer for your platform.
	Download Warp from the [Warp download page](https://www.warp.dev/download) and follow the installer for your platform.

	Download the package for your distribution from [Warp download page](https://www.warp.dev/download). For Debian/Ubuntu:
	Download the package for your distribution from the [Warp download page](https://www.warp.dev/download). For Debian/Ubuntu:

Conversation

rachaelrenk commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

SEO link cleanup

Video embeds

Review follow-ups and wording polish

Style guide and linting

Validation

Artifacts

Uh oh!

vercel Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rachaelrenk commented Jun 2, 2026

Uh oh!

oz-for-oss Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rachaelrenk commented Jun 2, 2026 •

edited

Loading

vercel Bot commented Jun 2, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 2, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 2, 2026 •

edited

Loading