docs: add commands & getting started & custom sidebar styles

.vscode/settings.json

@@ -1,5 +1,16 @@
 {
-  "cSpell.words": ["algoliasearch", "instantsearch", "valaxy", "valaxyjs", "beian", "jiti", "unconfig", "defu", "twikoo"],
+  "cSpell.words": [
+    "algoliasearch",
+    "beian",
+    "defu",
+    "instantsearch",
+    "jiti",
+    "twikoo",
+    "unconfig",
+    "vala",
+    "valaxy",
+    "valaxyjs"
+  ],
   "i18n-ally.sourceLanguage": "en",
   "i18n-ally.keystyle": "nested",
   "i18n-ally.localesPaths": ["packages/valaxy/src/client/locales"],

docs/pages/guide/commands.md

@@ -0,0 +1,75 @@
+---
+title: Commands
+title_zh: 命令行
+categories:
+  - Guide
+top: 99
+---
+
+Valaxy 内置了辅助命令行，你可使用 `valaxy` 或缩写 `vala` 来执行以下命令。
+
+```bash
+valaxy [args]
+
+Commands:
+  valaxy [root]        Start a local server for Valaxy                 [default]
+  valaxy build [root]  build your blog to static content
+  valaxy rss [root]    generate rss feed
+  valaxy new <title>   Draft a new post
+
+Positionals:
+  root  root folder of your source files                 [string] [default: "."]
+
+Options:
+  -p, --port     port                                                   [number]
+  -o, --open     open in browser                      [boolean] [default: false]
+      --remote   listen public host and enable remote control
+                                                       [boolean] [default: true]
+      --log      log level
+         [string] [choices: "error", "warn", "info", "silent"] [default: "warn"]
+  -h, --help     Show help                                             [boolean]
+  -v, --version  Show version number                                   [boolean]
+```
+
+## 使用
+
+### 局部使用
+
+你可以在项目的 `package.json` 中配置快捷脚本。（**推荐**）
+
+```json
+{
+  "scripts": {
+    "build": "npm run build:ssg && npm run rss",
+    "build:spa": "valaxy build",
+    "build:ssg": "valaxy build --ssg",
+    "dev": "valaxy .",
+    "rss": "valaxy rss"
+  }
+}
+```
+
+譬如通过 `npm run dev` 启动项目，通过 `npm run build` 可以在构建生成 ssg 站点后，再构建 RSS 源。
+
+### 全局安装
+
+你也可以全局安装 valaxy 以在全局使用 `valaxy` 命令。（**非必须**）
+
+```bash
+pnpm add -g valaxy
+```
+
+## 常用命令
+
+- `valaxy .`: 启动 Valaxy，默认目录为当前目录（`.` 可不写）
+- `valaxy rss`: 自动生成 RSS
+- `valaxy build`: 默认采用 Vite 构建 SPA 应用
+- `valaxy build --ssg`: 使用 vite-ssg 构建静态页面站点（SEO 友好，推荐）
+
+## 文章
+
+- `valaxy new <title>`: 在 `pages/posts` 目录下新建标题为 `title` 的帖子（.md）
+
+譬如，`valaxy new your-first-post`，将会在 `pages/posts` 下自动新建 `your-first-post.md` 文件，并附带日期。
+
+> 你觉得还可以有其他更常用、更好用的命令？没问题，尽管来 [Issues](https://github.com/YunYouJun/valaxy/issues) 反馈吧！

docs/pages/guide/custom/extend.md

@@ -2,7 +2,7 @@
 title: Extend
 title_zh: 自定义扩展
 categories:
-  - Guide
+  - Custom
 end: false
 ---
 

docs/pages/guide/deploy.md

@@ -2,8 +2,9 @@
 title: Deploy
 title_zh: 部署
 categories:
-  - Guide
+  - Getting Started
 end: false
+top: 99
 ---
 
 Valaxy 的部署非常简单，我们推荐你直接通过第三方的 CI 构建并托管到任意平台。

docs/pages/guide/features.md

@@ -2,7 +2,7 @@
 title: Features
 title_zh: 亮点
 categories:
-  - Guide
+  - Getting Started
 end: false
 top: 98
 ---

docs/pages/guide/getting-started.md

@@ -2,9 +2,9 @@
 title: Getting Started
 title_zh: 开始
 categories:
-  - Guide
+  - Getting Started
 end: true
-top: 99
+top: 100
 ---
 
 ## Overview {lang="en"}
@@ -133,7 +133,7 @@ npm run dev
 See `http://localhost:4859/`, have fun!
 :::
 
-- Valaxy 博客通用的配置可参见 [配置](/guide/config) 与 [自定义扩展](/guide/extend)。
+- Valaxy 博客通用的配置可参见 [配置](/guide/config) 与 [自定义扩展](/guide/custom/extend)。
 - Valaxy 主题独有配置请参见对应主题文档。（Valaxy Theme Yun 主题文档编写中……）
 
 ### Config {lang="en"}

docs/pages/guide/third-party/index.md

@@ -1,10 +1,10 @@
 ---
 title: Third Party
-title_zh: 第三方
+title_zh: 第三方集成
 categories:
-  - Guide
+  - Third
 end: false
-aplayer: true
+top: 99
 ---
 
 ## 音乐播放器
@@ -42,3 +42,4 @@ aplayer: true
 </meting-js>
 
 > More info see [Option | MetingJS](https://github.com/metowolf/MetingJS#option)
+

docs/pages/guide/why.md

@@ -5,7 +5,7 @@ title_zh: 为什么选 Valaxy
 date: 2022-03-22
 updated: 2022-03-23
 categories:
-  - Guide
+  - Getting Started
 tags:
   - valaxy
   - 笔记

docs/valaxy.config.ts

@@ -1,4 +1,5 @@
-import { defineConfig } from 'valaxy'
+import { defineValaxyConfig } from 'valaxy'
+import type { PressTheme } from 'valaxy-theme-press'
 
 const commitRef = process.env.COMMIT_REF?.slice(0, 8) || 'dev'
 
@@ -6,13 +7,14 @@ const safelist = [
   'i-ri-home-line',
 ]
 
-export default defineConfig({
+export default defineValaxyConfig<PressTheme.Config>({
   title: 'Valaxy',
   url: 'https://valaxy.site',
   description: 'Valaxy Site Docs',
 
   theme: 'press',
   themeConfig: {
+    sidebar: ['Getting Started', 'Guide', 'built-ins', 'Third', 'Custom', 'Theme', 'Addon', 'Dev'],
     nav: [
       {
         text: 'FAQ',

packages/valaxy-theme-press/components/PressCategories.vue

@@ -1,6 +1,7 @@
 <script lang="ts" setup>
+import { useThemeConfig } from 'valaxy'
 import type { Categories } from 'valaxy'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 
 const props = withDefaults(defineProps<{
   categories: Categories
@@ -16,15 +17,31 @@ const props = withDefaults(defineProps<{
 })
 
 const collapsable = ref(props.collapsable)
+
+const themeConfig = useThemeConfig()
+const sidebar = computed(() => themeConfig.value.sidebar)
 </script>
 
 <template>
-  <ul v-for="category, key in Object.fromEntries(categories)" :key="key" class="category-list" m="l-4">
-    <PressCategory :name="key.toString()" :category="category" :level="level + 1" :display-category="displayCategory" :collapsable="collapsable" />
+  <ul v-for="item in sidebar" :key="item" class="category-list" m="l-4">
+    <PressCategory
+      v-if="categories.get(item)"
+      :name="item" :category="categories.get(item)"
+      :level="level + 1"
+      :display-category="displayCategory"
+      :collapsable="collapsable"
+    />
   </ul>
 </template>
 
 <style lang="scss">
+.category-list {
+  &:first-child {
+    .category-list-item {
+      border-top: 0px;
+    }
+  }
+}
 .post-list-item {
   a {
     color: var(--va-c-text-light);

packages/valaxy-theme-press/components/PressCategory.vue

@@ -29,18 +29,25 @@ const getTitle = (post: Post | any) => {
 </script>
 
 <template>
-  <li v-if="category.total" class="category-list-item inline-flex items-center">
-    <span class="folder-action inline-flex cursor-pointer" @click="collapsable = !collapsable">
+  <li
+    v-if="category.total"
+    p="t-2"
+    w="full" border="t t-$pr-c-divider-light"
+    class="category-list-item inline-flex items-center justify-between"
+  >
+    <span class="category-name" font="bold" m="l-1" @click="displayCategory ? displayCategory(name) : null">
+      {{ name === 'Uncategorized' ? t('category.uncategorized') : name }}
+      <!-- <sup font="normal">[{{ category.total }}]</sup> -->
+    </span>
+    <span class="folder-action inline-flex cursor-pointer" opacity="50" @click="collapsable = !collapsable">
       <div v-if="collapsable" i-ri-folder-add-line />
-      <div v-else style="color:var(--va-c-primary)" i-ri-folder-reduce-line /></span>
-    <span class="category-name" m="l-1" @click="displayCategory ? displayCategory(name) : null">
-      {{ name === 'Uncategorized' ? t('category.uncategorized') : name }} [{{ category.total }}]
+      <div v-else i-ri-folder-reduce-line />
     </span>
   </li>
 
   <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">
+      <li v-for="post, i in category.posts" :key="i" class="post-list-item">
         <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>

packages/valaxy-theme-press/components/PressSidebar.vue

@@ -47,7 +47,7 @@ const { hasSidebar } = useSidebar()
   top: 0;
   bottom: 0;
   left: 0;
-  padding: 1.5rem 1rem;
+  padding: 1rem;
   top: var(--pr-nav-height);
   z-index: var(--pr-z-index-sidebar);
   width: calc(100vw - 64px);
@@ -70,7 +70,6 @@ const { hasSidebar } = useSidebar()
 @include media('md') {
   .press-sidebar {
     z-index: 1;
-    padding: 1.5rem 1rem;
     width: var(--va-sidebar-width);
     max-width: 100%;
     background-color: var(--va-c-bg-alt);

packages/valaxy-theme-press/config/index.ts

@@ -12,6 +12,8 @@ export const defaultThemeConfig: ThemeConfig = {
     primary: '#0078E7',
   },
 
-  sidebar: ['Guide', 'Dev', 'Theme', 'Addon'],
+  sidebar: [],
   nav: [],
+
+  footer: {},
 }

packages/valaxy-theme-press/types/index.d.ts

@@ -2,7 +2,6 @@ export * from '../composables'
 export * from './home.d'
 
 export namespace PressTheme {
-  export type Config = ThemeConfig
   export type Sidebar = any
 
   export interface Footer {

packages/valaxy-theme-yun/layouts/post.vue

@@ -21,7 +21,7 @@ const showSponsor = computed(() => {
     </template>
 
     <template #main-content-after>
-      <YunSponsor v-if="showSponsor" />
+      <YunSponsor v-if="showSponsor" m="t-6" />
       <ValaxyCopyright v-if="frontmatter.copyright || config.license.enabled" :url="url" m="y-4" />
     </template>
 

packages/valaxy/node/cli/new.ts

@@ -26,6 +26,7 @@ export const newPost = (cli: Argv<{}>) => {
         .option('date', {
           alias: 'd',
           type: 'boolean',
+          default: true,
           describe: 'Generate post with the current date',
         })
         .strict()