Vuemo

A lightweight blog framework built on VitePress: pick a theme, add plugins, and write in Markdown.

Vuemo is a thin layer on top of VitePress. VitePress stays the engine (Markdown, routing, build, HMR). Vuemo adds only what VitePress doesn't have: a post model, a theme contract and a small plugin interface.

Status: early development (alpha). APIs may change. Packages are published with the alpha tag: npm create vuemo@alpha my-blog. See docs/ for guides.

Packages

Path	Package	What it does
packages/core	@vuemo/core	Posts loader, tags / categories / archives, pagination, prev/next, JSON-LD, RSS, defineBlogConfig(), vuemo new and vuemo check-theme CLI
themes/default	@vuemo/theme-default	Minimal default theme (Tailwind CSS v4) and the reference implementation of the theme contract
plugins/comments	@vuemo/plugin-comments	Comments with Giscus or Utterances, synced with dark mode
plugins/ai-summary	@vuemo/plugin-ai-summary	"Summarize" button backed by your own Cloudflare Worker (Workers AI + AI Gateway)
packages/create-vuemo	create-vuemo	Project scaffolding (npm create vuemo): a blog (any theme with --theme) or a theme starter (--template theme)
examples/blog	—	Example blog used for development

What a blog looks like

my-blog/
├── posts/                    # Markdown posts
├── public/                   # static assets
├── themes/                   # only when you unzip a theme here
├── vuemo.config.ts           # all settings live here
└── .vitepress/               # boilerplate, you never open it
    ├── config.ts             # export { default } from '../vuemo.config'
    └── theme/index.ts        # export { default } from '@vuemo/core/theme'

All settings are in one place, defineBlogConfig. VitePress options keep working as usual.

// vuemo.config.ts
import { defineBlogConfig } from '@vuemo/core'

export default defineBlogConfig({
  // site
  title: 'My Blog',
  description: 'Notes',
  hostname: 'https://example.com',

  // theme
  theme: '@vuemo/theme-default',   // or a short name: 'trigger' (themes/trigger/ or vuemo-theme-trigger)
  postsPerPage: 5,
  nav: [{ text: 'Home', link: '/' }],

  // features: set a key to enable it, remove it or use `false` to disable it
  comments: { provider: 'utterances', repo: 'user/comments-repo' },
  aiSummary: false
})

Notes for new users: create-vuemo turns on search: true and markdown: { math: true } for you (both are off in plain defineBlogConfig); code block line numbers are opt-in (markdown: { lineNumbers: true }); the RSS feed at /feed.xml is written whenever hostname is set (rss: false turns it off). See Configuration.

Writing posts

vuemo new my-first-post   # creates posts/my-first-post.md

Frontmatter is defined by @vuemo/core; themes and plugins only depend on this:

---
title: My first post
date: 2025-01-01 10:00:00
category: Notes
tags:
  - vuemo
description: Optional summary
---

Themes

A theme is a regular VitePress theme that consumes data from @vuemo/core/client (usePosts, useTags, useCategories, useArchives, usePagination, usePrevNext, usePost, useTaxonomyLinks, useQueryParam). To be usable with Vuemo plugins, a theme must:

• implement the layouts home, post, archive, tag, category and page, chosen from frontmatter.layout only (a missing layout is page, other values are theme-defined; core gives posts/ pages the layout post)
• provide these slots in the post layout: post-before-content, post-after-content, post-comments, rendered with useSlots(name)
• call runEnhanceApps(ctx) from its enhanceApp
• put the class vuemo-content on the post body
• reflect dark mode through VitePress's isDark

To customize a theme, use VitePress's own extends and slots.

Switch themes by changing the theme option. npm install vuemo-theme-trigger and theme: 'trigger' is the whole job; or unzip a downloaded theme into themes/ (theme: 'trigger' finds themes/trigger/ first). create-vuemo --theme trigger does it for a new blog. See Themes. To build your own, start from npm create vuemo@alpha vuemo-theme-mine -- --template theme, check it with vuemo check-theme, and read Theme authoring.

Plugins

Official features (comments, aiSummary) are switched on in the config. Your own plugins go in plugins: []. A plugin is a function that returns an object; all fields are optional except name:

interface VuemoPlugin {
  name: string
  markdown?: (md: MarkdownRenderer) => void   // → markdown.config
  vite?: UserConfig['vite']                   // → merged into the vite config
  head?: HeadConfig[]                         // → site head
  transformPost?: (post: Post) => Post | void // → posts loader
  enhanceApp?: string                         // path of a client-side enhanceApp module
  slots?: Partial<Record<StandardSlot, string>> // component paths for the standard slots
}

Plugins that work with any theme live in plugins/. Plugins that only make sense for one theme live in themes/<theme>/plugins/. Both use the same interface.

Development

Requires Node.js >= 18.3 and pnpm (enabled through Corepack: corepack enable).

pnpm install
pnpm build                 # core, theme, plugins, then the example blog
pnpm test
pnpm --filter blog dev     # run the example blog

Build the packages once before starting the example (pnpm build); the default theme ships precompiled CSS.

Roadmap

• Core and default theme
• Plugin interface, comments and AI summary plugins
• create-vuemo scaffolding
• Documentation: see docs/
• RSS

License

MIT