# Valaxy

Valaxy static blog framework built with Vue 3, Vite, and pnpm workspaces.

- Repository: https://github.com/YunYouJun/valaxy (1131 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add YunYouJun/valaxy --skill valaxy -g -a claude-code -y`
Codex: `npx skills add YunYouJun/valaxy --skill valaxy -g -a codex -y`
Cursor: `npx skills add YunYouJun/valaxy --skill valaxy -g -a cursor -y`
Gemini CLI: `npx skills add YunYouJun/valaxy --skill valaxy -g -a gemini-cli -y`

## Description

Valaxy static blog framework built with Vue 3, Vite, and pnpm workspaces. Use when working with Valaxy projects: (1) creating or configuring Valaxy blog sites (site.config.ts, valaxy.config.ts), (2) writing blog posts with frontmatter, (3) developing Valaxy themes (valaxy-theme-*), (4) developing Valaxy addons (valaxy-addon-*), (5) customizing components/layouts/styles, (6) working with the Valaxy monorepo core framework, (7) debugging Valaxy builds or dev server, (8) deploying Valaxy sites. Triggers on: valaxy.config.ts, site.config.ts, theme.config.ts, defineValaxyConfig, defineSiteConfig, defineThemeConfig, defineTheme, defineAddon, valaxy-theme-*, valaxy-addon-*, pages/posts/, ValaxyMain, useSiteConfig, useFrontmatter, #valaxy/config.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Valaxy

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

## Quick Reference

```bash
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)

```txt
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()`:

```ts
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

The rest: https://github.com/YunYouJun/valaxy/blob/HEAD/skills/valaxy/SKILL.md