Getting Started

Overview

总览

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

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

TIP提示

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

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

Create a Valaxy Project

创建 Valaxy 项目

Example: yun.valaxy.site

Try it Online

在线试用

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

StackBlitz

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

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

Locally

在本地创建

DANGER警告

如果您是 Windows 用户,我强烈建议您使用类 Unix 的 Shell(如 Git BashWSL),而非 CMD / PowerShell.

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

DANGER警告

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 valaxy

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

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

pnpm create valaxy

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

默认使用主题 valaxy-theme-yun,当然您也可以安装使用任意其他主题。
本文档同样是一个 Valaxy 主题 valaxy-theme-press

Usage

使用

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

安装依赖:

# install
npm i
# or pnpm i

启动预览:

# start
npm run dev
# or pnpm dev

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

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

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

Config

配置

Modify valaxy.config.ts to custom your blog.

Documentation is being improved!

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

文档正在不断完善中!

Deploy

部署

GitHub Pages 自动部署

上传至 GitHub Repo,打开 Settings -> Pages,选择 gh-pages 分支。

gh-pages 已由 .github/workflows/gh-pages.yml 自动部署。

自行部署

# 构建打包
npm run build
# dist 文件夹为构建后的内容

可使用 Netlify/Vercel/Render/Cloudflare Pages 等进行托管。

Upgrade

升级

cd your-blog
# upgrade valaxy
npm i [email protected]
# upgrade theme
npm i [email protected]

pnpm

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

# interactive upgrade
pnpm up --latest -i

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.scss / index.css
    • css-vars.scss / css-vars.css
  • components: 自定义你的组件(将会被自动注册)
  • layouts: 自定义布局 (譬如可以通过 layout: xxx 来使用 layouts/xxx.vue 布局)
  • locales: 自定义国际化关键词

Other

其他

  • .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 等
  • .github: 使用 GitHub Actions 自动构建并部署到 GitHub Pages
  • netlify.toml: Netlify 自动配置
  • vercel.json: Vercel 重定向配置

Theme

主题

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.

如果你有疑问或者需要帮助,可以到 DiscordGitHub Discussions 社区来寻求帮助。


Q.E.D.