Getting Started

Overview ​

Valaxy = V + Galaxy aims for the next generation static blog framework, providing better hot reloading and user loading experience, with easier and powerful customization support.

You can learn more about the original intensions for this project in Why Valaxy.

Create a Valaxy Project ​

Example: yun.valaxy.site

Try it Online ​

You can use StackBlitz to try Valaxy online (the default theme used is valaxy-theme-yun).

This is an extremely simple project. You only need the following files to rapidly build your own blog!

• pages folder: storing the pages/posts
• site.config.ts: site information
• valaxy.config.ts: theme and framework configuration
• package.json: dependencies

Locally ​

Check your installed versions:

node --version
pnpm --version

Run this in the directory where you want to create your blog:

pnpm create valaxy@latest

Choose these answers in order:

1. Select a type: → Blog.
2. Select a theme: → Yun, the default blog theme used in this guide.
3. Project name: → valaxy-blog, or another directory that does not exist yet.
4. Install and start it now? → No, then install and start manually below. If you choose Yes, select pnpm and continue with “Write your first post” once the server starts.

  🌌 Valaxy  v1.1.0

? Select a type: › - Use arrow-keys. Return to submit.
❯   Blog - For Most Users 【Press Enter】
    Theme - For Theme Developers
    Addon - For Addon Developers

? Select a theme:
❯   Yun - A light & clean theme (default) 【Press Enter】
    Press - A document-oriented theme
    Custom - Enter a custom theme name

? Project name: › valaxy-blog 【Press Enter】
  📁 /root/repos/valaxy-blog

  Scaffolding project in valaxy-blog ...
  Done.

? Install and start it now? › (Y/n) 【Press N, Enter】

  start it later by:

  cd valaxy-blog
  pnpm install
  pnpm run dev

Select a Theme ​

• Yun: The default blog theme, used throughout this guide.
• Press: A documentation theme.
• Custom: Enter a theme name such as starter or valaxy-theme-starter.

The scaffolder configures the theme dependency and valaxy.config.ts. Press also has its own home page and configuration templates. Refer to the selected theme’s documentation for its options.

Usage ​

Enter the new project, install dependencies, and start the development server:

cd valaxy-blog
pnpm install
pnpm dev

Keep the generated pnpm-workspace.yaml: it contains dependency installation settings, including build script permissions. pnpm 11 and later stop installation when dependency scripts have not been reviewed. The template configures its current dependencies, so the initial install does not require an extra approve-builds step.

$ pnpm dev

✔ Resolve userValaxyConfig from /path/to/valaxy-blog/valaxy.config.ts
✔ Resolve siteConfig from /path/to/valaxy-blog/site.config.ts
✔ Resolve valaxy.config.ts from theme(yun)
✔ Resolve addons from /path/to/valaxy-blog
✔ [valaxy] server ready.

  🌌 Valaxy  v1.1.0

  🪐 theme   > yun (v1.1.0)
  📁 /path/to/valaxy-blog

  Preview    > http://localhost:4859/

  shortcuts  > restart | open | qr | edit

Open the address printed after Preview, usually http://localhost:4859/. If that port is occupied, Valaxy chooses another available port, so use the terminal’s address. The home page should show Hello, Valaxy!; click its title to open the example post.

pnpm dev keeps running. Leave this terminal open while editing the project. To run another command, open a second terminal in the same project directory. Stop the server with Ctrl+C.

Write your first post ​

Create pages/posts/first-post.md with this content:

---
title: My first post
date: 2026-10-05
tags:
  - Notes
---

## Hello, Valaxy

This is my first post.

Use your publication date. The block between --- markers contains post metadata; the rest is Markdown content. Saving the file updates the home page’s post list. Open /posts/first-post to read it. The example post has top: 1, so it stays above the new post.

Alternatively, run pnpm exec valaxy new first-post in the project directory to generate a post file, then edit it. If the file already exists, the command creates a numbered filename; check the path printed in the terminal.

Configure your site ​

Edit the corresponding fields in site.config.ts to set your site title, author, and description. For example:

import { defineSiteConfig } from 'valaxy'

export default defineSiteConfig({
  url: 'https://example.com/',
  lang: 'en',
  timezone: 'UTC',
  title: 'My blog',
  author: {
    name: 'Alex',
  },
  description: 'Notes on life and technology.',
})

url is your production address, used for post links, the sitemap, and RSS. Replace https://example.com/ with your own address before deployment. It does not change the development server address. After saving, check the browser title, sidebar site name, and post author.

Keep timezone, or set it to your site’s timezone, such as Asia/Shanghai. An explicit timezone keeps displayed post times consistent between the build server and visitors. valaxy new includes a timezone offset in its timestamps. When writing dates manually, use YYYY-MM-DD as above, or include an offset for a precise time, such as 2026-10-05T14:30:00+08:00.

valaxy.config.ts contains theme and framework options. The large text on the Yun home page is configured separately through themeConfig.banner.title. Change it to your preferred text. The template’s social links, sponsorship details, and footer registration information are also examples; replace or disable them before deployment.

See Site configuration and Custom extensions for more options.

Your first production build ​

Stop the development server, then run these commands in your project:

pnpm build
pnpm serve

The template’s build script runs valaxy build --ssg, prerendering pages into dist/. Wait for the build to exit successfully before running pnpm serve. It previews the generated output, usually at http://localhost:4173/; use the address printed in the terminal.

Check that:

• The home page shows your site name and links to your new post.
• Opening /posts/first-post directly shows the article, including after a refresh.
• dist/index.html and dist/posts/first-post.html contain the corresponding page content.
• dist/sitemap.xml and dist/atom.xml use the site address from site.config.ts.

pnpm serve does not rebuild your site. Run pnpm build again after editing. Follow the deployment guide to upload the output to a static host.

Deployment ​

Deploy the generated dist/ directory to a static host. See the deployment guide for the steps.

Upgrading ​

cd your-blog
# upgrade valaxy
pnpm add valaxy@latest
# upgrade theme
pnpm add valaxy-theme-yun@latest

cd your-blog
# upgrade valaxy
bun add valaxy@latest
# upgrade theme
bun add valaxy-theme-yun@latest

cd your-blog
# upgrade valaxy
npm i valaxy@latest
# upgrade theme
npm i valaxy-theme-yun@latest

pnpm ​

You can use the interactive upgrade command provided by pnpm.

# interactive upgrade
pnpm up --latest -i

Migration ​

If you are from another blog framework, you can refer to Migration.

Directory Structure ​

In most cases, you only need to work in the pages folder.

Main folders ​

• pages: your all pages
  • posts: write your posts here, will be counted as posts
• styles: override theme styles, index.scss/css-vars.scss/index.css will be loaded automatically
• components: custom your vue components (will be loaded automatically)
• layouts: custom layouts (use it by layout: xxx in md)
• locales: custom i18n

Others ​

• .vscode: recommend some useful plugins & settings, you can preview icon/i18n/class…
  • Optionally install the Valaxy VS Code extension for a post list and local site preview. See its documentation for setup, settings, and compatibility notes.
• .github: GitHub Actions to auto build & deploy to GitHub Pages
• netlify.toml: for netlify
• vercel.json: for vercel

Themes ​

If you want to develop a theme and released, you can refer to valaxy-theme-starter.

Community ​

If you have questions or need help, you can go to the Discord and Discussions to ask for help.