Skip to content

docs: sentence case for headings and titles - #774

Draft
hlenke wants to merge 1 commit into
docs-audit/doc-238-casing-consistencyfrom
docs/sentence-case-headings
Draft

hlenke wants to merge 1 commit into
docs-audit/doc-238-casing-consistencyfrom
docs/sentence-case-headings

Conversation

@hlenke

@hlenke hlenke commented Oct 30, 2026 •

Copy link
Copy Markdown
Member

Follow-up to #734: converts the remaining title-case headings and titles to sentence case. Only the first word and proper nouns keep a capital.

Stacked on #734. The base is docs-audit/doc-238-casing-consistency, so the diff shows only this change. Retarget to main after #734 merges.

What changed

1,846 lines in 369 .mdx files. Only letter case changed: every line has one deletion and one insertion, and lowercasing the old and new lines gives the same text. No slugs, hrefs or anchors changed. Trailing whitespace was removed from 10 of the edited lines (needed for git diff --check).

Kind Count
Markdown headings (#–####) 1,221
Frontmatter title 227
Frontmatter sidebarTitle 119
title props: <Tab> 115, <Card> 68, <Accordion> 66, <Step> 30 279

Kept as is

  • Product and feature names: Checkly, Playwright Check Suites, Rocky AI, Monitoring as Code, Checkly Agent, Checkly Traces, Checkly Skills, AI Assistant, Checkly Detect / Communicate / Resolve.
  • Check and monitor types: the type word stays capitalized and the noun is lowercased (Browser check, Multistep check, Heartbeat monitor, URL monitor).
  • Third-party names and their own product names: GitHub Actions, Microsoft Teams, OpenTelemetry Collector, Node Problem Detector, Playwright Test, Playwright Inspector, Trace Viewer, Visual Studio Code, Claude Code, HashiCorp Vault / Azure Key Vault, AWS Secrets Manager, Heroku Scheduler, Splunk On-Call, Vercel Deployment Protection, Core Web Vitals and the metric names (Largest Contentful Paint, etc.), web API names (Fetch API, File API, Layout Instability API).
  • Acronyms and mixed-case words (API, CLI, SSO, gRPC, OpAMP, P95, V2).
  • Anything in quotes (quoted error messages and UI labels), inline code and construct names.
  • The first word after a colon, a - separator or a full stop (for example "Step 4: Write your first test").
  • <YoutubeEmbed> titles, which mirror the video titles on YouTube.
  • Generated API reference pages (api-reference/** with openapi: frontmatter) and api-reference-old/.

Please check

These are judgment calls, so a quick yes/no would help:

  • Kept capitalized as feature names: Agentic Check(s) (prose mostly writes it this way), AI Assistant, Checkly Skills, Virtual Experience Score, Marketplace (Vercel), Infrastructure as Code.
  • Lowercased as generic: Playwright reporter, MCP server ("Checkly MCP server"), dev image, status pages, private locations, real user monitoring.

docs.json navigation labels: not changed

Navigation is high-visibility, so I left docs.json alone. 72 group/tab labels are in title case. Should they be converted?

  • Docs groups: Getting Started, Private Locations, Team Management, Uptime Monitoring, Synthetic Monitoring, Status Pages, Agent Resources, MCP Server, Alerts & Notifications, Incident Management, Alert Channels, Project & Configuration, Best Practices, E2E Examples, AI & Coding Agents, SDLC Basics, Monitoring Concepts, OpenTelemetry Basics, Key Signals, Playwright Comparisons.
  • Check/monitor type groups (would become e.g. "URL monitors", "Browser checks", "Heartbeat monitors"): URL / TCP / DNS / ICMP / Traceroute / gRPC / SSL / Heartbeat Monitors, API / Multistep / Browser Checks, plus the singular construct groups (API Check, URL Monitor, …).
  • Tabs: CLI Reference, API Reference; group CLI Commands.
  • API reference groups (Check Alerts, Check Groups, Status Page Incidents v1, Test Sessions, Environment Variables, …): these appear to match the OpenAPI tags kept in sync by npm run sync:api-group-tags, so I'd leave them unless the spec tags change too.

Checks

  • npm run check:links: no broken internal links.
  • vale on all changed files: 0 errors.
  • git diff --check: clean.
  • CI note: docs-gate and static-docs-checks only run on PRs targeting main, so they run once this is retargeted. Run locally instead, all passing: frontmatter integrity, redirect destinations, API group tags, sitemap up to date.
  • Spot-checked 20 random changed headings for proper nouns that were wrongly lowercased: none found.

🤖 Generated with Claude Code

Convert the remaining title-case Markdown headings, frontmatter title and
sidebarTitle values, and Card/Step/Tab/Accordion title props to sentence
case. Letter case only: no rewording, slugs, hrefs or anchors changed.

Kept as is: product and feature names, check and monitor types
(Browser check, URL monitor), third-party names, acronyms, quoted text,
inline code, YoutubeEmbed titles and generated API reference pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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