Valaxy Theme Starter

A runnable starting point for a Valaxy theme, with a separate demo that consumes the theme as a workspace package. Supports Valaxy 1.0.0-rc.14, Vue 3 and Vite 8. Requires Node.js 22.12+ and pnpm 10.

Create a theme

pnpm dlx degit valaxyjs/valaxy-theme-starter valaxy-theme-aurora
cd valaxy-theme-aurora
# Rename package references, configuration and component namespaces together.
pnpm theme:init aurora --owner your-github-name
pnpm install
pnpm dev

Use a lowercase kebab-case name without the valaxy-theme- prefix. --owner is optional. Initialization only runs on a fresh starter and refuses conflicting filenames. Review site metadata, package author and license attribution afterward. Retain existing copyright notices when reusing code.

Build with an AI coding assistant

Install the theme authoring Skill in your assistant's workspace:

pnpm dlx skills add YunYouJun/valaxy --skill valaxy-theme

Use the Skill for the reusable development workflow and the brief generator for this theme’s audience, visual direction and required blog features. Choose Design brief + Skill when the Skill is installed, or Standalone prompt for an assistant without Skill support. You do not need to maintain two copies of the framework instructions. The Skill guides the assistant through framework APIs, accessible reading layouts, SSG and package verification. It runs in your coding assistant; this template does not call an AI service or require an API key.

Example request:

Create an editorial Valaxy theme for a personal engineering blog. Use serif headings, a warm paper palette and an archive with title and tag filtering. Include light/dark modes, a long article with an outline and a mobile layout. Keep theme options typed. Run the checks and verify a packed theme in a clean consumer before finishing.

Workspace

• theme/: the distributable package, with components, layouts, styles, typed configuration and setup.
• docs/: a Press documentation site for the new theme, with local search and guide pages.
• demo/: a real blog using valaxy-theme-starter through workspace:* (renamed by theme:init).
• scripts/init-theme.mjs: one-time package and component initialization.
• AGENTS.md: concise authoring guidance for coding assistants.

Valaxy discovers styles/index.ts, setup/main.ts, components/ and layouts/ automatically. components/ValaxyMain.vue receives the Markdown content slot. Render it through ValaxyMd so built-in Markdown enhancements continue to work. Keep layouts/ thin and namespace ordinary theme components.

Validate and package

pnpm lint        # ESLint, Vue and formatting checks
pnpm build       # SSG demo and docs builds; also generates declarations
pnpm docs:dev    # develop theme documentation
pnpm build:site  # assemble demo at / and docs at /docs/ in dist/
pnpm typecheck   # Vue/TypeScript checks (run build first in a fresh checkout)
pnpm check       # all checks, including initializer tests
pnpm pack:theme  # writes a source-distributed .tgz under artifacts/

Also inspect the homepage and a long article in desktop/mobile browsers, keyboard navigation and both color schemes. Check a non-root Vite base for subdirectory hosting. Before release, install the .tgz in a fresh Valaxy blog and build it: a workspace build alone does not prove package portability.

Publish when ready

After reviewing package metadata and the packed archive, publish manually with pnpm --dir theme publish --access public --no-git-checks using your own npm credentials. The tag-triggered release workflow runs the checks and publishes the theme using your repository’s NPM_TOKEN secret. Configure it before creating a release tag. pnpm release runs the version helper; review its Git actions before accepting them.

CI exposes independent lint and typecheck jobs, plus Linux and Windows build/package checks on Node 22. pnpm check remains the local shortcut for all checks. The Pages workflow builds on pushes to main or manual dispatch and publishes the combined dist (demo at /, docs at /docs/) to gh-pages, preserving the starter’s branch-based hosting. In GitHub Pages settings, select Deploy from a branch, then gh-pages / (root). Set the demo Vite base and site URL for your hosting path, and remove or replace demo/public/CNAME if you use a custom domain.

License

MIT. The starter's original layout draws inspiration from vuejs/blog and tailwind-nextjs-starter-blog.

Theme documentation

Keep installation, theme options, examples and upgrade notes in docs/pages/. Link to the Valaxy website for common framework instructions. Theme initialization updates the docs package, references and edit links while preserving theme: 'press'. Set the demo and docs site URLs after initialization; the placeholder domain is example.com. For subdirectory hosting, set the docs Vite base to the demo base followed by docs/. The documentation workspace is private and is not included in the theme package.

Valaxy and Press 1.0.0-rc.14 include the documentation and local-search fixes used here. The workspace consumes their published packages directly and does not require compatibility patches.

The documentation keeps one set of English content URLs and includes both English and Chinese interface translations. This preserves the language preference shared with the demo without creating duplicate /zh/ documentation pages.