docs: Update documents

Marinerer · Dec 14, 2023 · f2a97a8 · f2a97a8
1 parent dc12d98
commit f2a97a8
Show file tree

Hide file tree

Showing 19 changed files with 401 additions and 263 deletions.
diff --git a/docs/.note/.note.md b/docs/.note/.note.md
diff --git a/docs/.note/index.md b/docs/.note/index.md
diff --git a/docs/.note/信息.md b/docs/.note/信息.md
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
@@ -1,9 +1,14 @@
 import { defineConfig } from 'vitepress'
 
+import { version } from '../../packages/main/package.json'
+const ogTitle = 'pipflow'
+const ogDescription = 'A web developer workflow based on Gulp. 基于gulp工作流的前端构建工具. 开箱即用,无需配置即可启动web项目的开发.'
+const ogUrl = 'https://pipflow.mengqing.org'
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "pipflow",
-  description: "A web developer workflow based on Gulp. It has built-in merging, compilation, and compression features that greatly simplify front-end development.",
+  title: ogTitle,
+  description: ogDescription,
   lang: 'zh-CN',
 
   locales: {
@@ -14,14 +19,26 @@ export default defineConfig({
   lastUpdated: true,
 
   sitemap: {
-    hostname: 'https://pipflow.mengqing.org'
+    hostname: ogUrl
   },
 
+  /* prettier-ignore */
+  head: [
+    // ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+    // ['link', { rel: 'icon', type: 'image/png', href: '/favicon.png' }],
+    ['meta', { name: 'theme-color', content: '#ea4a4a' }],
+    ['meta', { name: 'og:type', content: 'website' }],
+    ['meta', { name: 'og:locale', content: 'zh-CN' }],
+    ['meta', { name: 'og:site_name', content: ogTitle }],
+    // ['meta', { name: 'og:image', content: 'https://vitepress.dev/vitepress-og.jpg' }],
+    ['meta', { name: 'og:url', content: ogUrl }],
+  ],
+
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
 
     editLink: {
-      pattern: 'https://github.com/meqn/pipflow-cli/edit/main/docs/:path',
+      pattern: 'https://github.com/meqn/pipflow/edit/main/docs/:path',
       text: '为此页提供修改建议'
     },
 
@@ -39,8 +56,15 @@ export default defineConfig({
     },
 
     nav: [
-      { text: '指南', link: '/guide/' },
-      { text: '配置', link: '/config/' }
+      { text: '指南', link: '/guide/', activeMatch: '/guide/' },
+      { text: '配置', link: '/config/', activeMatch: '/config/' },
+      { text: '常见问题', link: '/help', activeMatch: '/help' },
+      {
+        text: `v${version}`,
+        items: [
+          { text: 'Changelog', link: 'https://github.com/Meqn/pipflow/releases' },
+        ]
+      }
     ],
 
     sidebar: {
@@ -63,6 +87,7 @@ export default defineConfig({
             { text: 'Javascript', link: '/guide/task-script' },
             { text: 'CSS', link: '/guide/task-style' },
             { text: '静态资源', link: '/guide/task-assets' },
+            { text: 'server服务', link: '/guide/task-server' },
             { text: '自定义任务和流程', link: '/guide/task-user' },
             { text: '其他', link: '/guide/task-more' }
           ]
@@ -73,7 +98,7 @@ export default defineConfig({
         },
         {
           text: '常见问题',
-          link: '/guide/help',
+          link: '/help',
         }
       ],
       '/config/': [

diff --git a/docs/config/build-options.md b/docs/config/build-options.md
@@ -78,6 +78,6 @@ CSS压缩是基于 `cssnano` 插件, 详细配置请参见 [这里](https://cssn
 
 图片压缩是基于 `gulp-imagemin` 插件, 详细配置请参见 [这里](https://www.npmjs.com/package/gulp-imagemin)。
 
-::: danger 🚨 提醒
+::: warning 🚨 提醒
 由于安装 `gulp-imagemin` 依赖经常失败(国内环境)，且图片压缩是一项耗时的一次性任务。所以 `pipflow` 将 `gulp-imagemin` 的安装提取到项目的依赖中。如果你的项目不需要 压缩图片或者手动一次性压缩，请删除项目的 `package.json` 中的 `gulp-imagemin` 依赖，并将 `imageMinify` 配置项的值设置为 `false`。
 :::
diff --git a/docs/config/task-options.md b/docs/config/task-options.md
@@ -111,9 +111,9 @@ interface CompilerOptions {
 ```
 
 每个预处理器支持的选项可以在它们各自的文档中找到：
-- `sass/scss` : [选项]()
-- `less` : [选项]()
-- `stylus` : [选项]()
+- `sass/scss` : [配置说明](https://www.npmjs.com/package/gulp-sass)
+- `less` : [配置说明](https://www.npmjs.com/package/gulp-less)
+- `stylus` : [配置说明](https://www.npmjs.com/package/gulp-stylus)
 
 
 示例：
@@ -184,8 +184,9 @@ module.exports = {
 
 在 `serve` 阶段是否监视文件变动并重新编译、刷新页面。
 
+支持 `'html', 'style', 'script', 'static', 'image', 'copy', 'user'` 类型任务。
 
-
+<!-- 
 ## filename {#filename}
 - **类型：** `string`
 - **默认：** `archive`
@@ -195,3 +196,4 @@ module.exports = {
 ::: tip 温馨提示
 如果需要创建压缩包，可以使用 `pipflow pack` 命令快速生成压缩包。 请参见 [[这里](../guide/cli#pipflow-pack)]。
 :::
+ -->
diff --git a/docs/guide/cli.md b/docs/guide/cli.md
@@ -202,8 +202,9 @@ Options:
 
 ### `pipflow server` {#cli-server}
 
-启动一个本地HTTP服务器。它是基于 BrowserSync 的。  
-你可以在任何目录下运行该命令，无需其他配置。
+快速启动一个本地HTTP服务器，用于预览或演示单个 HTML 页面。它是基于 `BrowserSync` 实现的。
+
+无需配置，可在任意目录启动服务器，同时也支持参数自定义，如端口、目录、是否监听文件变化、浏览器自动刷新等。
 
 #### 使用
 ```bash

diff --git a/docs/guide/help.md b/docs/guide/help.md
diff --git a/docs/guide/task-assets.md b/docs/guide/task-assets.md
@@ -1,41 +1,43 @@
-# 静态资源
+# 静态资源任务 {#assets-task}
 
-## 静态文件任务
+任务类型为 `static` 或 `image` 。
 
+静态资源包含常见的图像、媒体和字体文件等。如果不想处理这些静态资源文件，你可以将它们放在 `public` 目录下。
 
-## 图片任务
 
-### 图片压缩
 
-由于图片压缩是一个耗时任务，且 `gulp-imagemin` 插件**安装依赖经常失败**(国内环境)。鉴于此会影响整个工程的安装运行，所以 `pipflow` 并未内置图片压缩功能，如果需要则手动安装依赖并引入插件即可。
+## 任务流程 {#process-flow}
 
-**具体步骤如下:**
+- 自定义处理流程 - 处理 `pipflow.config.js` 中添加的自定义 `plugins`
+- 压缩图片 - 基于 `imagemin` 压缩图片
+- 生成文件hash及manifest文件
 
-1. 安装 `gulp-imagemin` 依赖
-```shell
-npm install -D gulp-imagemin@7
-```
 
-::: warning 注意
-`gulp-imagemin` 只能安装 `<=7` 的版本，`8`及以上版本仅支持 `esModule` 模块化.
-:::
 
+## 图片压缩
 
-2. 在 `pipflow.config.js` 中找到当前任务，并加入以下代码
+由于图片压缩是一项耗时的一次性任务，且 `gulp-imagemin` 插件**安装依赖经常失败**(国内环境)。所以 `pipflow` 将 压缩图片作为一个可选项。如果你的项目不需要 压缩图片或者手动一次性压缩，请删除项目的 `package.json` 中的 `gulp-imagemin` 依赖，并将 `imageMinify` 配置项的值设置为 `false`。
 
-```js
-const imagemin = require('gulp-imagemin')
+关于图片压缩配置，你可以为所有静态任务统一配置，也可以单独配置某个静态任务。
 
-module.exports = {
-  tasks: [
-    {
-      type: 'assets',
-      plugins: [
-        imagemin(/* options */)
-      ]
-    }
-  ]
+1. 统一配置项 `build.imageMinify` , 具体请看 [这里](../config/build-options.md#build-imageminify)。
+2. 单独任务配置项 `minify`。
+
+```ts
+ImageMinifyOptions : boolean | {
+  plugins?: ImageMinifyPlugin[]
+  options?: {
+    verbose?: boolean
+    silent?: boolean
+  }
 }
 ```
 
-> `gulp-imagemin` 插件在压缩图片过程中会自动过滤非图片文件。 请[点击查看文档](https://www.npmjs.com/package/gulp-imagemin)
+
+
+> `gulp-imagemin` 插件在压缩图片过程中会自动过滤非图片文件。 具体配置请点击 [这里](https://www.npmjs.com/package/gulp-imagemin)
+
+::: warning 🚨 提醒
+`gulp-imagemin` 只能安装 `<=7` 的版本，`8`及以上版本仅支持 `esModule` 模块化.
+:::
+
diff --git a/docs/guide/task-html.md b/docs/guide/task-html.md
@@ -1,6 +1,9 @@
 # HTML 任务
 
-## 处理流程 {#process-flow}
+任务类型为 `html` 。
+
+
+## 任务流程 {#process-flow}
 
 - 环境变量处理 - 环境变量在构建时会被静态替换
 - 模板渲染 - 渲染HTML模板引擎，支持 `Pug`, `EJS`, `Handlebars`, `Nunjucks`, `art-template`