Make It Yours: The Boots Docs Customization Guide

This site is built on Astro with Tailwind v4 + daisyUI, and everything you see — colors, fonts, layout, search — is configured in a handful of files you own. This guide covers the three things you’ll touch most:

1. Changing the look (colors, fonts, layout knobs)
2. Writing posts (frontmatter, images, callouts, code blocks, charts, math)
3. Going further with MDX (components inside your content)

1. Where the look lives

Colors: src/styles/global.css

The entire palette is defined in two theme blocks near the top of src/styles/global.css — one for light mode (chirpy-light), one for dark (chirpy-dark). Each is a list of CSS variables consumed by daisyUI:

/* Boots midnight blue primary (#2E3644) — 12.2:1 on white */
--color-primary: oklch(33.1% 0.027 261.6);

/* Darkened Boots gold (#8A6200) — AA-safe as text on light bg */
--color-accent: oklch(52.4% 0.108 80.6);

Change a variable, save, and the dev server hot-reloads with the new color everywhere it’s used. The current brand mapping:

The sidebar has its own tokens (it stays midnight in both themes) in the @theme block just below: --color-sidebar-from / --color-sidebar-to (the gradient), --color-sidebar-text, --color-sidebar-muted, and --color-sidebar-accent (the gold hover).

Colors are written in oklch() — a color space where the first number is perceived lightness, which makes “same color but darker” edits predictable. To convert a hex color, paste it into oklch.com and copy the result.

Fonts: astro.config.mjs

The fonts array at the bottom of astro.config.mjs loads Source Sans 3 (UI), Lato, and JetBrains Mono (code) from local @fontsource packages. To swap a font: install its @fontsource package with bun add -d, point the src paths at the new package’s .woff2 files, then update --font-sans / --font-mono in the @theme block of global.css.

Site settings: src/config.ts

Title, description, author, posts per page, nav items, social links, and footer text all live in src/config.ts, under a clearly marked “SAFE TO EDIT” section. The nav is just an array — add or remove entries in NAV to change the sidebar menu.

2. Writing posts

Every post is a markdown file in src/content/posts/en/. The filename becomes the URL slug — my-post.md → /posts/my-post.

Frontmatter cheatsheet

Only title, description, and pubDate are required. The full menu:

---
title: 'My Post' # required, max 140 chars
description: 'One-liner.' # required, max 280 chars
pubDate: 2026-08-02 # required
updatedDate: 2026-08-15 # shows an "updated" date
tags: [supabase, typescript] # listed on /tags
categories: [Runbooks] # listed on /categories
pinned: true # pin to top of the homepage
draft: true # hidden in production builds (visible in dev)
unlisted: true # live at its URL but hidden from all listings
toc: true # right-rail table of contents (default on)
heroImage: ./assets/hero.png # top-of-post image (see Images below)
heroImageAlt: 'What it shows'
math: true # enables KaTeX on this page only
mermaid: true # enables diagrams/charts on this page only
comments: false # opt this post out of Giscus comments
---

math and mermaid are opt-in per post so their libraries stay off pages that don’t need them.

Images

Three ways to add one, in order of preference:

1. Optimized (recommended): put the file next to your post (e.g. src/content/posts/en/assets/diagram.png) or under src/assets/, and reference it relatively: ![Alt text](./assets/diagram.png). Astro converts it to WebP, generates responsive sizes, and lazy-loads it.
2. Public folder: files in public/ are served as-is at the site root — ![Alt](/images/photo.jpg). No optimization.
3. Remote URL: external images work if the host is allow-listed in image.remotePatterns in astro.config.mjs (Unsplash, GitHub, jsDelivr, Cloudinary are pre-approved — add your own hosts there).

For a featured image at the top of the post and on its listing card, use heroImage in frontmatter instead.

Callouts and alerts

Fenced ```alert blocks render as styled daisyUI alerts:

Code blocks

Code blocks are powered by Expressive Code — they get a copy button for free, and the fence line accepts extras:

```ts title="src/utils/retry.ts" {3} ins={5} del={4}

```

export async function retry<T>(fn: () => Promise<T>, times = 3): Promise<T> {
  try {
    return await fn(); // highlighted line
    console.log('unreachable'); // marked as removed
    if (times <= 0) throw new Error('out of retries'); // marked as added
  } catch (err) {
    if (times <= 0) throw err;
    return retry(fn, times - 1);
  }
}

• title="..." adds a file-name frame
• {3} or {2-5} highlights lines
• ins={5} / del={4} mark diff-style added/removed lines
• wrap soft-wraps long lines

Charts, graphs, and diagrams

Set mermaid: true in frontmatter, then use ```mermaid fences. No chart library to install — this covers flowcharts, pie charts, bar/line charts, sequence diagrams, ER diagrams, and more.

Flowchart:

Pie chart:

Bar + line chart:

The full syntax for every diagram type is at mermaid.js.org. There’s also a deeper set of worked examples in this site’s Diagram Recipes post.

Math

Set math: true in frontmatter, then write LaTeX between dollar signs. Inline like $O(n \log n)$, or display blocks:

$$\text{contrast} = \frac{L_{\text{lighter}} + 0.05}{L_{\text{darker}} + 0.05}$$

Tables, quotes, and the rest

Standard GitHub-flavored markdown works everywhere: tables (like the color table above), task lists, blockquotes, and footnotes. Headings automatically get hover-to-copy anchor links, and everything you write is indexed by the built-in search (rebuilt on bun run build).

3. When to reach for MDX

Rename a post from .md to .mdx and you can import components into your content — interactive widgets, reusable callouts, video embeds — while everything above keeps working.

---
title: 'My Interactive Post'
description: 'MDX in action.'
pubDate: 2026-08-02
---

import Callout from '../../../components/Callout.astro';

Regular markdown up here.

<Callout type="warning" title="From a component">
  This box is an Astro component receiving props, rendered inside markdown.
</Callout>

Markdown continues below — **bold**, `code`, lists, all normal.

The rule of thumb: stay with .md for prose, code, and charts (everything in section 2 needs no MDX), and switch to .mdx when you want React/Astro components, JSX logic, or reusable content variables inside a post.

See it live in the companion post: Using MDX: Components Inside Your Posts — its source file is src/content/posts/en/using-mdx.mdx.

Quick reference card