valaxy

# 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 Place `.vue` files in `components/` — auto-registered, overrides theme/core components by name. ## Monorepo Development When working on the Valaxy core framework itself: ```bash pnpm i # install all workspace deps pnpm run build # build core: utils → valaxy → devtools pnpm dev:lib # watch core packages pnpm demo # run demo site pnpm docs:dev # run docs site pnpm test # unit tests (vitest) pnpm e2e # E2E tests (playwright) pnpm lint # eslint pnpm typecheck # type check ``` ### Repository URL Normalization When displaying repository URLs from package.json, import and use `normalizeRepositoryUrl()` from `@valaxyjs/utils` to remove the `git+` prefix. ## References - **Generate or redesign a theme from a brief**: use the dedicated `valaxy-theme` skill from this repository (`pnpm dlx skills add YunYouJun/valaxy --skill valaxy-theme`). It covers a runnable theme/demo, UI-library integration and verification. - **Framework architecture, virtual modules, composables, components**: Read [references/architecture.md](references/architecture.md) - **Theme/addon development, post frontmatter, addon gallery**: Read [references/theme-addon-dev.md](references/theme-addon-dev.md)