From 6ea670c16a2c03b133dc027c2ecead20ed6ccc52 Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Thu, 31 Oct 2024 12:09:38 +0800 Subject: [PATCH] docs: improve docs --- docs/.vuepress/notes/zh/index.ts | 4 +- docs/notes/plugins/README.md | 17 - docs/notes/plugins/caniuse.md | 118 ------- docs/notes/plugins/content-updated.md | 98 ------ docs/notes/plugins/iconify.md | 103 ------ docs/notes/plugins/md-power.md | 327 ------------------ .../notes/plugins/netlify-functions/README.md | 41 --- docs/notes/plugins/netlify-functions/api.md | 82 ----- .../plugins/netlify-functions/functions.md | 99 ------ docs/notes/plugins/netlify-functions/介绍.md | 61 ---- docs/notes/plugins/netlify-functions/使用.md | 165 --------- docs/notes/plugins/netlify-functions/功能.md | 20 -- docs/notes/plugins/shiki.md | 114 ------ 13 files changed, 2 insertions(+), 1247 deletions(-) delete mode 100644 docs/notes/plugins/README.md delete mode 100644 docs/notes/plugins/caniuse.md delete mode 100644 docs/notes/plugins/content-updated.md delete mode 100644 docs/notes/plugins/iconify.md delete mode 100644 docs/notes/plugins/md-power.md delete mode 100644 docs/notes/plugins/netlify-functions/README.md delete mode 100644 docs/notes/plugins/netlify-functions/api.md delete mode 100644 docs/notes/plugins/netlify-functions/functions.md delete mode 100644 docs/notes/plugins/netlify-functions/介绍.md delete mode 100644 docs/notes/plugins/netlify-functions/使用.md delete mode 100644 docs/notes/plugins/netlify-functions/功能.md delete mode 100644 docs/notes/plugins/shiki.md diff --git a/docs/.vuepress/notes/zh/index.ts b/docs/.vuepress/notes/zh/index.ts index c2116c11..62247b24 100644 --- a/docs/.vuepress/notes/zh/index.ts +++ b/docs/.vuepress/notes/zh/index.ts @@ -1,5 +1,5 @@ import { defineNotesConfig } from 'vuepress-theme-plume' -import { plugins } from './plugins' +// import { plugins } from './plugins' import { themeConfig } from './theme-config' import { themeGuide } from './theme-guide' import { tools } from './tools' @@ -10,7 +10,7 @@ export const zhNotes = defineNotesConfig({ notes: [ themeGuide, themeConfig, - plugins, + // plugins, tools, ], }) diff --git a/docs/notes/plugins/README.md b/docs/notes/plugins/README.md deleted file mode 100644 index 5dc3ee07..00000000 --- a/docs/notes/plugins/README.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 插件 -author: pengzhanbo -createTime: 2024/03/11 17:34:29 -permalink: /plugins/ ---- - -## 概述 - -主题通过插件来实现各种功能，除了一些对主题有强依赖的插件外，主题还开发了一些通用的插件。 - -## 插件 - -- [@vuepress-plume/plugin-shikiji](/plugins/plugin-shikiji/) -- [@vuepress-plume/plugin-content-update](/plugins/plugin-content-update/) -- [vuepress-plugin-netlify-functions](/plugins/plugin-netlify-functions/) -- [vuepress-plugin-md-power](/plugins/plugin-md-power/) diff --git a/docs/notes/plugins/caniuse.md b/docs/notes/plugins/caniuse.md deleted file mode 100644 index 6be59f49..00000000 --- a/docs/notes/plugins/caniuse.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: plugin-caniuse -author: pengzhanbo -createTime: 2024/03/11 17:22:52 -permalink: /plugins/plugin-caniuse/ ---- - -:::warning Deprecated -该插件功能已整合到 [vuepress-plugin-md-power](/plugins/plugin-md-power) 。 -因此，此插件不再更新维护，并标记为 弃用。 -::: - -## 指南 - -为你的 vuepress 站点，在编写文章时， 提供嵌入 [can-i-use](https://caniuse.com/) WEB feature 各平台支持说明 的功能。 - -方便在描述某个 WEB feature 时，能更直观的表述 该特性的支持程度。 - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install @vuepress-plume/plugin-caniuse -``` - -@tab:active yarn - -``` sh -yarn add @vuepress-plume/plugin-caniuse -``` - -@tab pnpm - -``` sh -pnpm add @vuepress-plume/plugin-caniuse -``` - -::: - -## 使用 - -### Step1：添加插件 - -将插件添加到你的 vuepress 项目的配置文件中： - -::: code-tabs -@tab .vuepress/config.ts - -``` ts -import { caniusePlugin } from '@vuepress-plume/plugin-caniuse' -import { defineUserConfig } from 'vuepress' - -export default defineUserConfig({ - plugins: [ - caniusePlugin() - ] -}) -``` - -::: - -### Step2：在markdown中使用 - -在你的 文章 markdown文件中，使用以下格式： - -``` md -::: caniuse {browser_versions} -::: -``` - -__示例： 获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况图标：__ - -``` md -::: caniuse css-matches-pseudo -::: -``` - -效果： - -::: caniuse css-matches-pseudo -::: - -## Method - -`caniusePlugin([options])` - -插件注册函数 - -__options:__ `[CanIUsePluginOptions]` - -- `options.mode`: 配置 can-i-use 在 文章中的 嵌入模式, 默认： `image` - - `image`： 嵌入 特性图表图片 - - `embed`: 嵌入 iframe， 实时的，可交互的模式 - -## Markdown 语法 - -``` md -::: caniuse {browser_versions} -::: -``` - -### `` - -必填。 正确取值请参考 [https://caniuse.bitsofco.de/](https://caniuse.bitsofco.de/) - -### `{browser_versions}` - -可选。当前特性在多个版本中的支持情况。 - -默认值为: `{-2,-1,1}` - -格式： `{number,number,...}` 取值范围为 `-5 ~ 3` - -- 小于`0` 表示低于当前浏览器版本的支持情况 -- `0` 表示当前浏览器版本的支持情况 -- 大于`0` 表示高于当前浏览器版本的支持情况 diff --git a/docs/notes/plugins/content-updated.md b/docs/notes/plugins/content-updated.md deleted file mode 100644 index 1ae07e30..00000000 --- a/docs/notes/plugins/content-updated.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: plugin-content-update -author: pengzhanbo -createTime: 2024/03/12 19:53:34 -permalink: /plugins/plugin-content-update/ -tags: - - 插件 - - 内容更新 ---- - -## 指南 - -用于解决在 开发运行时， Markdown 内容更新时， 部分依赖解析后的 HTML 内容提供功能的插件， -未对新增的 Markdown 内容提供支持。 - -如， `plugin-medium-zoom` 需要在 页面渲染完成后，获取当前页面的图片实现 图片放大功能。 -但是在 开发运行时，在 markdown 插入新图片后，如果页面未刷新，新增的图片无法实现放大功能。 - -本插件对 `vuepress` 内置插件 `` 进行重写替换，并提供了 `onContentUpdated(callback)` -方法，用于在 Markdown 内容更新时，执行回调函数。 - -::: warning 警告 -本插件为 试验性插件，未来会随着 VuePress 的更新进行升级。 - -本插件主要面向 主题开发者 或 插件开发者。 -::: - -## 安装 - -::: code-tabs -@tabs npm - -```sh -npm install @vuepress-plume/plugin-content-update -``` - -@tab pnpm - -```sh -pnpm add @vuepress-plume/plugin-content-update -``` - -@tab yarn - -```sh -yarn add @vuepress-plume/plugin-content-update -``` - -::: - -## 使用 - -在 vuepress 配置文件中引入插件： - -::: code-tabs -@tab .vuepress/config.ts - -``` ts -import { contentUpdatePlugin } from '@vuepress-plume/plugin-content-update' -import { defineUserConfig } from 'vuepress' - -export default defineUserConfig({ - plugins: [ - contentUpdatePlugin() - ] -}) -``` - -::: - -在 客户端文件中使用： - -``` vue - -``` - -## 示例 - -获取 `medium-zoom` 实例， 当 markdown 内容更新时， 刷新 `medium-zoom` 实例，使新增的图片可放大 - -```vue - -``` diff --git a/docs/notes/plugins/iconify.md b/docs/notes/plugins/iconify.md deleted file mode 100644 index 88d5ca1c..00000000 --- a/docs/notes/plugins/iconify.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: plugin-iconify -author: pengzhanbo -createTime: 2024/03/13 17:28:25 -permalink: /plugins/plugin-iconify/ -tags: - - 插件 - - 图标 ---- - -## 指南 - -添加 `iconify` 图标库支持。并注入全局组件 `` - -支持 iconify 所有图标，支持通过 icon name 加载图标，可在[iconify search](https://icon-sets.iconify.design/) 搜索图标使用。 - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install @vuepress-plume/plugin-iconify -``` - -@tab:active yarn - -``` sh -yarn add @vuepress-plume/plugin-iconify -``` - -@tab pnpm - -``` sh -pnpm add @vuepress-plume/plugin-iconify -``` - -::: - -## 使用 - -```ts -// .vuepress/config.ts -import iconifyPlugin from '@vuepress-plume/plugin-iconify' -module.exports = { - // ... - plugins: [ - iconifyPlugin({ - componentName: 'Iconify' - }) - ] - // ... -} -``` - -### Options - -```ts -interface IconifyOptions { - /** - * 组件名， - * @default `Iconify` - */ - componentName?: string - /** - * 默认图标颜色 - * @default `currentColor` - */ - color?: string - /** - * 图标大小 - * @default '1em' - */ - size?: string | number -} -``` - -## Component - -```vue - -``` - -### Props - -```ts -interface Props { - name?: string - size?: string | number - color?: string - mode?: 'style' | 'svg' | 'mask' | 'bg' - style?: StyleValue - flip?: string - vFlip?: boolean - hFlip?: boolean - inline?: boolean - rotate?: number -} -``` - -效果： diff --git a/docs/notes/plugins/md-power.md b/docs/notes/plugins/md-power.md deleted file mode 100644 index 43e5b036..00000000 --- a/docs/notes/plugins/md-power.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -title: plugin-md-power -author: pengzhanbo -createTime: 2024/04/04 18:44:57 -permalink: /plugins/plugin-md-power/ -tags: - - 插件 - - markdown ---- - -## 指南 - -插件为 vuepress markdown 注入更多的功能支持。 - -其中，`@[xxx](xx)` 形式的语法，主要用于 资源嵌入类型的支持，包括 嵌入 PDF、视频、代码演示等。 - -同时，还提供了其它的语法支持。 - -::: important -如果您正在使用 **vuepress-theme-plume** 主题，主题已内置了 本插件，您无需安装本插件。 - -只需要在 [配置 > 内置插件 > md-power](../theme/config/plugins/markdownPower.md) 中配置本插件即可。 -::: - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install vuepress-plugin-md-power -``` - -@tab:active yarn - -``` sh -yarn add vuepress-plugin-md-power -``` - -@tab pnpm - -``` sh -pnpm add vuepress-plugin-md-power -``` - -::: - -## 使用 - -```ts -// .vuepress/config.ts -import { markdownPowerPlugin } from 'vuepress-plugin-md-power' - -export default { - // ... - plugins: [ - markdownPowerPlugin({ - pdf: true - }) - ] - // ... -} -``` - -## Options - -```ts -interface MarkdownPowerPluginOptions { - pdf?: boolean | PDFOptions - - // new syntax - icons?: boolean | IconsOptions - - // video embed - bilibili?: boolean - youtube?: boolean - - // code embed - codepen?: boolean - replit?: boolean - codeSandbox?: boolean - jsfiddle?: boolean - - caniuse?: boolean | CanIUseOptions - repl?: false | { - go?: boolean - rust?: boolean - kotlin?: boolean - theme?: string | { light: string, dark: string } - } -} -``` - -## 使用 - -### caniuse - -插件默认不启用该功能，你需要手动设置 `caniuse` 为 `true` - -#### 语法 - -```md -@[caniuse](feature) -@[caniuse image](feature) // 不再推荐使用 -@[caniuse embed{versionRange}](feature) -``` - -你可以从 [caniuse](https://caniuse.pengzhanbo.cn/) 获取 feature 的值。 - -默认情况下，插件通过 `iframe` 嵌入 `caniuse` 的支持情况查看器。 -~~你也可以使用 `@[caniuse image](feature)` 直接嵌入图片。~~ - -caniuse 默认查看最近的5个浏览器版本。你可以通过 `{versionRange}` 手动设置查看的浏览器版本。 -格式为 `{past,future}` 表示 `{过去版本,未来版本}`。取值范围为 `-5 ~ 3` 。 - -- 小于0 表示低于当前浏览器版本的支持情况 -- 0 表示当前浏览器版本的支持情况 -- 大于0 表示高于当前浏览器版本的支持情况 - -如 `{-2,2}` 表示查看低于当前 2 个版本 到 高于当前 2 个版本的支持情况。 - -### pdf - -插件默认不启用该功能，你需要手动设置 `pdf` 为 `true` - -#### 语法 - -```md -@[pdf](url) -@[pdf 1](url) -@[pdf 1 no-toolbar width="100%" height="600px" zoom="1" ratio="16:9"](url) -``` - -`url` 只支持绝对路径以及完整的资源链接地址，请勿传入相对路径。 - -你可以在 `pdf` 后紧跟空格，设置一个数字表示默认显示的 pdf 页码 - -- `no-toolbar` 表示不显示工具栏 -- `width` 设置宽度 -- `height` 设置高度 -- `zoom` 设置缩放 -- `ratio` 设置宽高比， 仅当 `width` 有值， `height` 未设置时有效 - -### icons - -插件默认不启用该功能，你需要手动设置 `icons` 为 `true`。 - -你还需要手动安装 `@iconify/json` 依赖。 - -```sh -pnpm add @iconify/json -``` - -#### 语法 - -```md -:[collect:icon]: -:[collect:icon size]: -:[collect:icon /color]: -:[collect:icon size/color]: -``` - -你可以从 [icon-sets.iconify](https://icon-sets.iconify.design/) 获取 图标集。 - -显示 `logos` 图标集合下的 `vue` 图标 - -```md -:[logos:vue]: -``` - -图标默认大小为 `1em` ，你可以通过 `size` 设置图标大小 - -```md -:[logos:vue 1.2em]: -``` - -图标默认颜色为 `currentColor` 你可以通过 `/color` 设置图标颜色 - -```md -:[logos:vue /blue]: -``` - -也可以通过 `size/color` 设置图标大小和颜色 - -```md -:[logos:vue 1.2em/blue]: -``` - -### bilibili - -插件默认不启用该功能，你需要手动设置 `bilibili` 为 `true` - -#### 语法 - -```md -@[bilibili](bvid) -@[bilibili autoplay time="0"](bvid) -@[bilibili p1 autoplay time="0" ratio="16:9"](aid cid) -``` - -- 设置 `autoplay` 以自动播放视频。 -- 设置 `time` 以指定开始播放的时间点，单位为秒。还可以传入 `mm:ss` 或者 `hh:mm:ss`。 -- 如果为 分p（非合集），还可以设置 `p\d` （第\d 个分p），此时可以只传入 `aid` 和 `cid`。 -- 设置 `ratio` 以指定视频的宽高比。 - -### youtube - -插件默认不启用该功能，你需要手动设置 `youtube` 为 `true` - -#### 语法 - -```md -@[youtube](id) -@[youtube autoplay loop ratio="16:9" star="0" end="0"](id) -``` - -- `id` 为 YouTube 视频 ID -- `autoplay` 为是否自动播放 -- `loop` 为是否循环播放 -- `ratio` 为视频的宽高比 -- `star` 为开始时间，单位为秒，还可以传入 `mm:ss` 或者 `hh:mm:ss`。 -- `end` 为结束时间，单位为秒，还可以传入 `mm:ss` 或者 `hh:mm:ss`。 - -### CodePen - -插件默认不启用该功能，你需要手动设置 `codepen` 为 `true` - -#### 语法 - -```md -@[codepen](user/slash) -@[codepen preview editable title="" height="400px" tab="css,result" theme="dark"](user/slash) -``` - -- `user` 为 CodePen 用户名 -- `slash` 为 CodePen slash -- `preview` 为是否为预览模式 -- `editable` 为是否为可编辑模式 -- `title` 为标题 -- `height` 为高度 -- `tab` 为选项卡，默认为 `result`, 多个以逗号分隔，如 `css,result` -- `theme` 为主题， 可选值包括 `dark` 和 `light` - -### Replit - -插件默认不启用该功能，你需要手动设置 `replit` 为 `true` - -#### 语法 - -```md -@[replit](user/repl-name) -@[replit title="" height="450px" theme="dark"](user/repl-name#filepath) -``` - -- `user` 为 Replit 用户名 -- `repl-name` 为 Replit Repl 名 -- `filepath` 为文件路径 -- `title` 为标题 -- `height` 为高度 -- `theme` 为主题， 可选值包括 `dark` 和 `light` - -### CodeSandbox - -插件默认不启用该功能，你需要手动设置 `codesandbox` 为 `true` - -#### 语法 - -```md -@[codesandbox](id) -@[codesandbox button](workspace/id) -@[codesanbox title="xxx" layout="Editor+Preview" height="500px" navbar="false" console](id#filepath) -``` - -- `id`: Code Sandbox ID -- `title`: Code Sandbox 标题 -- `layout`: 代码预览布局 可选值： `Preview`， `Editor`， `Editor+Preview` -- `height`: 代码预览高度 -- `navbar`: 是否显示导航栏，默认为 true -- `console`: 是否显示控制台，默认为 false -- `filepath`: 文件路径 - -### JSFiddle - -插件默认不启用该功能，你需要手动设置 `jsfiddle` 为 `true` - -#### 语法 - -```md -@[jsfiddle](user/id) -@[jsfiddle theme="dark" tab="js,css,html,result" height="500px"](user/id) -``` - -- `user`: 用户 -- `id`: jsfiddle id -- `theme`: 主题模式， 可选值： `"light" | "dark"` -- `tab`: 选项卡， 可选值：`"js" | "css" | "html" | "result"`, 多个用 `","` 分割， - 顺序将决定选项卡的排序，默认为 `js,css,html,result` -- `height`: 高度 - -### Repl - -插件默认不启用该功能，你需要手动设置 `repl` 为 `true` - -提供在 markdown 中为 `golang` 、`kotlin`、`rust` 语言的 在线代码演示 支持。 -在线编译执行代码，并输出结果。 - -#### 语法 - -````md -::: go-repl -```go -// your go lang code -``` -::: - -::: kotlin-repl -```kotlin -// your kotlin code -``` -::: - -:::rust-repl -```rust -// your rust code -``` -::: -```` diff --git a/docs/notes/plugins/netlify-functions/README.md b/docs/notes/plugins/netlify-functions/README.md deleted file mode 100644 index ce558fdb..00000000 --- a/docs/notes/plugins/netlify-functions/README.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: plugin-netlify-functions -author: pengzhanbo -createTime: 2024/03/12 13:51:09 -permalink: /plugins/plugin-netlify-functions/ -tags: - - 插件 - - netlify ---- - -如果你的 vuepress 站点是部署在 netlify 的，而且希望能够使用netlify functions 来做 serverless。 - -那么你可能需要本插件提供支持。 - -本插件仅 提供 `Netlify Functions` 开发环境和 打包构建 支持，不提供具体的 `functions` 函数。 - -- 你可以基于此插件 在你的 vuepress 项目中 自定义 `functions` -- 也可以基于此插件作为你的 vuepress plugin 依赖，开发自定义 `functions` 提供给其他 vuepress项目使用。 - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install vuepress-plugin-netlify-functions -``` - -@tab:active yarn - -``` sh -yarn add vuepress-plugin-netlify-functions -``` - -@tab pnpm - -``` sh -pnpm add vuepress-plugin-netlify-functions -``` - -::: diff --git a/docs/notes/plugins/netlify-functions/api.md b/docs/notes/plugins/netlify-functions/api.md deleted file mode 100644 index d5438d90..00000000 --- a/docs/notes/plugins/netlify-functions/api.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: API -author: pengzhanbo -createTime: 2024/03/12 13:55:25 -permalink: /plugins/plugin-netlify-functions/api/ ---- - -## netlifyFunctionsPlugin(options) - -在 vuepress 项目中使用， 或者 开发vuepress-theme时使用，提供 netlify-functions 开发时服务。 - -该插件应该优先于其他有依赖该插件的其他插件之前调用。 - -``` js -netlifyFunctionsPlugin({ - sourceDirectory: '', - destDirectory: '', - proxyPrefix: '', -}) -``` - -### options - -__类型：__ `{ sourceDirectory: string, destDirectory: string, proxyPrefix: string }` - -- `options.sourceDirectory`: - - `functions` 开发时所在目录， 默认值： `app.dir.source('.vuepress/functions')`, - 即，如果你的vuepress项目源码目录是 `src`， 那么 `sourceDirectory` 默认为 `src/.vuepress/functions/` - -- `options.destDirectory`: - - `functions` 构建后输出目录，默认值： `app.dir.dest('functions')`, - 即，如果你的 vuepress项目配置的 `dest` 输出目录为 `docs`， 那么默认输出目录为 `docs/functions`, - 一般来说，这个配置不需要手动修改。 - -- `options.proxyPrefix`: - - 在开发环境中， `Netlify Functions` 服务的默认路径是 `/.netlify/functions/*`, 但这并不能保持开发环境和 - 生产部署环境一致，所以需要将路径重写。 - - 默认值： `/api` - - 即 `^/api/*` 的请求会被转发到 `/.netlify/functions/*` ， - 如, `functions/my_function.ts` ，则请求 `/api/my_function` 将会转发到 `/.netlify/functions/my_function`。 - -## useNetlifyFunctionsPlugin(app, options) - -在开发 vuepress plugin 时使用，为插件提供 `netlify functiosn` 支持 - -``` ts -import { useNetlifyFunctionsPlugin } from 'vuepress-plugin-netlify-functions' - -function myPlugin(): Plugin { - return (app: App) => { - const { - // 请求前缀, 默认 /api - proxyPrefix, - preparePluginFunctions, - generatePluginFunctions - } = useNetlifyFunctionsPlugin(app, { - // 指定插件的functions目录，相关脚本在此目录中开发 - directory: path.resolve(__dirname, 'functions') - }) - return { - name: 'vuepress-plugin-myPlugin', - onPrepared: () => preparePluginFunctions(), - onGenerated: () => generatePluginFunctions(), - } - } -} -``` - -### options - -__类型：__ `{ directory: string }` - -- `options.directory` - - 插件中的 functions 开发目录。 - - 一般来说，它的值都设置为 `path.resolve(__dirname, 'functions')` diff --git a/docs/notes/plugins/netlify-functions/functions.md b/docs/notes/plugins/netlify-functions/functions.md deleted file mode 100644 index d335eace..00000000 --- a/docs/notes/plugins/netlify-functions/functions.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: functions 使用指南 -author: pengzhanbo -createTime: 2024/03/12 17:56:28 -permalink: /plugins/plugin-netlify-functions/functions/ ---- - -## 说明 - -### 在一个 vuepress 项目中 - -在默认配置下，如果你 packages.json - -``` json -{ - "scripts": { - "serve": "vuepress dev src", - "build": "vuepress build src" - } -} -``` - -即， 你的 `sourceDir` 为 `src` 目录， 那么，你的functions目录则为 `src/.vuepress/functions`。 - -在这个目录下，直属的 `ts/js` 文件，均为一个个独立的 `function`， 不包括这个目录下的子目录。 - -``` sh -src/.vuepress/functions -├─my_function.ts # 这是一个function 通过 /api/my_function 调用 -├─verify_phone.ts # 这是一个 function， 通过 /api/verify_phone 调用 -└─utils # 子目录中的不会被识别为function - └─index.ts -``` - -### 在一个 vuepress plugin 项目中 - -以官方仓库插件的基本组织结构为例 - -``` sh -src/node -├─functions -│ ├─my_function.ts # 这是一个function 通过 /api/my_function 调用 -│ ├─verify_phone.ts # 这是一个 function， 通过 /api/verify_phone 调用 -│ └─utils # 子目录中的不会被识别为function -│ └─index.ts -├─index.ts -└─plugin.ts # 在这个文件中配置了 directory 为 path.resolve(__dirname, 'functions') -``` - -## 依赖 - -如果你是使用 typescript 作为开发语言，那么可以引入 `@netlify/functions` 模块提供类型检查支持。 - -如果你的 function 依赖其他的第三方模块，请在配置在项目`package.json` 的 `dependencies` 字段中作为生产依赖。 - -如果你是通过插件提供 function，请在 插件的使用指南中 说明，你的插件function依赖了哪些第三方模块， -提醒使用者安装这些依赖。 - -## function - -`functions` 通过 导出一个 `handler` 函数 提供给 云函数服务调用。 - -一个 function 的内容一般如下： - -- 异步函数 - - 在异步函数中，支持直接返回一个对象作为 响应体报文 - - ``` ts - import { Handler } from '@netlify/functions' - export const handler: Handler = async function (event, context) { - // do something - return { - statusCode: 200, - body: JSON.stringify({}) - } - } - ``` - -- 非异步函数 - - 在非异步函数中，通过 `callback` 函数参数返回响应体报文 - - ``` ts - import { Handler } from '@netlify/functions' - - export const handler: Handler = function (event, context, callback) { - // do something - callback({ - statusCode: 200, - body: JSON.stringify({}) - }) - } - ``` - -## 示例 - -[plugin-page-collection](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-page-collection) -页面访问次数插件 diff --git a/docs/notes/plugins/netlify-functions/介绍.md b/docs/notes/plugins/netlify-functions/介绍.md deleted file mode 100644 index c3bde97d..00000000 --- a/docs/notes/plugins/netlify-functions/介绍.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: 介绍 -author: pengzhanbo -createTime: 2024/03/12 14:11:59 -permalink: /plugins/plugin-netlify-functions/introduction/ ---- - -## Why - -### Netlify - -[Netlify](https://www.netlify.com/) 是一个提供了免费部署静态站点的平台，可用于作为 `github page` 的替代工具。 - -在 `Netlify` 上面部署站点也非常方便，可以直接使用 `github` 仓库进行 构建并部署，同时支持 自定义域名。 - -还提供了 `Netlify Functions` 等工具，可以用于给站点提供 自定义云函数。 - -### VuePress - -`vuepress` 是一个很方便的静态网站构建工具，使我们可以直接书写 markdown后，构建为一个高可用的静态站点。 - -### 部署 - -一般情况下，当我们不希望购买一个服务器用于部署我们的站点时，通常都会选择使用 `github page` 来进行免费部署。 -`Netlify` 是一种替代方案，而且当使用 `Netlify` 部署时，还可以利用 `Netlify Functions` 提供的云函数功能， -使站点能够进行更为丰富的交互。 - -### 场景 - -通过 `Functions` 连接到 一些提供了 免费服务的 云存储服务，比如 `FireBase` ，`Lean Cloud` 等。 -虽然这些云存储服务提供了 Web 客户端直连服务的功能。但毕竟我们的站点源码是直接放在 `github`开源仓库中， -我们不希望将 这些 云存储服务 提供的一些 鉴权信息 直接 保存在 仓库代码中，带来某些安全风险。 - -在这种场景下，就可以借助 `Netlify Functions` ，将这些鉴权信息，作为 `环境变量` ， -托管在 `Netlify Environment Variables` 中，然后通过 站点调用 `Functions` 来获取这些鉴权信息。 -或者进一步的，直接将 云存储服务的 连接、功能等，都在 `Netlify Functions` 中完成， -站点再调用 `Functions` 接口， 获取返回的数据。 - -有了 `Netlify Functions` 加上 一些 第三方的 云服务支持， 可以为我们的 vuepress 站点提供更强大的支持。 - -## 如何整合？ - -在基于以上的背景，下一步就是需要将 `Netlify Functions` 能够在 我们的 `Vuepress` 项目中进行 整合了。 - -- 如何使 `Netlify Functions` 能够在本地开发环境中进行调试。 -- 如何将 已开发好的 `Functions` 作为 `vuepress plugin` 提供给 其他 `vuepress theme` 或 `vuepress` 站点中使用。 - -### 开发环境 - -本插件在 vuepress 的开发服务的基础上， 启动了一个 由 `netlify-cli` 提供的 服务，并将该服务通过代理的方式， -代理到 vuepress开发服务上，统合开发环境。 - -并且监听 functions 内容变更，实现热更新。 - -### 打包 - -在打包阶段， 生成一个 `netlify.toml` 配置文件，配置 functions 相关内容。 - -并且将 所有 functions 添加在 vuepress 的构建包中。 - -如何使用插件，请查看 [使用文档](./使用.md) diff --git a/docs/notes/plugins/netlify-functions/使用.md b/docs/notes/plugins/netlify-functions/使用.md deleted file mode 100644 index d28b1683..00000000 --- a/docs/notes/plugins/netlify-functions/使用.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: 使用 -author: pengzhanbo -createTime: 2024/03/12 15:53:55 -permalink: /plugins/plugin-netlify-functions/usage/ ---- - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install vuepress-plugin-netlify-functions -``` - -@tab:active yarn - -``` sh -yarn add vuepress-plugin-netlify-functions -``` - -@tab pnpm - -``` sh -pnpm add vuepress-plugin-netlify-functions -``` - -::: - -## 在vuepress中使用 - -### 添加插件 - -在vuepress 的配置文件中 引入并 在 `plugins` 字段中添加插件。 - -::: code-tabs -@tab .vuepress/config.{ts,js} - -``` ts -import { defineUserConfig } from 'vuepress' -import { netlifyFunctionsPlugin } from 'vuepress-plugin-netlify-functions' - -export default defineUserConfig({ - // ... - plugins: [ - netlifyFunctionsPlugin(), - ] - // ... -}) -``` - -::: - -### 编写 functions - -启动 vuepress 开发服务后， 就可以在你的 `.vuepress/functions/` 目录中，新建并开发你的 `function` - -[`functions` 开发指南](https://docs.netlify.com/functions/overview/) - -## 在 vuepress plugin 中使用 - -### 添加插件钩子 - -::: code-tabs -@tab typescript - -``` ts -import * as path from 'node:path' -import { App } from '@vuepress/core' -import { useNetlifyFunctionsPlugin } from 'vuepress-plugin-netlify-functions' - -function myPlugin(): Plugin { - return (app: App) => { - const { - // 请求前缀, 默认 /api - proxyPrefix, - preparePluginFunctions, - generatePluginFunctions - } = useNetlifyFunctionsPlugin(app, { - // 指定插件的functions目录，相关脚本在此目录中开发 - directory: path.resolve(__dirname, 'functions') - }) - return { - name: 'vuepress-plugin-myPlugin', - onPrepared: () => preparePluginFunctions(), - onGenerated: () => generatePluginFunctions(), - } - } -} -``` - -::: - -在你的插件开发目录，假如是以下结构： - -``` sh -. -└─src # 开发目录 - ├─shared - └─node # node 端 - ├─functions # functions目录 - │ └─my_function.ts # functions脚本 - ├─plugin.ts - └─index.ts -``` - -那么，就在你的 `src/node/functions` 目录下进行 functions 开发 - -[`functions` 开发指南](https://docs.netlify.com/functions/overview/) - -如果你已经开发好了一个 `functions/my_function.ts` 的function。 - -那么你可以在 client端，通过以下方式调用： - -``` ts -async function fetchMyFunction() { - const result = await fetch('/api/my_functions') - // do something -} -``` - -就像调用一个普通接口一个样简单。 - -## 环境变量 - -你可以在项目根目录中，新建一个 `.env` 文件，用于配置开发时环境变量 - -::: warning -这些环境变量仅用于开发环境时使用，部署生产时不会被加载。 - -是用于在开发环境中 代替 `Netlify Environment Variables` 。 -在生产环境中，应该使用 `Netlify Environment Variables` 设置这些环境变量。 - -如果你的 `.env` 文件中有比较私密的信息，建议将 `.env` 文件添加到 `.gitignore` 中，避免提交到 仓库中。 -::: - -::: code-tabs -@tab .env - -``` -YOUR_ENV_VAR='your env var' -``` - -@tab functions/my_function.ts - -``` ts -const YOUR_ENV_VAR = process.env.YOUR_ENV_VAR -``` - -::: - -## 示例 - -如何使用本插件开发一个 提供 functions 的插件，这里提供了一个 例子： - -[plugin-page-collection](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-page-collection) - -可以参考此例子进行插件开发。 - -该例子提供了以下功能： - -- 连接 `lean cloud` -- 记录页面访问次数，并上报到 `lean cloud` 数据库。 -- 查询 当前页面访问次数，并提供组件嵌入到页面中。 diff --git a/docs/notes/plugins/netlify-functions/功能.md b/docs/notes/plugins/netlify-functions/功能.md deleted file mode 100644 index 9a33f821..00000000 --- a/docs/notes/plugins/netlify-functions/功能.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: 功能 -author: pengzhanbo -createTime: 2024/03/12 14:43:12 -permalink: /plugins/plugin-netlify-functions/features/ ---- - -## 功能 - -在启动 vuepress 开发环境后，`plugin-netlify-functions` 插件会在 vuepress 开发服务中， -启动一个 `netlify-functions` 服务，然后，将通过 vuepress 开发服务代理该服务。 - -同时，启动对 `functions` 的文件监听，实现服务热更新，从而获得与 vuepress 开发服务环境一致的体验。 - -## 服务 - -考虑到通用性，本插件仅提供对于 `netlify functions` 的开发时和构建时支持，并不提供具体的 `functions`功能支持。 -一切`functions` 功能由插件使用者自定义。 - -同时，还提供了给其他插件使用本插件的钩子，这使得多个插件之间或者主题，能够共享 本插件提供的基础服务。 diff --git a/docs/notes/plugins/shiki.md b/docs/notes/plugins/shiki.md deleted file mode 100644 index 6a329189..00000000 --- a/docs/notes/plugins/shiki.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: plugin-shikiji -author: pengzhanbo -createTime: 2024/03/11 17:26:31 -permalink: /plugins/plugin-shikiji/ -tags: - - 插件 - - 代码高亮 ---- - -## 指南 - -使用 [`shiki`](https://shiki.style) 来为 Markdown 代码块启用代码高亮。 - -::: important -如果您正在使用 **vuepress-theme-plume** 主题，主题已内置了 本插件，您无需安装本插件。 - -只需要在 [配置 > 内置插件 > shiki](../theme/config/plugins/代码高亮.md) 中配置本插件即可。 -::: - -## 安装 - -::: code-tabs -@tab npm - -``` sh -npm install @vuepress-plume/plugin-shikiji -``` - -@tab:active yarn - -``` sh -yarn add @vuepress-plume/plugin-shikiji -``` - -@tab pnpm - -``` sh -pnpm add @vuepress-plume/plugin-shikiji -``` - -::: - -## 使用 - -```ts -// .vuepress/config.ts -import shikiPlugin from '@vuepress-plume/plugin-shikiji' -module.exports = { - // ... - plugins: [ - shikiPlugin({ - // options ... - }) - ] - // ... -} -``` - -## Options - -```ts -interface ShikiOptions { - /** - * Custom theme for syntax highlighting. - * - * You can also pass an object with `light` and `dark` themes to support dual themes. - * - * @example { theme: 'github-dark' } - * @example { theme: { light: 'github-light', dark: 'github-dark' } } - * - * You can use an existing theme. - * @see https://shiki.style/themes - * Or add your own theme. - * @see https://shiki.style/guide/load-theme - */ - theme?: ThemeOptions - /** - * Languages for syntax highlighting. - * @see https://shiki.style/languages - */ - languages?: LanguageInput[] - /** - * Custom language aliases. - * - * @example { 'my-lang': 'js' } - * @see https://shiki.style/guide/load-lang#custom-language-aliases - */ - languageAlias?: Record - /** - * Setup Shiki instance - */ - shikiSetup?: (shikiji: Highlighter) => void | Promise - /** - * Fallback language when the specified language is not available. - */ - defaultHighlightLang?: string - /** - * Transformers applied to code blocks - * @see https://shiki.style/guide/transformers - */ - codeTransformers?: ShikiTransformer[] - /** - * Enable transformerRenderWhitespace - * @default false - */ - whitespace?: boolean - - /** - * @experimental - */ - twoslash?: boolean -} -```