docs: improve docs
This commit is contained in:
pengzhanbo
parent
436a818c2e
commit
6ea670c16a
@ -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,
|
||||
],
|
||||
})
|
||||
|
||||
@ -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/)
|
||||
@ -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 <feature> {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 <feature> {browser_versions}
|
||||
:::
|
||||
```
|
||||
|
||||
### `<feature>`
|
||||
|
||||
必填。 正确取值请参考 [https://caniuse.bitsofco.de/](https://caniuse.bitsofco.de/)
|
||||
|
||||
### `{browser_versions}`
|
||||
|
||||
可选。当前特性在多个版本中的支持情况。
|
||||
|
||||
默认值为: `{-2,-1,1}`
|
||||
|
||||
格式： `{number,number,...}` 取值范围为 `-5 ~ 3`
|
||||
|
||||
- 小于`0` 表示低于当前浏览器版本的支持情况
|
||||
- `0` 表示当前浏览器版本的支持情况
|
||||
- 大于`0` 表示高于当前浏览器版本的支持情况
|
||||
@ -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` 内置插件 `<Content />` 进行重写替换，并提供了 `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
|
||||
<script lang="ts" setup>
|
||||
import { onContentUpdated } from '@vuepress-plume/plugin-content-update/client'
|
||||
|
||||
onContentUpdated(() => {
|
||||
// do something
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
||||
获取 `medium-zoom` 实例， 当 markdown 内容更新时， 刷新 `medium-zoom` 实例，使新增的图片可放大
|
||||
|
||||
```vue
|
||||
<script lang="ts" setup>
|
||||
import { useMediumZoom } from '@vuepress/plugin-medium-zoom/client'
|
||||
import { onContentUpdated } from '@vuepress-plume/plugin-content-update/client'
|
||||
|
||||
const mediumZoom = useMediumZoom()
|
||||
|
||||
onContentUpdated(() => {
|
||||
mediumZoom?.refresh()
|
||||
})
|
||||
</script>
|
||||
```
|
||||
@ -1,103 +0,0 @@
|
||||
---
|
||||
title: plugin-iconify
|
||||
author: pengzhanbo
|
||||
createTime: 2024/03/13 17:28:25
|
||||
permalink: /plugins/plugin-iconify/
|
||||
tags:
|
||||
- 插件
|
||||
- 图标
|
||||
---
|
||||
|
||||
## 指南
|
||||
|
||||
添加 `iconify` 图标库支持。并注入全局组件 `<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
|
||||
<template>
|
||||
<Iconify name="material-symbols:home" color="currentColor" size="1em" />
|
||||
</template>
|
||||
```
|
||||
|
||||
### 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
|
||||
}
|
||||
```
|
||||
|
||||
效果： <Iconify name="material-symbols:home" color="currentColor" size="1em" />
|
||||
@ -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
|
||||
```
|
||||
:::
|
||||
````
|
||||
@ -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
|
||||
```
|
||||
|
||||
:::
|
||||
@ -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')`
|
||||
@ -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)
|
||||
页面访问次数插件
|
||||
@ -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)
|
||||
@ -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` 数据库。
|
||||
- 查询 当前页面访问次数，并提供组件嵌入到页面中。
|
||||
@ -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` 功能由插件使用者自定义。
|
||||
|
||||
同时，还提供了给其他插件使用本插件的钩子，这使得多个插件之间或者主题，能够共享 本插件提供的基础服务。
|
||||
@ -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<string, string>
|
||||
/**
|
||||
* Setup Shiki instance
|
||||
*/
|
||||
shikiSetup?: (shikiji: Highlighter) => void | Promise<void>
|
||||
/**
|
||||
* 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
|
||||
}
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user