Skip to content

docs: improve SEO for homepage title and description#1191

Merged
codyjlandstrom merged 2 commits intomainfrom
docs/seo-review-2026-04-08
Apr 21, 2026
Merged

docs: improve SEO for homepage title and description#1191
codyjlandstrom merged 2 commits intomainfrom
docs/seo-review-2026-04-08

Conversation

@ekline
Copy link
Copy Markdown
Contributor

@ekline ekline Bot commented Apr 8, 2026

Context

This PR addresses an SEO issue identified by auditing the documentation (130 pages) against Okteto's keyword strategy derived from the marketing website.

Keyword map

Primary keywords identified from okteto.com:

  • cloud development environment / cloud development environments
  • Kubernetes development environment
  • development platform
  • Okteto Platform, Okteto CLI, Okteto Manifest
  • preview environments, remote development

Secondary keywords:

  • inner loop development, development velocity, platform engineering
  • developer self-service, golden paths, live updates

Audience terms: platform engineers, platform teams, developers

Top 3 findings

Rank Priority Page Issue Proposed fix
1 High src/content/index.md Homepage title "Welcome to Okteto!" (18 chars) contains zero target keywords. Description is 76 chars — under the 120-160 sweet spot. Fixed in this PR — Title → Okteto docs - cloud development environments for Kubernetes (60 chars). Description expanded to 149 chars with keywords.
2 High src/content/self-hosted/install/certificates/cert-manager.mdx Truncated title: "Setting up certificates with" — missing the subject (cert-manager). Follow-up
3 Medium src/content/reference/index.mdx Title is only "References" (10 chars), no description field. Key navigation page. Follow-up

What this PR fixes

The docs homepage (src/content/index.md) is the single most important page for search rankings. The title "Welcome to Okteto!" and short description contained none of Okteto's target keywords.

Changes (frontmatter only — no content changes):

  • Title: Welcome to Okteto!Okteto docs - cloud development environments for Kubernetes (60 chars, includes two primary keywords)
  • Description: Expanded from 76 to 149 chars, now includes "cloud development environments", "Kubernetes", and action-oriented language

Remaining items

  • Fix truncated title on cert-manager.mdx ("Setting up certificates with" — incomplete)
  • Add title and description to reference/index.mdx
  • 8 pages missing descriptions entirely
  • 27 pages with titles under 30 characters
  • 3 sets of duplicate titles (GitHub, Volume Snapshots, Registry Credentials)
  • ~85 pages where titles lack keyword alignment

Audit summary

Metric Count
Pages scanned 130
Pages missing descriptions 8
Duplicate title sets 3 (6 pages)
Titles under 30 chars 27
Descriptions under 120 chars 30
Title keyword alignment gaps ~85

How to verify

  1. Check that the updated frontmatter renders correctly: npm start and visit the docs homepage
  2. Confirm the page title and meta description appear correctly in the browser tab and page source

@netlify
Copy link
Copy Markdown

netlify Bot commented Apr 8, 2026

Deploy Preview for okteto-docs ready!

Name Link
🔨 Latest commit 16ab4db
🔍 Latest deploy log https://app.netlify.com/projects/okteto-docs/deploys/69e7e39322bd0c00082b55ab
😎 Deploy Preview https://deploy-preview-1191--okteto-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Replace Ekline's category-generic title and filler description with
language that reflects Okteto's actual ICP and company direction:
developer platform for human and AI teams, covering dev environments,
preview environments, testing, and AI-native workflows.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@codyjlandstrom codyjlandstrom merged commit 6f2f0a1 into main Apr 21, 2026
4 checks passed
@codyjlandstrom codyjlandstrom deleted the docs/seo-review-2026-04-08 branch April 21, 2026 20:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant