From 1ff2007067e357203fc473be99bc89be1596d161 Mon Sep 17 00:00:00 2001
From: Vladlen Popolitov <vladlen@FreeBSD.org>
Date: Sun, 27 Sep 2026 18:46:45 +0300
Subject: Fix HTML validation errors in docs - on main page

Card titles on the documentation homepage were rendered as <h5>
right after the <h2> from global-search.html, skipping two
heading levels. The page also had no <h1>.

Add a visually hidden <h1>{{ .Title }}</h1> before the search
partial, render card titles as <h3 class=""card-title"">, and
rename the .card a h5 selector to .card a .card-title with
padding-top and padding-bottom set, so the look stays
the same. Add a .visually-hidden helper to global.scss.

Differential Revision: https://reviews.freebsd.org/D60069
PR: 297509
---
 .../themes/beastie/assets/styles/global.scss          | 16 +++++++++++++++-
 documentation/themes/beastie/layouts/index.html       | 19 ++++++++++---------
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/documentation/themes/beastie/assets/styles/global.scss b/documentation/themes/beastie/assets/styles/global.scss
index 88554f711e..17a496ffd0 100644
--- a/documentation/themes/beastie/assets/styles/global.scss
+++ b/documentation/themes/beastie/assets/styles/global.scss
@@ -141,12 +141,14 @@ body {
         flex-direction: column;
         text-decoration: none;
 
-        h5 {
+        .card-title {
           color: var(--global-font-color);
           font-weight: 700;
           font-size: 22px;
           margin: 0px 0px 8px 0px;
           border-bottom: 0px;
+          padding-top: 0.1rem;
+          padding-bottom: 0.5rem;
         }
 
         p {
@@ -213,6 +215,18 @@ ul.language-list {
   font-weight: 700;
 }
 
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 h1,
 h2,
 h3,
diff --git a/documentation/themes/beastie/layouts/index.html b/documentation/themes/beastie/layouts/index.html
index 3789a3d1b0..7ae440920f 100644
--- a/documentation/themes/beastie/layouts/index.html
+++ b/documentation/themes/beastie/layouts/index.html
@@ -8,59 +8,60 @@
     {{ $downloadurl = printf "%s/%s/" $.Site.Params.websiteURL "where" }}
   {{ end }}
   <main class="main-wrapper">
+    <h1 class="visually-hidden">{{ .Title }}</h1>
     {{ partial "global-search.html" . }}
     <section class="cards-container">
       <div class="card">
         <a href={{ "books/handbook/basics" | absLangURL }}>
-          <h5>{{ i18n "getting-started" }}</h5>
+          <h3 class="card-title">{{ i18n "getting-started" }}</h3>
           <p>{{ i18n "learn-basics" }}</p>
         </a>
       </div>
       <div class="card">
         <a href={{ "books/handbook/" | absLangURL }}>
-          <h5>{{ i18n "handbook" }}</h5>
+          <h3 class="card-title">{{ i18n "handbook" }}</h3>
           <p>{{ i18n "handbook-desc" }}</p>
         </a>
       </div>
       <div class="card">
         <a href={{ "books/porters-handbook/" | absLangURL }}>
-          <h5>{{ i18n "porters-handbook" }}</h5>
+          <h3 class="card-title">{{ i18n "porters-handbook" }}</h3>
           <p>{{ i18n "porters-handbook-desc" }}</p>
         </a>
       </div>
       <div class="card">
         <a href={{ "books/faq/" | absLangURL }}>
-          <h5>{{ i18n "faq" }}</h5>
+          <h3 class="card-title">{{ i18n "faq" }}</h3>
           <p>{{ i18n "faq-desc" }}</p>
         </a>
       </div>
       <div class="card">
         <a href="https://docs.FreeBSD.org/en/books/fdp-primer/">
-          <h5>{{ i18n "fdp" }}</h5>
+          <h3 class="card-title">{{ i18n "fdp" }}</h3>
           <p>{{ i18n "fdp-desc" }}</p>
         </a>
       </div>
       <div class="card">
         <a href={{ "books" | absLangURL }}>
-          <h5>{{ i18n "books" }}</h5>
+          <h3 class="card-title">{{ i18n "books" }}</h3>
           <p>{{ i18n "books-list" }}</p>
         </a>
       </div>
       <div class="card">
         <a href={{ "articles" | absLangURL }}>
-          <h5>{{ i18n "articles" }}</h5>
+          <h3 class="card-title">{{ i18n "articles" }}</h3>
           <p>{{ i18n "articles-list" }}</p>
         </a>
       </div>
       <div class="card">
         <a href="https://man.FreeBSD.org/cgi/man.cgi">
-          <h5>{{ i18n "manual-pages" }}</h5>
+          <h3 class="card-title">{{ i18n "manual-pages" }}</h3>
           <p>{{ i18n "manual-pages-desc" }}</p>
         </a>
       </div>
       <div class="card">
         <a href="https://docs-archive.freebsd.org">
-          <h5>{{ i18n "docs-archive" }}</h5>
+          <h3 class="card-title">{{ i18n "docs-archive" }}</h3>
           <p>{{ i18n "docs-archive-desc" }}</p>
         </a>
       </div>
-- 
cgit v1.3