docs/write-a-plugin.md · ht131/docsify

代码拉取完成,页面将自动刷新

扫描微信二维码支付

取消

支付完成

richgiteeai

Watch

不关注关注所有动态仅关注版本发行动态关注但不提醒动态

1 Star 0 Fork 135

ht131/docsify

forked from docsifyjs/docsify

代码 Issues 0 Pull Requests 0 统计流水线

服务

加入 Gitee

与超过 1400万开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)

免费加入

已有帐号? 立即登录

文件

develop

分支 (37)

标签 (194)

管理

develop

snyk-upgrade-e312495bf5fe875759f38abb9fa661a7

dependabot/npm_and_yarn/glob-11.0.1

dependabot/npm_and_yarn/eslint-config-prettier-10.0.1

fix/1854

github-callouts

v5-style-overhaul-update-1

update-rewrite-gr-config

pullrequests/akshaybhinge19/lang-translation-flag

unhide-build-errors

type-definitions

gh-pages

main

master

routerMode-history-for-website

enhance-scroll

fix-1525

pin-script-versions

onlyCoverNavbar-option

element-value-for-el-option

v4.13.1

v4.13.0

v4.12.4

v4.12.2

v4.12.1

v4.12.0

v4.11.6

v4.11.5

v4.11.4

v4.11.3

v4.11.2

v4.11.1

v4.11.0

v4.10.2

v4.10.0

v4.9.4

v4.9.2

v4.9.1

v4.9.0

v4.8.6

克隆/下载

HTTPS SSH SVN SVN+SSH 下载ZIP

提示

下载代码请复制以下命令到终端执行

为确保你提交的代码身份被 Gitee 正确识别,请执行以下命令完成配置

git config --global user.name userName 
git config --global user.email userEmail

初次使用 SSH 协议进行代码克隆、推送等操作时,需按下述提示完成 SSH 配置

1 生成 RSA 密钥

2 获取 RSA 公钥内容,并配置到 SSH公钥中

在 Gitee 上使用 SVN,请访问使用指南

使用 HTTPS 协议时,命令行会出现如下账号密码验证步骤。基于安全考虑,Gitee 建议配置并使用私人令牌替代登录密码进行克隆、推送等操作

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # 私人令牌

分支 37

标签 194

docsify

docs

write-a-plugin.md

write-a-plugin.md 5.37 KB

# Write a plugin

A docsify plugin is a function with the ability to execute custom JavaScript code at various stages of Docsify's lifecycle.

## Setup

Docsify plugins can be added directly to the `plugins` array:

```js
window.$docsify = {
 plugins: [
 function myPlugin1(hook, vm) {
 // ...
 },
 function myPlugin2(hook, vm) {
 // ...
 },
 ],
};
```

Alternatively, a plugin can be stored in a separate file and "installed" using a standard `<script>` tag:

```js
// docsify-plugin-myplugin.js

{
 function myPlugin(hook, vm) {
 // ...
 }

// Add plugin to docsify's plugin array
 window.$docsify = window.$docsify || {};
 $docsify.plugins = [...($docsify.plugins || []), myPlugin];
}
```

```html
<script src="docsify-plugin-myplugin.js"></script>
```

## Template

Below is a plugin template with placeholders for all available lifecycle hooks.

1. Copy the template
1. Modify the `myPlugin` name as appropriate
1. Add your plugin logic
1. Remove unused lifecycle hooks
1. Save the file as `docsify-plugin-[name].js`
1. Load your plugin using a standard `<script>` tag

