Getting Started

Overview ​

总览 ​

Valaxy = V + Galaxy 旨在成为下一代静态博客框架，提供更好的热更新与用户加载体验、更强大更便捷的自定义开发可能性。

你可以在 为什么选 Valaxy 中了解更多关于项目的设计初衷。

TIP

Valaxy 基于 Vite 提供热更新与打包等功能，基于 Vue 实现视图（如主题、自定义组件）等客户端功能。

因此 Valaxy 兼容并可自由使用 Vite 与 Vue 生态的所有插件。

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.

TIP

Valaxy is based on Vite to provide hot reloading and packaging, and based on Vue to realize client functionalities such as views (themes, custom components).

Therefore, Valaxy supports all extensions/plugins for Vite and Vue.

Create a Valaxy Project ​

创建 Valaxy 项目 ​

Try it Online ​

在线试用 ​

你可以通过 StackBlitz 在线试用 Valaxy（默认使用主题 valaxy-theme-yun）。

StackBlitz

这是一个极简项目，您仅需以下几个文件，就可以快速搭建好你的博客！

  • pages 文件夹：存放页面/文章
  • valaxy.config.ts Valaxy 配置文件
  • package.json 记录依赖

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

StackBlitz

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

  • pages folder: storing the pages/posts
  • valaxy.config.ts: Valaxy’s configuration file
  • package.json: dependencies

Locally ​

在本地创建 ​

兼容

由于 Vite@7 要求 Node.js 的版本为 ^20.19.0 || >=22.12.0，Valaxy 同样需要你将 Node.js 升级至 20.19.0 版本之后。

TIP

如果您是 Windows 用户，我们强烈建议您使用类 Unix 的 Shell（如 Git Bash 或 WSL），而非 CMD / PowerShell.

如果您想要在本地创建，只需要执行以下命令：

Compatibility Note

Vite@7 requires Node.js version ^20.19.0 || >=22.12.0. Valaxy also requires you to upgrade Node.js after version 20.19.0.

TIP

If you are a Windows user, I strongly recommend using a Unix-like shell (such as Git Bash or WSL rather than CMD / PowerShell.

由于 npm init 会缓存您此前下载的版本，我更推荐您使用 pnpm 来创建模版。 安装 pnpm

Since npm init caches your previously downloaded version, I would recommend using pnpm to create templates. Install pnpm：npm i -g pnpm

bash
pnpm create valaxy
bash
npm init valaxy
You will be greeted with a few simple questions.
  🌌 Valaxy  v0.25.10

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

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

  Scaffolding project in valaxy-blog ...
  Done.

? Install and start it now? › (Y/n) Press Y

? Choose the agent › - Use arrow-keys. Return to submit.
    npm
    yarn
❯   pnpm 【Press Enter】

跟随命令行提示完成创建！

默认使用主题 valaxy-theme-yun，当然您也可以安装使用任意其他主题。 本文档同样是一个 Valaxy 主题 valaxy-theme-press，它的灵感来自 VitePress。

Follow the prompt in the commandline to complete the process!

The default theme used is valaxy-theme-yun, but you can also install any other themes. This documentation is also a Valaxy theme: valaxy-theme-press. It is inspired by VitePress.

Usage ​

使用 ​

进入你创建好后的文件夹目录后，执行以下命令。 譬如：cd valaxy-blog。

安装依赖：

Enter the folder for the Valaxy project you just created, and execute the following commands. For example: cd valaxy-blog.

Install the dependencies:

bash
# install
pnpm i
bash
# install
npm i

启动预览：

Start a preview:

bash
# start
pnpm dev
bash
# start
npm run dev

博客创建完毕，查看本地 http://localhost:4859/，玩的开心！

  • Valaxy 博客通用的配置可参见 配置 与 自定义扩展。
  • Valaxy 主题独有配置请参见对应主题文档。（Valaxy Theme Yun 主题文档编写中……）

See http://localhost:4859/, have fun!

  • See Config and Custom Extensions for the general configuration for Valaxy blogs.
  • For configuring Valaxy themes, please see the documentation for the corresponding themes. (Docs for Valaxy Theme Yun is still work in progress)

Config ​

配置 ​

Modify valaxy.config.ts to custom your blog.

Documentation is being improved!

修改 valaxy.config.ts 来自定义你的博客吧。

文档正在不断完善中！

Deployment ​

部署 ​

部署可参见 部署｜指南。

See Deployment for deployment guide.

Upgrading ​

升级 ​

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

pnpm ​

你可以使用 pnpm 的交互升级命令。

You can use the interactive upgrade command provided by pnpm.

bash
# 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.

在大部分情况下，你只需要在 pages 文件夹下进行工作，编写文章。

Main folders ​

主要的文件夹 ​

  • pages: your all pages
    • posts: write your posts here, will be counted as posts
  • styles: override theme styles, index.scss/vars.csss/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
  • pages: 你的所有页面
    • posts: 写在 pages/posts 文件夹下的内容，将被当作博客文章
  • styles: 覆盖主题样式，文件夹下的这些 scss 文件将会被自动加载
    • index.ts / index.scss / index.css
  • components: 自定义你的组件（将会被自动注册）
  • layouts: 自定义布局 (譬如可以通过 layout: xxx 来使用 layouts/xxx.vue 布局)
  • locales: 自定义国际化关键词

Others ​

其他 ​

  • .vscode: recommend some useful plugins & settings, you can preview icon/i18n/class…
  • .github: GitHub Actions to auto build & deploy to GitHub Pages
  • netlify.toml: for netlify
  • vercel.json: for vercel
  • .vscode: 推荐安装一些有用的 VSCode 插件，这样你可以直接预览一些图标、国际化、辅助的 CSS Class 等
    • 你可以在 VSCode 插件商店中找到 Valaxy 插件，它提供了文章列表预览/切换/删除等功能，让你尽可能地可以在 VSCode 中完成所有操作。
  • .github: 使用 GitHub Actions 自动构建并部署到 GitHub Pages
  • netlify.toml: Netlify 自动配置
  • vercel.json: Vercel 重定向配置

Themes ​

主题 ​

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

如果您希望自己开发一个主题并发布，您可以参考 valaxy-theme-starter。

更多内容请参见 如何编写一个 Valaxy 主题。

Community ​

社区 ​

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

如果你有疑问或者需要帮助，可以到 Discord 和 GitHub Discussions 社区来寻求帮助。

Contributors

Edit this page on GitHub

Last updated: