From 0de5e2b415f63cb32b0d7fd96c80f30d9f494d27 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Mon, 11 May 2026 14:02:49 +0200 Subject: [PATCH] feat(reading): pass C reading-experience polish MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four small UX fixes that target day-2 readers — users who already landed and are now reading docs. - Lower the top-nav breakpoint from 87em (1392px) to 68em (1088px) so the 5 nav buttons (Dashboard, Slack, Discussions, Changelog, Status) are visible at typical laptop widths. The original breakpoint was set when the navbar carried a logo eating the space; after Pass A moved the logo into the sidebar, the breakpoint is no longer load-bearing. - Hub-page light heroes: /merge-queue, /ci-insights, /test-insights H1s now render in their product accent color (teal / purple / orange). Driven by a new optional `hubAccent: true` frontmatter field on the docs schema; PageContent.astro reads it and adds a `hero-accent` class to the auto-rendered H1. CSS hooks the class into the existing `--section-accent` custom property from Pass A's section-accent system. No new copy, no screenshots, no CTAs — just an accent on the title. - Right-sidebar page-actions cluster: the right column now hosts a PageFeedback widget beneath the table of contents, giving the sidebar a purpose on short doc pages. PageFeedback is mirrored, not moved — the article-footer copy still renders for users on viewports below 82em (where the right sidebar is hidden), with a CSS rule on MainLayout hiding the footer copy when the sidebar is visible. The single Edit-on-GitHub link continues to live in PageMeta (no duplication). - Drop the global h2 auto-numbering. The CSS counter that prefixed every h2 with 1., 2., 3. is deleted. The pattern was an Astro Starlight inheritance that doesn't fit reference / conceptual pages; sequential pages can author explicit numbering inline. The homepage h2s' `class="no-counter"` opt-outs are removed since the rule they overrode is gone. Stale `counter-increment: none` guards in changelog and api-reference styles also removed. Pass C is the third and final pass of the docs design overhaul (A: foundation, B: homepage, C: reading experience). Change-Id: Ib39618f6b4e3fc79ade43934a3d5db6faad6a551 --- src/components/Header/Header.astro | 2 +- src/components/PageContent/PageContent.astro | 10 ++++- .../RightSidebar/RightSidebar.astro | 42 +++++++++++++++---- src/content.config.ts | 1 + src/content/docs/ci-insights.mdx | 1 + src/content/docs/index.mdx | 6 +-- src/content/docs/merge-queue.mdx | 1 + src/content/docs/test-insights.mdx | 1 + src/layouts/BaseLayout.astro | 1 + src/layouts/MainLayout.astro | 18 +++++++- src/pages/changelog/[slug].astro | 15 ------- src/pages/changelog/index.astro | 7 ---- src/styles/api-reference.css | 5 --- src/styles/index.css | 21 ++-------- 14 files changed, 70 insertions(+), 61 deletions(-) diff --git a/src/components/Header/Header.astro b/src/components/Header/Header.astro index 5bac1ff40e..fc8239c2d5 100644 --- a/src/components/Header/Header.astro +++ b/src/components/Header/Header.astro @@ -243,7 +243,7 @@ const primaryLink = isEnterpriseSection margin: 0; } - @media (max-width: 87em) { + @media (max-width: 68em) { .nav-buttons { display: none !important; } diff --git a/src/components/PageContent/PageContent.astro b/src/components/PageContent/PageContent.astro index 919c6faf9e..271bfd3de1 100644 --- a/src/components/PageContent/PageContent.astro +++ b/src/components/PageContent/PageContent.astro @@ -1,5 +1,5 @@ --- -import { CollectionEntry } from 'astro:content'; +import type { CollectionEntry } from 'astro:content'; export interface Props { content: CollectionEntry<'docs'>['data']; } @@ -18,7 +18,13 @@ const suppressTitle = content.suppressTitle;
- {!suppressTitle &&

} + {!suppressTitle && ( +

+ )} {!suppressTitle && (

)} diff --git a/src/components/RightSidebar/RightSidebar.astro b/src/components/RightSidebar/RightSidebar.astro index a366e17bf1..4d9a21c0ca 100644 --- a/src/components/RightSidebar/RightSidebar.astro +++ b/src/components/RightSidebar/RightSidebar.astro @@ -1,30 +1,54 @@ --- import generateToc from '../../util/generateToc'; +import PageFeedback from '../PageFeedback.astro'; import TableOfContents from './TableOfContents'; const { headings } = Astro.props; --- - + ) +} + +
+ +
diff --git a/src/content.config.ts b/src/content.config.ts index 1c9f465fb9..1acdab41eb 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -13,6 +13,7 @@ const docs = defineCollection({ title: z.string(), description: z.string(), suppressTitle: z.boolean().optional(), + hubAccent: z.boolean().optional(), }), }); diff --git a/src/content/docs/ci-insights.mdx b/src/content/docs/ci-insights.mdx index 084d3a8ba7..ffc90663d2 100644 --- a/src/content/docs/ci-insights.mdx +++ b/src/content/docs/ci-insights.mdx @@ -1,6 +1,7 @@ --- title: CI Insights description: Optimize your CI run time, catch flaky tests, and give developers actionable insights so your team ships code faster. +hubAccent: true --- import Docset from '../../components/DocsetGrid/Docset.astro'; diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 544453ac3b..24ac4453f4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -62,7 +62,7 @@ import mergeQueueHero from './images/merge-queue-hero.jpg'; {/* -------------- PROBLEM CARDS -------------- */}
-

