feat: 🎸 Improve documentation

huyikai · Dec 14, 2023 · 1f909ec · 1f909ec
1 parent c0da6dc
commit 1f909ec
Show file tree

Hide file tree

Showing 36 changed files with 94 additions and 78 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -25,7 +25,14 @@ export default async () => {
         ...instance.nav,
         {
           text: 'Example',
-          link: 'https://huyikai.xyz'
+          items: [
+            { text: 'MySite', link: 'https://huyikai.xyz' },
+            {
+              text: 'Tree-Conver',
+              link: 'https://huyikai.github.io/tree-conver/'
+            },
+            { text: 'LocalCMS', link: 'https://huyikai.github.io/local-cms/' }
+          ]
         }
       ],
       // 侧边栏

diff --git a/docs/.vitepress/theme/home.vue b/docs/.vitepress/theme/home.vue
@@ -17,8 +17,8 @@ import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vu
         tag="a"
         size="medium"
         theme="brand"
-        text="Docs"
-        href="/contents/Guide/1.Introduction/Started.html"
+        text="Guide"
+        href="/Guide/Basic/Introduction.html"
       >
       </VPButton>
       <VPButton

diff --git a/docs/Guide/Basic/Features/CMS.md b/docs/Guide/Basic/Features/CMS.md
@@ -0,0 +1,25 @@
+# CMS
+
+## 提升
+
+- 脚本直接运行管理工具 `npm run cms`。
+- 增删改查支持
+- 实时预览保存，所见即所得。
+
+## 关于 CMS 的一些想法
+
+VitePress-Helper 中的 CMS 实际上是一个独立开发的库，让 VitePress 更加灵活的同时，也为了方便其他情况下使用，故将 CMS 独立出来。
+
+在使用过程中发现，仍然存在一些维护成本，比如需要在开发工具中管理内容及目录，在 markdown 编辑器中编辑内容。因此想进一步简化这个过程的操作，更加专注于内容的创作和管理。
+
+常见的静态站点生成器使用方式是编辑内容然后将代码推送到代码仓库，通过代码仓库的 Pages 和工作流自动生成站点访问。或者也可以在服务器上直接放置构建后的代码文件或者通过容器部署。
+
+CMS 系统有很多已经成熟的项目，之所以选择开发一个 LocalCMS ，而不是使用现有 CMS 系统的原因如下。
+
+目前了解的大多数 CMS 系统需要服务器和数据库来搭配对内容管理和存储。
+这种使用方式比较成熟，但对于当前的使用场景来说，体量过重了，增加额外的开发成本、使用成本。和 VitePress 的使用体验也有所割裂，通过 CMS 提供的接口获取内容对 SEO 也不够友好。
+最主要的它们往往还需要额外付费订阅才能使用。
+
+还有一种基于 Git 的 CMS 管理系统，相比较更适合，但也存在使用成本和体验的问题。当然这并不是这些 CMS 系统的问题，只是使用场景没有契合。
+
+所以我认为在使用 VitePress 的场景下需要的是一个使用简单，没有太多概念和配置，甚至用起来像一个 markdown 编辑器的本地 CMS。
diff --git a/docs/Guide/Basic/Features/Home.md b/docs/Guide/Basic/Features/Home.md
@@ -0,0 +1,3 @@
+# Home
+
+不少开发者喜欢更具个性化的首页。本着可以不用，但不能没有的理论，增加了 `.vitepress/theme/home.vue` 可以根据需要自定义首页的内容和样式。
diff --git a/docs/Guide/Basic/Features/Nav.md b/docs/Guide/Basic/Features/Nav.md
@@ -0,0 +1,12 @@
+# Nav
+
+## 提升
+
+- 自动生成：根据 VitePress 运行目录下的目录及内容自动生成导航栏。
+- 多级目录：VitePress 本身的导航只支持到二级目录，即使手动设置了更多的子级也不会生效。
+- 样式调整：优化了多层级、链接与类目等多种情况下的样式处理。像侧边栏的样式靠拢。
+
+## 问题
+
+- 多语言情况未兼容
+- 内容排序目前只能按照名称排序，无法灵活定义。可以通过在文件前面增加数字序号来解决。也考虑过在 FrontMatter 中增加 order，还有待考量。
diff --git a/docs/Guide/Basic/Features/Sidebar.md b/docs/Guide/Basic/Features/Sidebar.md
@@ -0,0 +1,10 @@
+# Sidebar
+
+## 提升
+
+- 自动生成：根据 VitePress 运行目录下的目录及内容自动生成侧边栏。
+
+## 问题
+
+- 多语言情况未兼容
+- 内容排序目前只能按照名称排序，无法灵活定义。可以通过在文件前面增加数字序号来解决。也考虑过在 FrontMatter 中增加 order，还有待考量。
diff --git a/docs/Guide/Basic/Introduction.md b/docs/Guide/Basic/Introduction.md
@@ -0,0 +1,13 @@
+# 欢迎使用 VitePress-Helper
+
+## 为什么要做这个工具
+
+VitePress 是一个很好用的构建静态文档工具。使用了一段时间后，感觉它并不完美。
+
+VitePress 本身的 `导航栏` 和 `侧边栏` 配置比较繁琐，而且配置文件和源码文件是分离的，需要手动同步。在管理的内容数量比较少的情况下，还问题不大，一旦内容数量比较多的话，会增加很多维护成本。
+
+另一方面，作为 VitePress 使用者，可能会有不止一个 VitePress 项目，如果每个项目都配置一遍，也是比较麻烦的。
+
+在发现问题后，检索了关于 VitePress 的插件，可以看出有不少人有相同的感受。
+尝试了部分插件，并没有很好的解决问题或者说大家关注的细节有所出入。
+所以最终决定写一个工具，让自己使用起来更加便利，同时也希望能够帮助大家更轻松地使用 VitePress。
diff --git a/docs/contents/Guide/1.Introduction/Started.md b/docs/contents/Guide/1.Introduction/Started.md
diff --git a/docs/contents/Guide/2.Features/Nav.md b/docs/contents/Guide/2.Features/Nav.md
diff --git a/docs/contents/Guide/2.Features/Sidebar.md b/docs/contents/Guide/2.Features/Sidebar.md
diff --git a/docs/contents/Guide/test.md b/docs/contents/Guide/test.md
diff --git a/docs/contents/test.md b/docs/contents/test.md
diff --git a/docs/contents2/Guide2/1.Introduction2/Started.md b/docs/contents2/Guide2/1.Introduction2/Started.md
diff --git a/docs/contents2/Guide2/1.Introduction2/test123/test123.md b/docs/contents2/Guide2/1.Introduction2/test123/test123.md
diff --git a/docs/contents2/Guide2/2.Features/Nav.md b/docs/contents2/Guide2/2.Features/Nav.md
diff --git a/docs/contents2/Guide2/2.Features/Sidebar.md b/docs/contents2/Guide2/2.Features/Sidebar.md
diff --git a/docs/contents2/Guide2/test.md b/docs/contents2/Guide2/test.md
diff --git a/docs/index.md b/docs/index.md
@@ -9,7 +9,10 @@ lastUpdated: false
 
 ## Usage
 
