Valaxy

Next-generation static blog framework: Vue 3 + Vite + UnoCSS + file-based routing + markdown-it.

Quick Reference

pnpm create valaxy          # scaffold new site
pnpm i                      # MUST use pnpm
pnpm dev                    # dev server at localhost:4859
pnpm build                  # SSG build to dist/

Two config files:

• site.config.ts, site metadata (title, author, social, search, comments) via defineSiteConfig()
• valaxy.config.ts, framework config (theme, addons, markdown, vite) via defineValaxyConfig<ThemeConfig>()
• Optional theme.config.ts, theme-specific via defineThemeConfig()

Posts go in pages/posts/*.md. Frontmatter controls title, date, tags, categories, cover, draft, encryption, layout, etc.

Key Patterns

Config Merging

Config sources merge via defu (user wins): Default → Theme → Addons → User.

File Resolution (Roots System)

roots = [clientRoot, themeRoot, ...addonRoots, userRoot]

User components/layouts/styles override theme which overrides core, by filename matching.

Routing

File-based via vue-router/vite. Files in pages/ become routes. Layout auto-assigned:

• pages/posts/** → post layout
• pages/tags/** → tags layout
• pages/categories/** → categories layout

Override with layout: xxx in frontmatter.

Collections

Define in pages/collections/{name}/index.ts using defineCollection():

import { defineCollection } from 'valaxy'

export default defineCollection({
  key: 'hamster',
  title: 'Hamster Stories',
  items: [
    { title: 'Chapter 1', key: '1' },
  ],
})

i18n

• CSS-based bilingual: ::: zh-CN / ::: en containers in markdown
• File-based: locales/*.yml
• Frontmatter: title: { en: 'Title', 'zh-CN': '标题' }
• Tags: $locale:tag.notes syntax

Custom Styles

Create styles/index.ts (or .scss/.css), auto-loaded. Override CSS vars for theming.

Custom Components