Vitepress Theme Akari Docsv1.0.0GitHubSettingsMore

Hero: API ​

hero ​

hero in the page frontmatter. Written as a string, it is the image URL.

FieldTypeDefaultDescription
imagestring | { src, alt? } | { light, dark, alt? }RequiredImage URL; site paths get base added automatically, and external URLs are used as they are. Written as { light, dark }, the two images are used in light and dark mode
altstring""Alt text of the image; leave it empty for a purely decorative image
datestring | DateNoneShown above the title. A date such as 2026-05-19 is formatted for the page language and output as a tag such as <time datetime="2026-05-19">; any other text shows as written
taglinestringThe page's descriptionOne-line summary below the title
backgroundstring--md-sys-color-primary-containerBackground color of the image card; any CSS color or token
fit"cover" | "contain""cover"cover fills the card and crops what does not fit; contain shows the whole image with a margin, suited to illustrations with a transparent background
colorstring | falseTaken from the imageTheme seed color of this page: #rrggbb fixes it to that color, false keeps the color the reader chose in settings
pattern"dots" | "grid" | "plus" | "diagonal" | "waves" | "none" | "auto""auto"Hidden pattern on the page: dots, grid, plus signs, diagonal lines, waves; none shows no pattern, auto picks one at random each time content loads

pattern applies to the whole page: the hero cards and the elements with a background in the content use the same pattern. Pages without a hero also pick one at random.

yaml
hero:
  image:
    light: /hero/theme-hero.svg
    dark: /hero/theme-hero-dark.svg
    alt: The docs theme's interface in a desktop window and on a phone
  date: 2026-10-28
  tagline: Put an image in the frontmatter
  fit: contain
  color: "#6750a4"
  pattern: dots

CSS variables ​

VariableDefaultPurpose
--akari-doc-hero-inset8pxDistance between the cards and the surface edges, and between the two cards
--akari-doc-hero-text-color--md-sys-color-surface-containerBackground color of the text card
--akari-doc-hero-media-color--md-sys-color-primary-containerDefault background color of the image card; background takes precedence
--akari-pattern-glow4%Strength of the glow around the pointer
--akari-pattern-spot0.1How clearly the pattern shows inside the glow

You can set the first three on :root. The two pattern variables are defined on the document surface .akari-doc, so override them on .akari-doc as well.

Replacing the hero component ​

You can replace the hero with your own component; see Extending the theme. The layout renders this component only when the page sets a hero with an image, and it hides the first h1 of the content, so a custom component must render the page title itself. Give the title the data-akari-page-title attribute, and the app bar's title swap follows it. In the component, read the frontmatter with VitePress's useData(). The layout gives the component's root element the akari-doc__page class, so when you switch between the parallel pages of a group the hero slides sideways with the content; a component with several root nodes does not get the class, and its hero stays where it is.

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%