-Currently, two usage methods are planned: 1. Using the scaffolding initialization (recommended), you can get started directly. 2. Add the dependency `@huyikai/vitepress-Helper` to an existing vitepress project and manually modify the config and theme.
+Currently, two usage methods are planned:
+
+1. Using the scaffolding initialization (recommended), you can get started directly.
+2. Add the dependency `@huyikai/vitepress-Helper` to an existing vitepress project and manually modify the config and theme.
 
 ### Cli Init
 

diff --git a/packages/@huyikai/vitepress-helper/package.json b/packages/@huyikai/vitepress-helper/package.json
@@ -2,7 +2,7 @@
   "name": "@huyikai/vitepress-helper",
   "version": "0.0.7",
   "private": false,
-  "description": "enhance vitepress experience",
+  "description": "This tool is designed to help you to use VitePress more easily.",
   "keywords": [
     "vite",
     "vitepress",

diff --git a/packages/@huyikai/vitepress-helper/template/docs/.vitepress/config.ts b/packages/@huyikai/vitepress-helper/template/docs/.vitepress/config.ts
@@ -22,10 +22,17 @@ export default async () => {
       // 导航栏
       nav: [
         ...instance.nav,
+        // 可以自定义添加导航栏的额外内容
         {
-          // 可以自定义添加导航栏的额外内容
           text: 'Example',
-          link: 'https://huyikai.xyz'
+          items: [
+            { text: 'MySite', link: 'https://huyikai.xyz' },
+            {
+              text: 'Tree-Conver',
+              link: 'https://huyikai.github.io/tree-conver/'
+            },
+            { text: 'LocalCMS', link: 'https://huyikai.github.io/local-cms/' }
+          ]
         }
       ],
       // 侧边栏

diff --git a/packages/@huyikai/vitepress-helper/template/docs/.vitepress/theme/home.vue b/packages/@huyikai/vitepress-helper/template/docs/.vitepress/theme/home.vue
@@ -18,7 +18,7 @@ import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vu
         size="medium"
         theme="brand"
         text="Docs"
-        href="/contents/Guide/1.Introduction/Started.html"
+        href="/Introduction.html"
       >
       </VPButton>
       <VPButton
@@ -34,7 +34,7 @@ import VPButton from 'vitepress/dist/client/theme-default/components/VPButton.vu
         size="medium"
         theme="alt"
         text="Github"
-        href="https://github.com/vitepress-custom"
+        href="https://github.com/huyikai/vitepress-helper"
       >
       </VPButton>
     </div>

diff --git a/packages/@huyikai/vitepress-helper/template/docs/Introduction.md b/packages/@huyikai/vitepress-helper/template/docs/Introduction.md
@@ -0,0 +1,5 @@
+# VitePress-Helper
+
+## Brief
+
+On the basis of [vitepress](https://vitepress.vuejs.org), optimize the user experience.
diff --git a/docs/contents2/class1/class1-a.md → .../template/docs/content/class1/class1-a.md b/docs/contents2/class1/class1-a.md → .../template/docs/content/class1/class1-a.md
diff --git a/docs/contents2/class1/class1-b.md → .../template/docs/content/class1/class1-b.md b/docs/contents2/class1/class1-b.md → .../template/docs/content/class1/class1-b.md
diff --git a/docs/contents2/class1/class2-1/class2-1-a.md → ...ocs/content/class1/class2-1/class2-1-a.md b/docs/contents2/class1/class2-1/class2-1-a.md → ...ocs/content/class1/class2-1/class2-1-a.md
diff --git a/docs/contents2/class1/class2-2/class2-2-a.md → ...ocs/content/class1/class2-2/class2-2-a.md b/docs/contents2/class1/class2-2/class2-2-a.md → ...ocs/content/class1/class2-2/class2-2-a.md
diff --git a/docs/contents2/class1/class2-2/class2-2-b.md → ...ocs/content/class1/class2-2/class2-2-b.md b/docs/contents2/class1/class2-2/class2-2-b.md → ...ocs/content/class1/class2-2/class2-2-b.md
diff --git a/...tents2/class1/class2-2/class3/class3-a.md → ...ontent/class1/class2-2/class3/class3-a.md b/...tents2/class1/class2-2/class3/class3-a.md → ...ontent/class1/class2-2/class3/class3-a.md
diff --git a/...tents2/class1/class2-2/class3/class3-b.md → ...ontent/class1/class2-2/class3/class3-b.md b/...tents2/class1/class2-2/class3/class3-b.md → ...ontent/class1/class2-2/class3/class3-b.md
diff --git a/packages/@huyikai/vitepress-helper/template/docs/example/class1/class1-a.md b/packages/@huyikai/vitepress-helper/template/docs/example/class1/class1-a.md
diff --git a/packages/@huyikai/vitepress-helper/template/docs/example/class1/class1-b.md b/packages/@huyikai/vitepress-helper/template/docs/example/class1/class1-b.md
diff --git a/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-1/class2-1-a.md b/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-1/class2-1-a.md
diff --git a/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-2/class2-2-a.md b/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-2/class2-2-a.md
diff --git a/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-2/class2-2-b.md b/...s/@huyikai/vitepress-helper/template/docs/example/class1/class2-2/class2-2-b.md
diff --git a/...yikai/vitepress-helper/template/docs/example/class1/class2-2/class3/class3-a.md b/...yikai/vitepress-helper/template/docs/example/class1/class2-2/class3/class3-a.md
diff --git a/...yikai/vitepress-helper/template/docs/example/class1/class2-2/class3/class3-b.md b/...yikai/vitepress-helper/template/docs/example/class1/class2-2/class3/class3-b.md