Vitepress Theme Akari Docsv1.0.0GitHubSettingsMore

Configuration: API ​

defineAkariConfig ​

ts
import { defineAkariConfig } from "./.vitepress/theme/define.ts";

function defineAkariConfig(config: AkariSiteConfig): AkariDirectoryConfig;

Both levels of config file export their config with it. VitePress fields stay as they are. The theme's fields move under the themeConfig.akari that VitePress reads, and get type hints. The types are defined in docs/.vitepress/theme/types.ts.

Site and language ​

FieldTypeDefaultDescription
rootLanguagestringThe first language folder in alphabetical orderOnly takes effect in the shared config: the language folder served at the site root. Paths of the other languages start with their folder name
langstringThe language folder nameLanguage code. Used for <html lang>, and picks the language pack
labelstringThe language's own nameName in the language menu
dir"ltr" | "rtl" | "auto"The language pack'sText direction
titlestringNoneSite title; also the default app bar title
titleTemplatestring | booleanNoneSuffix or template for page titles, as in VitePress
descriptionstringNoneSite description
headHeadConfig[][]Extra <head> tags, merged with the level above
logostringNoneBrand image in the app bar and the footer
markdownMarkdownLocaleOptionsThe language pack'sThe language's text in Markdown, such as the tooltip of the code block copy button, laid over the language pack's

lang, label, dir and markdown describe a language and go in the language config. Every other field can go in the shared config as a default, and a language config can override it.

Theme fields ​

FieldContentsSee
appBarApp bar title, version, logo, buttons and social linksLayout and app bar
tocTable of contents on the rightLayout and app bar
loadingBarThe bar at the top of the window while a page loadsLayout and app bar
footerPager cards and footerLayout and app bar
sidebarCategories, navigation written by hand and drawer widthSide navigation
settingsSettings dialog and appearance buttonSettings and appearance
searchSearch entry and backendsSearch
messagesInterface textInternationalization
fontsWhether to load fonts from Google Fonts, and the font stackTypography
languagesLanguage packs besides the built-in ones, or changes to themInternationalization

Replacing interface components is not done in the config files; see Extending the theme.

.vitepress/config.mts ​

The part that wires the theme into VitePress. You rarely need to change it:

ts
import { fileURLToPath } from "node:url";
import { defineConfig } from "vitepress";
import { akariContent } from "./content";
import { akariHead } from "./theme/head";
import { akariMarkdown } from "./theme/markdown";

const docsDir = fileURLToPath(new URL("../", import.meta.url));
const content = await akariContent(docsDir);

export default defineConfig({
  ...content.site,
  cleanUrls: false,
  appearance: false,
  head: akariHead(),
  markdown: { config: (md) => akariMarkdown(md) },
  vue: {
    template: {
      compilerOptions: { isCustomElement: (tag) => tag.startsWith("m3e-") },
    },
  },
  vite: {
    plugins: [content.plugin],
  },
});
OptionPurpose
...content.sitelocales, rewrites and the site-level lang, title, description, generated from the folders; with local search, also themeConfig.search, which turns on VitePress' local search index
cleanUrls: falsePage paths end in .html and match the files in the output one to one; with true they have no extension, see Installation for hosting requirements
appearance: falseTurns off the light and dark toggle built into VitePress; the theme manages it
head: akariHead()A script that applies light or dark mode before the first frame
akariMarkdownM3 borders for tables and sizes for remote images
isCustomElementMakes Vue treat m3e-* as custom elements
content.pluginIn development, updates the navigation as Markdown files are added or removed and as frontmatter changes

akariContent ​

ts
function akariContent(
  srcDir: string,
  logger?: { warn(message: string): void },
): Promise<AkariContent>;

Reads the config files and folders in srcDir. logger defaults to console and receives notices such as pages outside the structure and parallel pages that cannot be found.

Returned fieldTypeDescription
site{ lang, title, description, locales, rewrites }Spread into defineConfig
pluginVite PluginUpdates the navigation in the dev server
route(page: string) => stringSource file path → page path, such as zh-CN/theme/layout/index.md → /zh-CN/theme/layout
rewrite(page: string) => stringSource file path → VitePress serving path, such as zh-CN/theme/layout/index.md → theme/layout.md
languages{ folder, key, prefix }[]Language folders, root language first. key is the VitePress locale key (root for the root language); prefix is the path prefix

akariHead ​

ts
function akariHead(options?: {
  storageKey?: string;
  defaultScheme?: "light" | "dark" | "auto" | "time";
}): HeadConfig[];

Returns an inline script that applies light or dark mode before the first frame is painted. The fonts' <head> tags differ by language, so akariContent writes them into each language's locale; see Typography. If you change settings.storageKey or settings.defaults.scheme, pass the same values here so the script reads the same settings.

akariMarkdown ​

ts
function akariMarkdown(
  md: MarkdownRenderer,
  options?: { remoteImageSize?: boolean | AkariImageSizeOptions },
): void;

Call it in markdown.config. It does two things:

  • Wraps every Markdown table in <div class="akari-table">, which gives the table an M3 outlined border and horizontal scrolling.
  • Writes the width and height of remote images with markdown-it-image-size. VitePress writes them for local images itself. See Writing pages.
OptionDefaultDescription
remoteImageSizetrueWith false, remote images are not measured. It can also hold the plugin's options, for example { cacheDir: ".image-size" } to keep the cache in the repository, or { cache: false } for no cache
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%