Extending the theme
There are three ways to adjust the theme, and none of them needs changes to the theme's source:
| Way | Good for | Where |
|---|---|---|
| Config | Titles, navigation, settings options, TOC, footer, interface strings | docs/config.ts and each language's config.ts; see Configuration |
| Replacing components | A branded app bar, a special footer, a custom content container | enhanceApp in the theme entry |
| CSS variables | Corner radius, spacing, surface colors, TOC width | Site styles |
Replacing components
In enhanceApp of the theme entry docs/.vitepress/theme/index.ts, call provideAkariSiteData to hand the site's language and config data to the theme, then pass the parts you want to replace to provideAkariComponents. Parts you leave out keep the built-in components:
import { type Theme } from "vitepress";
import DefaultTheme from "vitepress/theme-without-fonts";
import { provideAkariSiteData } from "./composables/useLocales";
import { provideAkariComponents } from "./composables/useAkariConfig";
import Layout from "./layouts/AkariLayout.vue";
import CustomFooter from "./CustomFooter.vue";
export default {
extends: DefaultTheme,
Layout,
enhanceApp({ app, siteData }) {
provideAkariSiteData(app, siteData);
provideAkariComponents(app, { Footer: CustomFooter });
},
} satisfies Theme;Custom components read config and state through the theme's composables, such as useAkariConfig() and useSidebar(). See API for the parts you can replace and the functions available.
CSS variables
Override the variables of the theme and of m3e components in your site styles:
:root {
--akari-doc-radius: 24px;
--akari-doc-max-width: 1440px;
}You can also override a single component in place. The three cards below change only the corner radius:
<m3e-card variant="outlined" style="--m3e-card-shape: 28px;">…</m3e-card>Prefer the variables that the theme and components expose. Do not rely on components' internal class names or Shadow DOM structure; they change between versions.
Things to keep in mind
- When you replace a component, keep the original root element's semantics and accessibility attributes (for example,
m3e-app-barfor the app bar andm3e-nav-menufor navigation), and keep keyboard operation. - Do not hard-code colors. Use the
--md-sys-color-*tokens so that colors follow dynamic color, light and dark mode, and contrast. - When you use a new m3e component or icon, register it on demand in
m3e.tsandicons.ts. Do not import@m3e/web/all. - Do not access
window,documentorlocalStorageat the top level of a module, or server-side rendering fails.