Skip to content
 
 

Repository files navigation

English | 简体中文

Vitepress Theme Akari Docs

A Material You / Expressive stylized documentation theme for vitepress, built with @m3e/web Material 3 Expressive Web Components. Compared with Vitepress Theme Akari Blog, its layout is optimized for technical documentation.

Showcase

Requirements

  • Node.js >= 22.12
  • npm

Development

npm install
npm run dev

The default development address is http://localhost:5173.

Build and checks

npm run typecheck
npm test
npm run build
npm run preview

The production output is in docs/.vitepress/dist.

Configuration docs

For more configuration documentation for this theme, see here.

Q&A

Wow, a new theme!

Yay!

Wait, why named it Akari again, not MD3 docs??

Well you know I am just a complete idiot at naming things so...

But however I added "docs" suffix at the end of the name to distinguish from the Blog style theme, so that.

Why not just call it "vitepress-theme-akari-2"?

Just as I said above, it is optimized for technical documentation, not suitable for personal blog. You may think this theme just looks better than old ones, but I plan to redesign the styling in the future--stay tuned!

What else you want to say?

I dunno at this point, so that's all.

Using with the AkariBot docs engine

The theme is consumed as a source checkout. docs-theme.json at the repository root is the contract: it names the theme directory, the VitePress and Node versions, the npm dependencies, and the generated config options. The engine copies theme_dir into the generated site and never imports the theme code.

Set the theme in the instance's docs.toml:

[theme]
source = "file:/path/to/akari-bot-docs-template"

The following components are registered globally and are available to every Markdown page:

  • ModuleMeta — module name, aliases, capabilities, permission and platform badges.
  • ModuleConfig — config table and file path, or "the module has no config".
  • ModuleData — the tables the package owns and where their models live, or that it stores nothing.
  • ModuleAlias — module-level aliases; placed under a section heading, they apply to every command in it.
  • NoticeBox — tinted notice with info, tip, warning, danger, example or help.
  • ChatExample — a short chat transcript for a command: log takes 用户:… / 机器人:… lines (unprefixed lines continue the previous bubble), bubble text is rendered as Markdown only when a messages item sets markdown: true (log and unflagged messages stay plain; raw HTML is disabled), ![alt](src) renders a thumbnail that opens a zoomable, rotatable viewer (a trailing image starts its own bubble, and multiple trailing images share one bubble; append {natural} to show an image at its original size (tall images scale down to fit the viewport), image-width fixes every image in the example to one width, and card renders a bot card at the end), and botAvatar overrides the configured bot avatar; buttons adds message buttons whose replies are preloaded and appended with a loading state and a fade-in; a button can carry its own buttons for a second step, dismiss: true removes the button's reply group, and one-shot disables the other buttons in the same group after a click; the reset control restores the initial transcript; a line of three or more wave marks (〰〰〰) renders as a time separator.
  • CommandUsage — permission and alias badges, the usage line with the site's command prefix, an optional parameter list, and options as a list; params explains each <placeholder> (angle brackets are required, square brackets optional, derived from the usage text), the prefix comes from commandPrefix in the theme config, prefix overrides it, type is only set for non-prefix triggers such as regex, and platforms / excluded render platform availability badges.

They are styled with the M3E color tokens, so their surfaces follow the reader's seed color, light/dark scheme and contrast setting.

Releases

Packages

Used by

Contributors

Languages