Vitepress Theme Akari Docsv1.0.0GitHubSettingsMore

Extending the theme: API ​

provideAkariComponents ​

ts
import { provideAkariComponents } from "./composables/useAkariConfig";

function provideAkariComponents(
  app: App,
  components: Partial<Record<AkariComponentSlot, Component>>,
): void;

Call it in enhanceApp of the theme entry. Each component you pass replaces the matching part; parts you leave out use the built-in components. Config files can only hold data, so components are provided here instead of in the config.

SlotReplacesBuilt-in component
AppBarApp barm3e-app-bar app bar
DesktopNavDesktop rail and navigation drawerm3e-nav-rail and m3e-nav-menu; the root element is display: contents, the rail spans the full height of column 1 of the page grid, and the persistent drawer sits in column 2, row 2
SidebarNavigation drawer on narrow screensRecursive m3e-nav-menu
SettingsPanel in the settings dialogSix groups of options; the title, close button and motion come from the dialog
HeroPage heroTitle card and image card, rendered only when the frontmatter has hero
TocTOC on the rightHanging TOC
PagerPager at the end of the contentPrevious and next page cards
FooterFooterWavy divider and footer surface
ContentOuter container of the Markdown contentUnstyled div

A minimal app bar:

vue
<script setup lang="ts">
import { useAkariConfig } from "@theme";

const config = useAkariConfig();
</script>

<template>
  <m3e-app-bar>
    <span slot="title">{{ config.appBar.title }}</span>
    <m3e-chip v-if="config.appBar.version" slot="trailing">
      {{ config.appBar.version }}
    </m3e-chip>
  </m3e-app-bar>
</template>

When you replace the app bar for real, also keep the toggle that opens the navigation drawer on narrow screens (<m3e-drawer-toggle for="akari-sidebar">). Without it, the navigation cannot be opened on narrow screens.

Composables ​

All of them are exported from the theme entry (import { … } from "@theme") and can only be called in components inside the layout.

FunctionReturnsSee
useAkariConfig()ComputedRef<ResolvedAkariThemeConfig>: the theme config merged with defaultsBelow
useSidebar(){ items, prevNext, tabGroup, isActive, hasActive }Side navigation
useAkariSettings(){ settings, setSetting, reset, isDefault, defaults, sections, labels }Settings
useAkariColorScheme(){ mode, resolved, cycle }Settings
useAkariI18n(){ lang, messages, t }Internationalization
useAkariLocales(){ locales, homeHref }Internationalization
useAkariSearch()State and actions of the search panelSearch

The result of useAkariConfig() contains lang, messages, appBar, sidebar, settings, toc, footer, search, fonts and components. Each group has its defaults filled in and has been validated (for example, toc.maxDepth is clamped between 1 and 6).

Other exports ​

ExportTypePurpose
defineAkariConfig(config: AkariSiteConfig) => AkariDirectoryConfigWriting config files; see Configuration
defineAkariThemeConfig(config: AkariThemeConfig) => AkariThemeConfigType helper when you write only theme fields
registerSearchBackend(id, handler) => voidRegisters a search backend; see Search
defineAkariLanguage(language: AkariLanguage) => AkariLanguageWrites a language pack; see Internationalization
AKARI_LANGUAGESAkariLanguage[]The built-in language packs
resolveLanguage(lang, languages?) => ResolvedAkariLanguageThe pack a language ends up with
AKARI_CONTENT_ID"akari-doc-content"id of the content container
AKARI_SIDEBAR_ID"akari-sidebar"id of the navigation drawer on narrow screens
AKARI_SETTINGS_ID"akari-settings"id of the settings panel

Types (AkariThemeConfig, AkariSidebarItem, AkariSearchResult and others) are all exported from types.ts.

CSS variables ​

ScopeVariablesSee
Document surface, TOC, footer--akari-doc-*, --akari-toc-width, --akari-wavy-divider-colorLayout and app bar
Tab bar of parallel pages--akari-app-bar-tabs-gap, --akari-page-tabs-docked-max-widthSide navigation
Hero and patterns--akari-doc-hero-*, --akari-pattern-*Hero
Color--md-sys-color-*Color
Typography--md-sys-typescale-*Typography
m3e componentsSuch as --m3e-card-shape, --m3e-button-*m3e component docs

Source layout ​

text
docs/.vitepress/
├── config.mts             connects the theme to VitePress
├── content/               languages, paths and navigation from the folders (Node)
└── theme/
    ├── index.ts           theme entry and public exports
    ├── define.ts          defineAkariConfig and defineAkariLanguage
    ├── config.ts          config defaults and validation
    ├── types.ts           type definitions
    ├── constants.ts       defaults, breakpoints and ids
    ├── i18n/              language packs and resolving a language
    │   └── languages/     built-in language packs, one file per language
    ├── locales.ts         path mapping for switching language
    ├── sidebar.ts         navigation normalizing, matching and paging
    ├── settings.ts        settings validation and storage
    ├── scheme.ts          light and dark mode resolution and first-frame script
    ├── hero.ts            hero frontmatter parsing
    ├── loading.ts         loading bar progress math
    ├── head.ts / fonts.ts akariHead and fonts
    ├── markdown.ts        akariMarkdown
    ├── m3e.ts / icons.ts  on-demand registration of components and icons
    ├── layouts/           AkariLayout.vue
    ├── components/
    │   ├── shell/         app bar, "More" menu, appearance and language buttons, dialogs, loading bar
    │   ├── sidebar/       rail, desktop navigation drawer, narrow-screen navigation
    │   ├── content/       hero, tab bar, TOC, pager, FABs, footer
    │   └── settings/      settings dialog and panel
    ├── composables/       composables
    ├── search/            search panel, backends and state
    └── styles/            tokens, shell, content, pattern and tab bar styles

Logic that does not depend on the browser (config resolution, navigation matching, language paths, settings validation, hero parsing, motion curves and so on) is written as pure functions, with unit tests in tests/ at the repository root.

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%