write-a-plugin.md

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:

window.$docsify={plugins: [functionmyPlugin1(hook,vm){// ...},functionmyPlugin2(hook,vm){// ...},],};

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

// docsify-plugin-myplugin.js{functionmyPlugin(hook,vm){// ...}// Add plugin to docsify's plugin arraywindow.$docsify=window.$docsify||{};$docsify.plugins=[...($docsify.plugins||[]),myPlugin];}

<scriptsrc="docsify-plugin-myplugin.js"></script>

Template

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

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

{functionmyPlugin(hook,vm){// Invoked one time when docsify script is initializedhook.init(()=>{// ...});// Invoked one time when the docsify instance has mounted on the DOMhook.mounted(()=>{// ...});// Invoked on each page load before new markdown is transformed to HTML.// Supports asynchronous tasks (see beforeEach documentation for details).hook.beforeEach(markdown=>{// ...returnmarkdown;});// Invoked on each page load after new markdown has been transformed to HTML.// Supports asynchronous tasks (see afterEach documentation for details).hook.afterEach(html=>{// ...returnhtml;});// Invoked on each page load after new HTML has been appended to the DOMhook.doneEach(()=>{// ...});// Invoked one time after rendering the initial pagehook.ready(()=>{// ...});}// Add plugin to docsify's plugin arraywindow.$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.

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

mounted()

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

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

beforeEach()

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

hook.beforeEach(markdown=>{// ...returnmarkdown;});

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.

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.

hook.afterEach(html=>{// ...returnhtml;});

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.

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.

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

ready()

Invoked one time after rendering the initial page.

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 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

window.$docsify={plugins: [functionpageFooter(hook,vm){constfooter=/* 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=>{returnhtml+footer;});},],};

Edit Button (GitHub)

window.$docsify={plugins: [functioneditButton(hook,vm){// The date template pattern$docsify.formatUpdated='{YYYY}/{MM}/{DD} {HH}:{mm}';hook.beforeEach(html=>{consturl='https://github.com/docsifyjs/docsify/blob/main/docs/'+vm.route.file;consteditHtml='[📝 EDIT DOCUMENT]('+url+')\n';return(editHtml+html+'\n----\n'+'Last modified {docsify-updated}'+editHtml);});},],};