What problem are you solving?

+

What problem are you solving?

Broken main, slow merges
@@ -91,7 +91,7 @@ import mergeQueueHero from './images/merge-queue-hero.jpg'; {/* -------------- PRODUCTS -------------- */}
-

Products

+

Products

@@ -141,7 +141,7 @@ import mergeQueueHero from './images/merge-queue-hero.jpg'; {/* -------------- COMMUNITY -------------- */}
-

Community

+

Community

Share feedback, ask questions, and see what other teams build with Mergify.

diff --git a/src/content/docs/merge-queue.mdx b/src/content/docs/merge-queue.mdx index a051999f6f..773fa5f6e2 100644 --- a/src/content/docs/merge-queue.mdx +++ b/src/content/docs/merge-queue.mdx @@ -1,6 +1,7 @@ --- title: Merge Queue description: Ship faster with zero broken builds. Parallel testing, smart batching, and CI cost optimization. +hubAccent: true --- import Button from '~/components/Button.astro'; diff --git a/src/content/docs/test-insights.mdx b/src/content/docs/test-insights.mdx index 3d8ec3070f..f42e394f29 100644 --- a/src/content/docs/test-insights.mdx +++ b/src/content/docs/test-insights.mdx @@ -1,6 +1,7 @@ --- title: Test Insights description: Monitor, detect, and manage unreliable tests across your repositories. +hubAccent: true --- Test Insights helps you manage test reliability across the full lifecycle. diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro index 87b3e23090..5b1ba74262 100644 --- a/src/layouts/BaseLayout.astro +++ b/src/layouts/BaseLayout.astro @@ -115,6 +115,7 @@ const canonicalURL = new URL(Astro.url.pathname.replace(/([^/])$/, '$1/'), Astro } #right-sidebar { display: flex; + flex-direction: column; } } diff --git a/src/layouts/MainLayout.astro b/src/layouts/MainLayout.astro index d0aed266ff..aabe75d0ef 100644 --- a/src/layouts/MainLayout.astro +++ b/src/layouts/MainLayout.astro @@ -23,7 +23,7 @@ const { content, headings, breadcrumbTitle, showMarkdownActions = true } = Astro --- - + { Astro.url.pathname !== '/' && ( @@ -63,10 +63,24 @@ const { content, headings, breadcrumbTitle, showMarkdownActions = true } = Astro { Astro.url.pathname !== '/' && ( - + {/* PageFeedback also lives in the right sidebar (visible ≥82em). + Hide this footer copy on wide viewports so it doesn't double up. */} +
+ +
{showMarkdownActions && } ) } + + diff --git a/src/pages/changelog/[slug].astro b/src/pages/changelog/[slug].astro index 5ba001087e..431efdcd51 100644 --- a/src/pages/changelog/[slug].astro +++ b/src/pages/changelog/[slug].astro @@ -147,14 +147,6 @@ const accent = getProductAccent(primaryTag); font-size: 1.75rem; } } - /* Disable global heading auto-numbering */ - .changelog-detail .detail-title { - counter-increment: none !important; - } - .changelog-detail .detail-title::before { - content: none !important; - } - .detail-date { font-size: 0.8125rem; color: var(--theme-text-muted); @@ -300,13 +292,6 @@ const accent = getProductAccent(primaryTag); font-weight: 700; margin: 0 0 14px; } - /* Disable global heading auto-numbering on related-heading */ - .changelog-detail .related-heading { - counter-increment: none !important; - } - .changelog-detail .related-heading::before { - content: none !important; - } .related-grid { display: grid; grid-template-columns: 1fr 1fr; diff --git a/src/pages/changelog/index.astro b/src/pages/changelog/index.astro index 9cc78559dd..f716597333 100644 --- a/src/pages/changelog/index.astro +++ b/src/pages/changelog/index.astro @@ -283,13 +283,6 @@ const description = 'Latest product updates from Mergify.'; background: var(--theme-text); } - /* Year / month headings — disable global numbering */ - .changelog-page .cl-year > .cl-year-heading { - counter-increment: none !important; - } - .changelog-page .cl-year > .cl-year-heading::before { - content: none !important; - } .cl-year { margin-bottom: 0; } diff --git a/src/styles/api-reference.css b/src/styles/api-reference.css index 24a7285877..c9e3324519 100644 --- a/src/styles/api-reference.css +++ b/src/styles/api-reference.css @@ -113,11 +113,6 @@ margin: 0 0 0.5rem !important; color: var(--theme-text); scroll-margin-top: calc(var(--theme-navbar-height) + 1rem); - counter-increment: none; -} - -.endpoint-heading::before { - content: none !important; } .endpoint-head { diff --git a/src/styles/index.css b/src/styles/index.css index 6c19c2f8ba..bc2ec93b56 100644 --- a/src/styles/index.css +++ b/src/styles/index.css @@ -826,6 +826,10 @@ pre { margin-bottom: 0.25em; } +.content-title.hero-accent { + color: var(--section-accent); +} + #main-content h2.content-subtitle, .content-subtitle { font-size: 1.125rem; @@ -866,20 +870,3 @@ pre { header .nav-wrapper { height: 100%; } - -article.content { - counter-reset: h2-section; -} - -.content h2:not(.content-subtitle):not(.no-counter) { - counter-increment: h2-section; - position: relative; -} - -.content h2:not(.content-subtitle):not(.no-counter)::before { - content: counter(h2-section); - font-weight: 500; - margin-right: 0.55rem; - color: var(--theme-text-muted); - opacity: 0.6; -}