```js
{
 function myPlugin(hook, vm) {
 // Invoked one time when docsify script is initialized
 hook.init(() => {
 // ...
 });

// Invoked one time when the docsify instance has mounted on the DOM
 hook.mounted(() => {
 // ...
 });

// Invoked on each page load before new markdown is transformed to HTML.
 // Supports asynchronous tasks (see beforeEach documentation for details).
 hook.beforeEach(markdown => {
 // ...
 return markdown;
 });

// Invoked on each page load after new markdown has been transformed to HTML.
 // Supports asynchronous tasks (see afterEach documentation for details).
 hook.afterEach(html => {
 // ...
 return html;
 });

// Invoked on each page load after new HTML has been appended to the DOM
 hook.doneEach(() => {
 // ...
 });

// Invoked one time after rendering the initial page
 hook.ready(() => {
 // ...
 });
 }

// Add plugin to docsify's plugin array
 window.$docsify = window.$docsify || {};
 $docsify.plugins = [myPlugin, ...($docsify.plugins || [])];
}
```

## Lifecycle Hooks

Lifecycle hooks are provided via the `hook` argument passed to the plugin function.

### init()

Invoked one time when docsify script is initialized.

```js
hook.init(() => {
 // ...
});
```

### mounted()

Invoked one time when the docsify instance has mounted on the DOM.

```js
hook.mounted(() => {
 // ...
});
```

### beforeEach()

Invoked on each page load before new markdown is transformed to HTML.

```js
hook.beforeEach(markdown => {
 // ...
 return markdown;
});
```

For asynchronous tasks, the hook function accepts a `next` callback as a second argument. Call this function with the final `markdown` value when ready. To prevent errors from affecting docsify and other plugins, wrap async code in a `try/catch/finally` block.

```js
hook.beforeEach((markdown, next) => {
 try {
 // Async task(s)...
 } catch (err) {
 // ...
 } finally {
 next(markdown);
 }
});
```

### afterEach()

Invoked on each page load after new markdown has been transformed to HTML.

```js
hook.afterEach(html => {
 // ...
 return html;
});
```

For asynchronous tasks, the hook function accepts a `next` callback as a second argument. Call this function with the final `html` value when ready. To prevent errors from affecting docsify and other plugins, wrap async code in a `try/catch/finally` block.

```js
hook.afterEach((html, next) => {
 try {
 // Async task(s)...
 } catch (err) {
 // ...
 } finally {
 next(html);
 }
});
```

### doneEach()

Invoked on each page load after new HTML has been appended to the DOM.

```js
hook.doneEach(() => {
 // ...
});
```

### ready()

Invoked one time after rendering the initial page.

```js
hook.ready(() => {
 // ...
});
```

## Tips

- Access Docsify methods and properties using `window.Docsify`
- Access the current Docsify instance using the `vm` argument
- Developers who prefer using a debugger can set the [`catchPluginErrors`](configuration#catchpluginerrors) configuration option to `false` to allow their debugger to pause JavaScript execution on error
- Be sure to test your plugin on all supported platforms and with related configuration options (if applicable) before publishing

## Examples

#### Page Footer

```js
window.$docsify = {
 plugins: [
 function pageFooter(hook, vm) {
 const footer = /* html */ `
 <hr/>
 <footer>
 <span><a href="https://github.com/QingWei-Li">cinwell</a> &copy;2017.</span>
 <span>Proudly published with <a href="https://github.com/docsifyjs/docsify" target="_blank">docsify</a>.</span>
 </footer>
 `;

hook.afterEach(html => {
 return html + footer;
 });
 },
 ],
};
```

### Edit Button (GitHub)

```js
window.$docsify = {
 plugins: [
 function editButton(hook, vm) {
 // The date template pattern
 $docsify.formatUpdated = '{YYYY}/{MM}/{DD} {HH}:{mm}';

hook.beforeEach(html => {
 const url =
 'https://github.com/docsifyjs/docsify/blob/master/docs/' +
 vm.route.file;
 const editHtml = '[📝 EDIT DOCUMENT](' + url + ')\n';

return (
 editHtml +
 html +
 '\n----\n' +
 'Last modified {docsify-updated}' +
 editHtml
 );
 });
 },
 ],
};
```

一键复制编辑原始数据按行查看历史

Joe Pea 提交于 2023年07月03日 16:27 +08:00 . chore: update miscellaneous parts of the source to reasonably modern l...