Sidebar & badges

The sidebar you see on the left is deliberately quiet. This page explains the rules so new content stays that way — and shows how to add badges when the signal is actually worth the noise.

Three visual tiers

Tier	Example	Style
1	KUBERNETES · AZURE	UPPERCASE, tracked, 14px chevron
2	NETWORKING · AZ305	smaller small-caps, tinted, 10px chevron
3	Services explained	sentence case, sans; active = accent pill

The chevron shrinks and the label quiets as depth increases — so nesting feels obvious without a legend.

Overview pages are hidden

Every folder has an index.mdx (so /kubernetes/ doesn’t 404), but every single one has sidebar: { hidden: true } in its frontmatter. That’s why you never see a Kubernetes → Overview → Kubernetes duplicate.

Users reach section landing pages via:

• LinkCard grids on the homepage.
• LinkCard grids on parent section pages.
• Breadcrumbs.
• Search.

Do you ever un-hide an Overview page?

Rarely — only if the Overview page is doing real work (long-form explanation or a curated reading order) and users can’t find it via LinkCards. In that case remove sidebar.hidden, give it a distinct label, and add sidebar.order: 0 so it sorts first.

Badges — use sparingly

Badges are the noisiest element in a sidebar. Rule of thumb: add a badge only when it distinguishes the item from its siblings.

Under Kubernetes → Security, tagging every post SEC adds nothing — the group already says Security. Tagging one post Lab is useful: it tells the reader that this one is a hands-on scenario, unlike its neighbours.

Adding a badge later

Two ways.

Sidebar badge — small tag on the nav item

---
title: RBAC break-glass recovery
sidebar:
  badge:
    text: Lab
    variant: tip                # note | tip | success | danger | caution
---

Result in the sidebar: Lab

Inline badge — anywhere in the body (.mdx only)

import { Badge } from '@astrojs/starlight/components';

<Badge text="Lab scenario" variant="tip" />
<Badge text="~30 min" variant="note" />
<Badge text="Production-tested" variant="success" />

Result: Lab scenario ~30 min Production-tested

When not to add a badge

• The parent group already tells the same story. Under AZURE → AZ-305, don’t tag every post AZ-305.
• All siblings would get the same badge. It stops being a signal.
• The badge repeats the title. A post titled “Lab · Break-glass RBAC” doesn’t need a Lab badge.

When a badge is worth it

• One-of-many differentiator — Lab on the one hands-on post in a series of theory posts.
• Status flag — Draft, WIP, Deprecated.
• Difficulty tier — Advanced on a single deep-dive amid intro posts.

1. Draft the post.
2. Look at the sibling posts in the same folder.
3. Ask: “Is there a real difference readers should see before clicking?”
4. If yes → add a badge with 1–2 words. If no → skip it.