@SomeRanDev I just last week updated my mdBook to latest version. And the way it works, I just add the default theme of mdBook too (.ayu, .rust, etc) - so the list contains all -> see above I updated the Gist to my last version.

And I asked Claude to explain how it works - so here's the step by step documentation, that worked for me:

Adding Custom Themes to mdBook Without Losing Defaults

theme/css/variables.css is an all-or-nothing override. When mdBook sees this file in your theme/ directory, it replaces the built-in one entirely. You must include all default themes AND your custom ones in the same file.

Steps

1. Copy the default variables.css

mkdir -p theme/css
mdbook init --theme  # generates theme/ with defaults
# Keep theme/css/variables.css (and theme/index.hbs if adding theme picker buttons)

2. Append custom themes to theme/css/variables.css

Keep all built-in theme classes (.ayu, .coal, .light, .navy, .rust, plus the @media (prefers-color-scheme: dark) block), then add yours below:

/* ... all default themes (ayu, coal, light, navy, rust) stay above ... */

.kanagawa {
    --bg: #1F1F28;
    --fg: #DCD7BA;
    --sidebar-bg: #2A2A37;
    --sidebar-fg: #C8C093;
    /* define ALL the same CSS variables the defaults use */
    --color-scheme: dark;
}

/* Code block overrides for your theme */
.kanagawa .hljs {
    background: #2A2A37;
    color: #DCD7BA;
}

3. Add theme picker button in theme/index.hbs

Find the theme button list and add your entry. In mdBook v0.5.x, IDs use the mdbook-theme- prefix:

<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-kanagawa">Kanagawa</button></li>

For mdBook v0.4.x, the ID has no prefix:

<li role="none"><button role="menuitem" class="theme" id="kanagawa">Kanagawa</button></li>

4. Reference in book.toml

[output.html]
default-theme = "light"
preferred-dark-theme = "kanagawa"

Why it breaks without this

The file replaces the default — it doesn't merge. If your variables.css only contains .kanagawa, all other themes (.light, .coal, etc.) disappear. You have to carry forward all built-in definitions yourself.

Real-world example

See my working book at dedp.online. It includes 4 custom themes (Kanagawa, Rose Pink, Tokyo Night, Burgundy) alongside all mdBook defaults.