docs: complete basic getting-started

This commit is contained in:
YunYouJun 2022-07-20 22:15:50 +08:00
parent 86026e9798
commit 6f80973fa1
10 changed files with 319 additions and 129 deletions

View File

@ -23,37 +23,9 @@ Valaxy aims to be a next generation of static blogging frameworks/generators.
Valaxy 的目标是成为新一代的静态博客框架/生成器。
:::
## 为什么是 Valaxy? {lang="zh-CN"}
构想新一代静态博客框架/生成器。
<!-- more -->
「告诉你两件好事吧」,第一它与 Hexo 相比开发体验和速度上都更胜一筹,第二它与 VitePress/VuePress 相比拥有更多针对博客的集成功能,譬如文章列表钩子、自动路由与组件注册、可覆盖的布局与主题等。
一味地讲述 Valaxy 的优点似乎有些难以理解。
我将会把 Valaxy 与现有的 Hexo流行的静态博客框架与 VitePress/VuePress流行的静态站点生成器进行对比并阐述 Valaxy 的优势。
::: en
## Why Valaxy? {lang="en"}
Next Generation Static Blog Framework/Generator
<!-- more -->
「Two things to tell you」, first, compared with Hexo, Valaxy is superior in both development experience and speed, second, compared with VitePress/VuePress, Valaxy has more integration features for blogs, such as article list hook, automatic routing and component registration, overlay layout and theme, etc.
It seems hard to understand the advantages of Valaxy.
I will compare Valaxy with the existing Hexo (popular static blog framework) and vitepress / vuepress (popular static site generator), and explain the advantages of Valaxy.
:::
More info see [valaxy.site](https://valaxy.site).
```ts
import type { UserConfig } from 'valaxy'
import type { ThemeUserConfig } from 'valaxy-theme-yun'
/**
* User Config
* do not use export const, because c12 will set as child property
@ -71,51 +43,3 @@ const config: UserConfig<ThemeUserConfig> = {
export default config
```
::: zh-CN
配置、文章热更新
而不是像 hexo 一样重新加载页面
:::
::: en
Hot update for configuration, article.
Instead of reloading pages like hexo
:::
### Motivation
- Slidev
- VitePress
- Vitesse
## Why not ...?
### Hexo/Hugo
### Vuepress/Vitepress
### iles
- [iles](https://github.com/ElMassimo/iles)
::: zh-CN
在完成了 Valaxy 基础结构的开发后,我从群友处得知了 iles这和我实现的许多功能十分相似。
它相比 Vitepress 拥有更多功能,也很适合写一个拥有更多交互的文档。
不过它的定位仍旧是静态站点生成器,这与 Valaxy 静态博客生成器的定位不同。
因为 Valaxy 除此之外,还会提供文章列表、分页、标签、分类等更多面向博客的功能,并支持扩展与自定义博客主题。
:::
::: en
After completing the development of Valaxy's basic structures, I learned about iles from my group friend, which is very similar to many features I have archieved.
It has more features than Vitepress and is also suitable for writing a document with more interaction.
However, its positioning is still static site generator, which is different from that of Valaxy static blog generator.
In addition, Valaxy also provides more blog oriented features such as article list, pagination, tag and category, and supports extension and customization of blog topics.
:::

View File

@ -1,5 +1,6 @@
---
title: FAQ
title_zh: 常见问题
categories:
- Guide
end: false

View File

@ -89,7 +89,9 @@ export default {
> 更多请参见 [valaxy-theme-yun](https://github.com/YunYouJun/valaxy/tree/main/packages/valaxy-theme-yun) 代码。
## File-based Routing
## File-based Routing {lang="en"}
## 基于文件的自动路由 {lang="zh-CN"}
Routes will be auto-generated for Vue files in this dir with the same file structure.
Check out [`vite-plugin-pages`](https://github.com/hannoeru/vite-plugin-pages) for more details.
@ -124,7 +126,9 @@ npm run rss
# valaxy rss
```
## i18n in One Page
## i18n in One Page {lang="en"}
## 单页 i18n {lang="zh-CN"}
More info see [i18n](/docs/guide/i18n).

View File

@ -3,12 +3,48 @@ title: Getting Started
title_zh: 开始
categories:
- Guide
end: false
end: true
top: 99
---
## Overview {lang="en"}
## 总览 {lang="zh-CN"}
Valaxy V + Galaxy旨在成为下一代静态博客框架提供更好的热更新与用户加载体验、更强大更便捷的自定义开发可能性。
你可以在 [为什么选 Valaxy](/guide/why) 中了解更多关于项目的设计初衷。
::: tip
Valaxy 基于 [Vite](https://vitejs.dev/) 提供热更新与打包等功能,基于 [Vue](https://vuejs.org/) 实现视图(如主题、自定义组件)等客户端功能。
因此 Valaxy 兼容并可自由使用 Vite 与 Vue 生态的所有插件。
:::
## Create a Valaxy Project {lang="en"}
## 创建 Valaxy 项目 {lang="zh-CN"}
> Example: [yun.valaxy.site](https://yun.valaxy.site)
### Try it Online {lang="en"}
### 在线试用 {lang="zh-CN"}
你可以通过 [StackBlitz](https://stackblitz.com/edit/valaxy) 在线试用 Valaxy默认使用主题 [valaxy-theme-yun](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/))。
[![StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/valaxy)
> 这是一个极简项目,您仅需一下几个文件,就可以快速搭建好你的博客!
>
> - `pages` 文件夹:存放页面/文章
> - `valaxy.config.ts` Valaxy 配置文件
> - `package.json` 记录依赖
### Locally {lang="en"}
### 在本地创建 {lang="zh-CN"}
<div lang="zh-CN">
::: danger
@ -17,6 +53,8 @@ top: 99
:::
如果您想要在本地创建,只需要执行以下命令:
</div>
<div lang="en">
@ -29,25 +67,82 @@ If you are a Windows user, I strongly recommend using a Unix-like shell (such as
</div>
## Create
```bash
npm init valaxy
```
::: zh-CN
> 由于 `npm init` 缓存您此前下载的版本,我更推荐您使用 `pnpm` 来创建模版。
> 由于 `npm init` 缓存您此前下载的版本,我更推荐您使用 `pnpm` 来创建模版。
> 安装 [pnpm](https://pnpm.io/)`npm i -g pnpm`
:::
::: en
> Since `npm init` caches your previously downloaded version, I would recommend using `pnpm` to create templates.
> Since `npm init` caches your previously downloaded version, I would recommend using `pnpm` to create templates.
> Install [pnpm](https://pnpm.io/)`npm i -g pnpm`
:::
```bash
pnpm create valaxy
```
## Upgrade
跟随命令行提示完成创建!
> 默认使用主题 [valaxy-theme-yun](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/),当然您也可以安装使用任意其他主题。
> 本文档同样是一个 Valaxy 主题 [valaxy-theme-press](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-press/)。
## Usage {lang="en"}
## 使用 {lang="zh-CN"}
> 进入你创建好后的文件夹目录后,执行以下命令。
> 譬如:`cd valaxy-blog`。
安装依赖:
```bash
# install
npm i
# or pnpm i
```
启动预览:
```bash
# start
npm run dev
# or pnpm dev
```
::: zh-CN
博客创建完毕,查看本地 `http://localhost:4859/`,玩的开心!
:::
::: en
See `http://localhost:4859/`, have fun!
:::
- Valaxy 博客通用的配置可参见 [配置](/guide/config) 与 [自定义扩展](/guide/extend)。
- Valaxy 主题独有配置请参见对应主题文档。Valaxy Theme Yun 主题文档编写中……)
### Config {lang="en"}
### 配置 {lang="zh-CN"}
::: en
Modify `valaxy.config.ts` to custom your blog.
Documentation is being improved!
:::
::: zh-CN
修改 `valaxy.config.ts` 来自定义你的博客吧。
文档正在不断完善中!
:::
## Upgrade {lang="en"}
## 升级 {lang="zh-CN"}
```bash
cd your-blog
@ -59,38 +154,30 @@ npm i valaxy-theme-yun@latest
### pnpm
> 你可以使用 pnpm 的交互升级命令。
```bash
# interactive upgrade
pnpm up --latest -i
```
## Usage
## Structure {lang="en"}
```bash
# install
npm i
# or pnpm i
# start
npm run dev
# or pnpm dev
```
See `http://localhost:4859/`, have fun!
### Config
Modify `valaxy.config.ts` to custom your blog.
English & Chinese Docs is coming!
> Wait a minute.
## Structure
## 目录结构 {lang="zh-CN"}
::: en
In most cases, you only need to work in the `pages` folder.
:::
### Main folders
::: zh-CN
在大部分情况下,你只需要在 `pages` 文件夹下进行工作,编写文章。
:::
### Main folders {lang="en"}
### 主要的文件夹 {lang="zh-CN"}
::: en
- `pages`: your all pages
- `posts`: write your posts here, will be counted as posts
@ -99,12 +186,62 @@ In most cases, you only need to work in the `pages` folder.
- `layouts`: custom layouts (use it by `layout: xxx` in md)
- `locales`: custom i18n
### Other
:::
::: zh-CN
- `pages`: 你的所有页面
- `posts`: 写在 `pages/posts` 文件夹下的内容,将被当作博客文章
- `styles`: 覆盖主题样式,文件夹下的 `index.scss`/`css-vars.scss`/`index.css`/`css-vars.css` 将会被自动加载
- `components`: 自定义你的组件(将会被自动注册)
- `layouts`: 自定义布局 (譬如可以通过 `layout: xxx` 来使用 `layouts/xxx.vue` 布局)
- `locales`: 自定义国际化关键词
:::
### Other {lang="en"}
### 其他 {lang="zh-CN"}
::: en
- `.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](https://www.netlify.com/)
- `vercel.json`: for [vercel](https://vercel.com/)
:::
::: zh-CN
- `.vscode`: 推荐安装一些有用的 VSCode 插件,这样你可以直接预览一些图标、国际化、辅助的 CSS Class 等
- `.github`: 使用 GitHub Actions 自动构建并部署到 GitHub Pages
- `netlify.toml`: [Netlify](https://www.netlify.com/) 自动配置
- `vercel.json`: [Vercel](https://vercel.com/) 重定向配置
:::
## Theme {lang="en"}
## 主题 {lang="zh-CN"}
::: en
If you want to develop a theme and released, you can refer to [valaxy-theme-starter](https://github.com/YunYouJun/valaxy-theme-starter).
:::
::: zh-CN
如果您希望自己开发一个主题并发布,您可以参考 [valaxy-theme-starter](https://github.com/YunYouJun/valaxy-theme-starter)。
更多内容请参见 [如何创建一个 Valaxy 主题](/themes).
:::
## Community {lang="en"}
## 社区 {lang="zh-CN"}
::: en
If you have questions or need help, you can go to the [Discord](https://discord.gg/nd3mPkU5j8) and [Discussions](https://github.com/YunYouJun/valaxy/discussions) to ask for help.
:::
::: zh-CN
如果你有疑问或者需要帮助,可以到 [Discord](https://discord.gg/nd3mPkU5j8) 和 [GitHub Discussions](https://github.com/YunYouJun/valaxy/discussions) 社区来寻求帮助。
:::

123
docs/pages/guide/why.md Normal file
View File

@ -0,0 +1,123 @@
---
cover: https://fastly.jsdelivr.net/gh/YunYouJun/cdn/img/bg/girl-in-water-tank.webp
title: Why Valaxy
title_zh: 为什么选 Valaxy
date: 2022-03-22
updated: 2022-03-23
categories:
- Guide
tags:
- valaxy
- 笔记
top: 100
outline: deep
---
## What is Valaxy? {lang="en"}
::: en
Valaxy aims to be a next generation of static blogging frameworks/generators.
:::
## 什么是 Valaxy? {lang="zh-CN"}
::: zh-CN
Valaxy 的目标是成为新一代的静态博客框架/生成器。
:::
## 为什么是 Valaxy? {lang="zh-CN"}
构想新一代静态博客框架/生成器。
<!-- more -->
「告诉你两件好事吧」,第一它与 Hexo 相比开发体验和速度上都更胜一筹,第二它与 VitePress/VuePress 相比拥有更多针对博客的集成功能,譬如文章列表钩子、自动路由与组件注册、可覆盖的布局与主题等。
一味地讲述 Valaxy 的优点似乎有些难以理解。
我将会把 Valaxy 与现有的 Hexo流行的静态博客框架与 VitePress/VuePress流行的静态站点生成器进行对比并阐述 Valaxy 的优势。
::: en
## Why Valaxy? {lang="en"}
Next Generation Static Blog Framework/Generator
<!-- more -->
「Two things to tell you」, first, compared with Hexo, Valaxy is superior in both development experience and speed, second, compared with VitePress/VuePress, Valaxy has more integration features for blogs, such as article list hook, automatic routing and component registration, overlay layout and theme, etc.
It seems hard to understand the advantages of Valaxy.
I will compare Valaxy with the existing Hexo (popular static blog framework) and vitepress / vuepress (popular static site generator), and explain the advantages of Valaxy.
:::
```ts
import type { UserConfig } from 'valaxy'
import type { ThemeUserConfig } from 'valaxy-theme-yun'
/**
* User Config
* do not use export const, because c12 will set as child property
*/
const config: UserConfig<ThemeUserConfig> = {
theme: 'yun',
themeConfig: {
banner: {
enable: true,
title: '云游君的小站',
},
},
}
export default config
```
::: zh-CN
配置、文章热更新
而不是像 hexo 一样重新加载页面
:::
::: en
Hot update for configuration, article.
Instead of reloading pages like hexo
:::
### Motivation
- Slidev
- VitePress
- Vitesse
## Why not ...?
### Hexo/Hugo
### Vuepress/Vitepress
### iles
- [iles](https://github.com/ElMassimo/iles)
::: zh-CN
在完成了 Valaxy 基础结构的开发后,我从群友处得知了 iles这和我实现的许多功能十分相似。
它相比 Vitepress 拥有更多功能,也很适合写一个拥有更多交互的文档。
不过它的定位仍旧是静态站点生成器,这与 Valaxy 静态博客生成器的定位不同。
因为 Valaxy 除此之外,还会提供文章列表、分页、标签、分类等更多面向博客的功能,并支持扩展与自定义博客主题。
:::
::: en
After completing the development of Valaxy's basic structures, I learned about iles from my group friend, which is very similar to many features I have archieved.
It has more features than Vitepress and is also suitable for writing a document with more interaction.
However, its positioning is still static site generator, which is different from that of Valaxy static blog generator.
In addition, Valaxy also provides more blog oriented features such as article list, pagination, tag and category, and supports extension and customization of blog topics.
:::

View File

@ -9,12 +9,15 @@ top: 50
::: tip
Valaxy 与 Vite/Vue 的生态完全兼容,因此你可以像写一个 Vite 插件一样,在主题中自由地扩展
Valaxy 与 Vite/Vue 的生态完全兼容,因此你在编写主题时,可以任意使用第三方的 Vite/Vue 插件
- [Authoring a Plugin | Vite](https://vitejs.dev/guide/api-plugin.html#authoring-a-plugin)
- [Writing a Plugin | Vue](https://vuejs.org/guide/reusability/plugins.html#writing-a-plugin)
:::
撰写中...
## APIs
我们提供了一个扩展函数,以供你快速扩展页面信息。
@ -22,19 +25,17 @@ Valaxy 与 Vite/Vue 的生态完全兼容,因此你可以像写一个 Vite 插
你也可以直接扩展 [vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages) 插件中的 `extendRoute`
```ts
// vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
valaxy: {
pages: {
extendRoute(route, parent) {
console.log(route)
},
},
extendMd(ctx) {
console.log(ctx.path)
// valaxy.config.ts
import { defineTheme } from 'valaxy'
export default defineTheme({
pages: {
extendRoute(route, parent) {
console.log(route)
},
},
extendMd(ctx) {
console.log(ctx.path)
},
})
```

View File

@ -1,5 +0,0 @@
import { defineConfig } from 'vite'
export default defineConfig({
})

View File

@ -28,10 +28,15 @@ const collapsable = ref(props.collapsable)
.post-list-item {
a {
color: var(--va-c-text-light);
transition: all 0.2s;
&:hover {
color: var(--va-c-primary);
}
&.active {
color: var(--va-c-primary);
}
}
}

View File

@ -41,8 +41,8 @@ const getTitle = (post: Post | any) => {
<template v-if="!collapsable">
<ul v-if="!isParentCategory(category)">
<li v-for="post, i in category.posts" :key="i" class="post-list-item" m="l-4">
<router-link v-if="post.title" :to="post.path || ''" class="inline-flex items-center">
<span m="l-1">{{ getTitle(post) }}</span>
<router-link v-if="post.title" :to="post.path || ''" class="inline-flex items-center" active-class="active">
<span m="l-1" text="sm">{{ getTitle(post) }}</span>
</router-link>
</li>
</ul>

View File

@ -27,7 +27,7 @@ const collapsable = ref(props.collapsable)
<style lang="scss">
.post-list-item {
a {
color: var(--va-c-text);
color: var(--va-c-text-lighter);
&:hover {
color: var(--va-c-primary);