Vitepress Theme Akari Docsv1.0.0GitHubSettingsMore

Settings and appearance: API ​

settings ​

FieldTypeDefaultDescription
enabledbooleantrueWhether there is a settings dialog; when false, the gear button is hidden too
showSchemeTogglebooleantrueWhether to show the appearance button; independent of enabled
titlestringDepends on the language: "Settings"Title of the settings dialog
sectionsSettingsSectionKey[]All sixWhich options to show, and in what order
labelsPartial<Record<SettingsSectionKey, string>>Depends on the languageOverrides the titles of individual options
defaultsPartial<AkariThemeSettings>See the table belowThe appearance every reader sees on their first visit
persistbooleantrueWhether to write the reader's choices to localStorage
storageKeystring"akari-docs-settings"Key name in localStorage

appBar.showSettingsToggle: false only hides the gear button. The settings feature itself stays (for example, a custom component can open it).

ts
settings: {
  sections: ["color", "textSize"],
  labels: { textSize: "Body text size" },
  defaults: { color: "#0b57d0", scheme: "time" },
},

Invalid entries in sections are filtered out, and only the first of any duplicates is kept. If the result is empty, all six options are shown.

AkariThemeSettings ​

FieldOption keyValuesDefault
colorcolorSix-digit hex color"#6750A4"
variantvarianttonal-spot, vibrant, fidelity, expressive, monochrome, neutral, rainbow, fruit-salad"tonal-spot"
schemeAppearance buttonauto, light, dark, time"auto"
contrastcontraststandard, medium, high"standard"
motionmotionstandard, expressive"expressive"
directiondirectionauto, ltr, rtl"auto"
textSizetextSize16px, 24px, 32px (shown as 100%, 150%, 200%)"16px"

akariHead and light and dark mode ​

head: akariHead() in .vitepress/config.mts includes a script that applies light and dark mode before the first frame is painted. If you change storageKey or defaults.scheme, pass the same values to it:

ts
head: akariHead({ storageKey: "my-docs", defaultScheme: "time" }),

Also keep appearance: false, so that the theme alone manages html.dark.

Storage format ​

localStorage[storageKey] holds a JSON object with the same fields as AkariThemeSettings:

json
{
  "color": "#6750A4",
  "variant": "tonal-spot",
  "scheme": "dark",
  "contrast": "standard",
  "motion": "expressive",
  "direction": "auto",
  "textSize": "16px"
}

Each missing or invalid field falls back to its default on its own.

useAkariSettings ​

ts
import { useAkariSettings } from "@theme";

const { settings, setSetting, reset, isDefault } = useAkariSettings();
setSetting("textSize", "24px");
Return valueDescription
settingsThe current settings, as a reactive object
setSetting(key, value)Changes one setting; when persist is true, also writes it to localStorage
reset()Restores the defaults
isDefault()Whether every current setting equals its default
defaultsThe merged defaults
sections, labelsThe resolved list of options and their titles

useAkariColorScheme ​

ts
import { useAkariColorScheme } from "@theme";

const { mode, resolved, cycle } = useAkariColorScheme();
Return valueTypeDescription
modeComputedRef<"auto" | "light" | "dark" | "time">The mode the reader chose
resolvedRef<"light" | "dark" | null>Whether the page actually shows light or dark; null until it is mounted in the browser
cycle()() => voidSwitches to the next mode: System → Light → Dark → Time of day → System

Call both functions only from components inside the layout.

Replacing the settings panel ​

You can replace the panel in the settings dialog with your own component (slot Settings). The title, the close button and the motion are still provided by the dialog. See Extending the theme.

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%