fix(website): render decorative card titles as div, not h2, to fix Algolia search relevance#2400
Merged
Merged
Conversation
Algolia DocSearch v3 indexes any <article h2> as a page section (lvl2)
because the default Docusaurus crawler template uses that selector. Two
components on atmos.tools were emitting decorative h2s that hijacked the
search hierarchy:
1. DocCardList items render each card as <h2 class="cardTitle_*">📄️
{label}</h2>. On pages like /cli/configuration/auth/ this produces
~10 lvl2 records containing literal command names ("atmos auth
login", "atmos auth whoami", ...), which then outrank the real
command pages on those queries.
2. ActionCard renders <h2>{title}</h2> for its decorative card title.
On /cli/commands/auth/usage the "Configure Authentication" h2 sits
between the page H1 and the first real H2, scrambling the crawler's
hierarchy extractor so the page produces only a single weak
content-type record.
Both titles are navigational labels for a link, not section headings.
Render them as <div> with the same className so visual styling is
preserved (the CSS targets the class, not the element). Mirrors the
pattern from PR #2393 for Terminal/Screengrab/File.
Swizzles @theme/DocCard rather than changing the Algolia crawler config,
keeping the fix local to atmos.tools and avoiding atmos-specific
deviations from the DocSearch v3 defaults.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
requested a review
from a team
as a code owner
Contributor
|
Tip Atmos Pro
No affected stacks workflow was detected for this pull request. 
|
Erik Osterman (Cloud Posse) (osterman)
added
the
no-release
Dependency ReviewThe following issues were found:
License Issueswebsite/package.json
Scanned Files
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
📝 WalkthroughWalkthroughReplaces ActionCard title h2 with a div using ChangesActionCard Title Refactor
DocCard Theme Component
Dependency
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
![atmos-pro[bot]](https://avatars.githubusercontent.com/in/927493?s=60&v=4){kind=small}
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2400 +/- ##
==========================================
+ Coverage 78.12% 78.16% +0.03%
==========================================
Files 1098 1098
Lines 103630 103630
==========================================
+ Hits 80966 80999 +33
+ Misses 18213 18180 -33
Partials 4451 4451
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
…wizzle The swizzled DocCard component at website/src/theme/DocCard/index.js imports `@docusaurus/plugin-content-docs/client` for `useDocById` and `findFirstSidebarItemLink`. The package is a transitive dep of @docusaurus/preset-classic and was hoisted in local pnpm installs, but CI's stricter module resolution couldn't find it from outside the upstream package boundary, failing the build with: Module not found: Error: Can't resolve '@docusaurus/plugin-content-docs/client' in '.../website/src/theme/DocCard' Adding the package as a direct dependency makes the swizzle resolvable in any package manager configuration. Version pinned to ^3.9.2 to match the rest of the @docusaurus/* deps. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
dismissed stale reviews from atmos-pro[bot] and coderabbitai[bot]
via
001606e
Andriy Knysh (aknysh)
approved these changes
May 12, 2026
Contributor
|
These changes were released in v1.218.0-rc.2. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
what
@theme/DocCardso each card's title renders as<div className={styles.cardTitle}>instead of<Heading as=\"h2\">. Visual styling is preserved because the CSS module rule (font-size: 1.2rem) targets the className, not the element.ActionCard's<h2>{title}</h2>to<div className=\"action-card__title\">{title}</div>and add explicit font tokens so the title still renders at h2 size.Terminal,Screengrab, andFile.why
article h2as a page section (lvl2) — that's the default Docusaurus crawler template's selector. Decorative h2s emitted by these components were being indexed as if they were real headings./cli/configuration/auth/theDocCardList"Related Commands" section emits ten<h2 class=\"cardTitle_*\">📄️ atmos auth login</h2>-style entries. Searches likeatmos authranked these card titles above the actual/cli/commands/auth/usagepage because they contained the literal query./cli/commands/auth/usagetheActionCardtitle<h2>Configure Authentication</h2>sat between the page H1 and the first real H2. That extra heading scrambled the crawler's hierarchy extractor, leaving the page with a single weaktype:\"content\"record and nolvl1/lvl2records — so it couldn't compete with the noisier configuration page.<div>is semantically more honest and removes the indexing hijack without forcing an atmos-specific deviation from the DocSearch v3 defaults.references
Terminal/Screengrab/File).Summary by CodeRabbit
New Features
Style