What is a plug-in

The Gitbook plugin is the best way to extend the functionality of Gitbook (e-books and websites).

Anything Gitbook doesn’t provide by default can be extended based on the plug-in mechanism, and plug-ins make Gitbook even more powerful.

This article will comprehensively introduce the relevant knowledge of plug-ins and focus on the whole process of plug-in development, only familiar with the process of plug-in development can be targeted, have a good idea, and then develop their own plug-ins.

For more information about plug-ins, see the Advanced Gitbook Tutorial series, which focuses on the basic process of developing Gitbook.

  • Gitbook introduction to the plugin tutorial
  • Gitbook tutorial utility plug-in
  • Theme plugin for gitbook tutorial

How to discover plug-ins

You can easily search for the Gitbook plugin on ~~Gitbook website, or search for the gitbook-plugin-

plugin on NPMJS website.

At present, Gitbook is no longer the official website for maintaining plug-ins, only through NPMJS to discover Gitbook plug-ins.

How to install plug-ins

Once you find the plug-in you want to install, you need to add it to your book.json configuration file, or create it yourself if you don’t have it.

{
    "plugins": ["myPlugin"."anotherPlugin"]}Copy the code

You can also specify a specific version using the following command: [email protected]. If version is not specified by default,GitBook uses ** latest version (compatible version)** plugins.

Installing a plug-in

  • If you are in an online environment, the site will automatically install the plug-in for you.
  • If you’re in a local environment,Run directly gitbook installTo install the plug-in.
$ gitbook install
Copy the code

Or use NPM to download the plug-in in advance and install it into your local project:

$ npm install gitbook-plugin-<name>

$ gitbook install
Copy the code

Configure the plug-in

The plugin configuration is in the pluginsConfig property in the book.json configuration file (if you do not have this property, create it yourself). When installing the plug-in, it is best to consult the plug-in documentation for more information about the options.

{
    "plugins": ["github"]."pluginsConfig": {
        "github": {
          "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"}}}Copy the code

Some plug-ins do not provide plug-in configuration items, so you can skip this step. Some plug-ins provide configuration items. For details, see the plug-in documentation.

How to develop plug-ins

The GitBook plug-in is a traditionally defined Node package released on NPM, with some specifications defined by GitBook itself in addition to the standard Node specification.

The directory structure

The basic project structure of the Gitbook plug-in includes at least the package.json configuration file and the entry file index.js, and other directory files can be added or reduced according to the purpose of the plug-in.

.├ ─ index.js ├─ package.jsonCopy the code

Actual plug-in projects vary slightly, and may also have a _layouts directory, an Asset resource directory, a custom Example directory, and a docs document directory.

package.json

Json is a package.json configuration file for **nodejs**. The Gitbook plug-in also follows this specification. The configuration file declares the description of the version of the plug-in, in addition to the Gitbook related fields.

{
    "name": "gitbook-plugin-mytest"."version": "0.0.1"."description": "This is my first GitBook plugin"."engines": {
        "gitbook": ">1.x.x"
    },
    "gitbook": {
        "properties": {
            "myConfigKey": {
                "type": "string"."default": "it's the default value"."description": "It defines my awesome config!"}}}}Copy the code

It is worth noting that the package name must begin with gitbook-plugin-, and the package engine should include Gitbook. For the specification of package.json, refer to the official documentation

index.js

Index.js is the entry to the plugin runtime, as shown in the following basic example:

module.exports = {
    // The hook function
    hooks: {},

    / / code block
    blocks: {},

    / / filter
    filters: {}
};
Copy the code

Release the plugin

The GitBook plug-in can be published on the NPMJS website.

To publish plug-ins, you need to register an account on the NPMJS website and publish them from the command line.

$ npm publish
Copy the code

Special plug-ins

Dedicated plug-ins can be hosted on GitHub and use Git urls:

{
    "plugins": [
        "myplugin@git+https://github.com/MyCompany/mygitbookplugin.git#1.0.0"]}Copy the code

Local test plug-in

Use NPM link to test your plugin before release. See the official documentation for details

In the plugin folder, run:

$ npm link
Copy the code

Then execute it in your book or document folder:

$ npm link gitbook-plugin-<name>
Copy the code

Unit test plug-in

Gitbook-tester makes it easy to write Node.js/Mocha unit tests for your plug-in.

You can run tests on each commit/tag using Travis.

Plug-in summary

The Gitbook plugin is a great way to extend the functionality of Gitbook. If you are familiar with the nodeJS project development process and have some familiarity with the interface documentation provided by Gitbook, you should be able to develop your own plugin.

I hope this article has helped you understand the Gitbook plugin, understand and master the whole process of plug-in development, and if this article has helped you, don’t forget to give me positive feedback to encourage me to continue to create!

Reading extension

  • What is theGitbookThe plug-in
  • How to createGitbookThe plug-in
  • How to testGitbookThe plug-in

If you feel that this article is helpful to you, welcome to like the message to tell me, your encouragement is my motivation to continue to create, might as well pay attention to the personal public number “snow dream technology station”, regularly update quality articles!