Vitepress Theme Akari Docsv1.0.0GitHubSettingsMore

Extending the theme ​

There are three ways to adjust the theme, and none of them needs changes to the theme's source:

WayGood forWhere
ConfigTitles, navigation, settings options, TOC, footer, interface stringsdocs/config.ts and each language's config.ts; see Configuration
Replacing componentsA branded app bar, a special footer, a custom content containerenhanceApp in the theme entry
CSS variablesCorner radius, spacing, surface colors, TOC widthSite 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:

ts
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:

css
: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:

4px corners
A more compact card, suited to tool panels and data blocks.
Default corners
Keeps the m3e card's default shape token, consistent with other components.
28px corners
Larger corners, closer to the visual language of the document surface.
html
<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-bar for the app bar and m3e-nav-menu for 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.ts and icons.ts. Do not import @m3e/web/all.
  • Do not access window, document or localStorage at the top level of a module, or server-side rendering fails.
GitHub Settings

Search the docs

Type a page title, a component name or words from the text.

Press ⌘/Ctrl + K to open it anytime

Choose a language

EnglishEnglish (United States)العربيةArabic (Saudi Arabia)FrançaisFrench (France)日本語Japanese (Japan)한국어Korean (South Korea)简体中文Chinese (China)

Settings

Color
VariantTonal SpotVibrantFidelityExpressiveMonochromeNeutralRainbowFruit Salad
ContrastDefaultMediumHigh
MotionStandardExpressive
Text directionFollow languageLeft to rightRight to left
Text size100%150%200%