Documentation indexes need to be scannable. A responsive card grid is a good fit when readers need to compare guides, jump into a topic, or discover related resources.
This tutorial builds a simple grid that works with plain HTML and CSS, then shows how to adapt it to Bootstrap utilities.
The Markup
Start with semantic links. Each card should be a destination, not just a box with a button inside it.
<section class="doc-grid" aria-label="Documentation topics">
<a class="doc-card" href="/docs/getting-started/">
<span class="doc-card__eyebrow">Start</span>
<h2>Getting Started</h2>
<p>Install the theme, configure your site, and publish your first page.</p>
</a>
<a class="doc-card" href="/docs/customization/">
<span class="doc-card__eyebrow">Design</span>
<h2>Customization</h2>
<p>Adjust layouts, navigation, colors, and reusable includes.</p>
</a>
</section>
The whole card is clickable, which is easier on touch devices and faster for scanning.
The Grid
Use auto-fit with minmax so the layout adapts without breakpoints.
.doc-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 1rem;
}
.doc-card {
border: 1px solid var(--bs-border-color);
border-radius: 0.5rem;
padding: 1rem;
color: inherit;
text-decoration: none;
}
.doc-card:hover,
.doc-card:focus-visible {
border-color: var(--bs-primary);
box-shadow: 0 0 0 0.2rem rgba(var(--bs-primary-rgb), 0.15);
}
The card radius stays modest and the hover state changes border and focus treatment without shifting layout.
Bootstrap-Friendly Version
If the project already uses Bootstrap, keep the grid custom and let Bootstrap handle spacing and typography.
<section class="doc-grid my-4" aria-label="Documentation topics">
<a class="doc-card d-block h-100" href="/docs/deployment/">
<span class="text-uppercase small text-secondary">Publish</span>
<h2 class="h5 mt-2">Deployment</h2>
<p class="mb-0">Deploy to GitHub Pages, Netlify, or a custom domain.</p>
</a>
</section>
This avoids fighting the framework while still giving you a layout tailored to documentation.
Accessibility Checks
Before shipping the grid, check these details:
- The card has visible focus styles
- Link text makes sense when read out of context
- Heading levels follow the page outline
- Cards do not rely on color alone to indicate state
- Content remains readable at narrow widths
Optional Metadata
Documentation cards become more useful when they include a small status line:
| Metadata | Example |
|---|---|
| Difficulty | Beginner |
| Time | 10 minutes |
| Topic | Deployment |
| Updated | April 2026 |
Keep metadata short. The card should help readers choose, not become a miniature article.
Final Pattern
A good card grid is predictable. It uses stable dimensions, clear labels, and a full-card link. Once the pattern is in place, documentation indexes become easier to expand without redesigning the page each time.