White gitbook Getting Started tutorial can understand the whole process of Gitbook plug-in development

What is a plug-in

GitbookPlug-in is extended GitBook functions (e-books and websites) in the best way .

As long as Gitbook the default function is not provided , based on plug-in mechanism can be self-expansion , is the plugin allows Gitbookmuch more powerful.

This article will fully introduce the relevant knowledge Plug and focuses on the whole process of plug-in development , only familiar with the plug-in development processes to be targeted aware of in order to develop their own plug-ins.

About Plug-ins Refer to the GitbookGetting Started tutorial Senior Advanced series, focusing on the development of this paper to explain Gitbookthe basic flow .

gitbook Getting Started tutorial introduces plug-ins

Getting Started tutorial utility plug gitbook

gitbook Getting Started tutorial theme plugin

How to find plug-ins

You can~~GitbookOfficial website~~Easily search plug-in can also be in npmjsthe official website of the search gitbook-plugin-<name>plug-ins.

Currently Gitbookthe official has no longer maintain Plugin website, only through the npmjsdiscovery Gitbookplug-ins.

How to install plug-ins

Once you find the plugin you want to install, you need to add it to your book.jsonconfiguration file, if the file is not self-created.

{
    "plugins": ["myPlugin", "anotherPlugin"]
}

You can also use the following command to specify a specific version: [email protected].
Default version does not fill, GitBookuse the latest version (compatible version) plug-ins.

Install plug

If this is the official website of the online environment, the site will automatically help you install the plugin.
If it is in the local environment, directly run gitbook install to install the plug-in.

$ gitbook install

Or use the npm advance to download plug-ins to install to a local project :

$ npm install gitbook-plugin-<name>

$ gitbook install

Configure the plugin

Configure the plug-in book.jsonconfiguration file pluginsConfigproperty (if the property is not your own creation),
when installed plug-ins, the best browser plug-in documentation for more information about the options.

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

Some plug-ins do not provide plug-in configuration items, this step can be omitted, and some plug-in provides configuration items to plug presentations document shall prevail.

How to develop plug-ins

GitBookPlug-in is npmposted on follow the traditional definition of the nodepackage, in addition to the standard nodeexternal norms there are some Gitbookself-defined by the relevant norms.

Directory Structure

GitbookThe most basic item plug structure comprising at least profile package.json and entry files index.js , other directory file itself changes in accordance with the use of plug-ins.

.
├── index.js
└── package.json

The actual plug-in project is slightly different, there may be _layoutsthe layout of directories, assetresource directories and custom exampleexamples, and docsdocumentation directories, and so on.

package.json

package.jsonIs the nodejsconfiguration file, Gitbookthe plug also follow the specification, configuration file declares version descriptive information, in addition to plug-in Gitbookrelated fields, follow the schemaguidelines basic example is as follows:

{
    "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!"
            }
        }
    }
}

It is noteworthy that, the package name must gitbook-plugin-begin with, packet engine should be included gitbook. For package.jsonspecifications, refer to the official documentation

index.js

index.js It is an inlet plug runtime basic example as follows:

module.exports = {
    // 钩子函数
    hooks: {},

    // 代码块
    blocks: {},

    // 过滤器
    filters: {}
};

Release plug

GitBookPlug-in npmjs's official website posted on.

To release the plug, you first need in npmjsthe official website of the registered account , then issue the command line.

$ npm publish

Special plug-ins

Special plug-ins can be hosted GitHubon, and use giturls:

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

Local test plug-in

Use npm linkcan test your plug-in before the release, the command reference details of official documents

Plug-in file folders, run:

$ npm link

Then execute your book or document file folder:

$ npm link gitbook-plugin-<name>

Unit testing plug

gitbook-testerYou can easily write plugins Node.js / Mocha unit tests.

Use Traviscan submit / tag for each test run.

Plug summary

GitbookPlug-in is an extension of Gitbookprime function of the election, if familiar with the nodejsdevelopment process of the project, as long as the slightly familiar Gitbookinterface documentation provided to develop their own plug-ins should not be difficult!

Hopefully this article to your understanding of Gitbookplug-in help, understand and master the whole process of plug-in development, if this article help you, do not forget to give me a positive feedback to encourage me to continue to create yo!

Reading extended

If this article help you, please tap the touch of hands is recommended , otherwise also correct me please leave a message and, if necessary, public awareness of personal numbers, " Snow Dream Inn technology ."

Snow Dream Inn technology .png