Create a gitbook plugin locally without publishing it

Question

I want to learn writing plugins for gitbook (because I want to use it and will need custom plugins).

However, I feel documentation is a bit sparse on the matter, and reading code from existing plugins doesn't help me very much in this question:

How can I test a plugin before publishing it. The documentation gives some hints on how the plugin has to look, and then it tells me to publish it.

Of course I don't want to do that yet, I want to develop and test it locally before publishing. But I don't see how that can be done.

I tried to copy an installed plugin inside /usr/lib/node_modules/gitbook-cli/node_modules/ to create my new plugin, but when I try to use the plugin in a book I get error message telling me to install the plugin through npm.

Is there a way to use a plugin (for testing or maybe generally) without first publishing it on npm?

Answer 1

This is not a definitive answer (so I won't "accept" it), but a workaround I found, which can be acceptable, depending on the circumstance.

What is possible is:

• Write a (preliminary) plugin
• publish to NPM
• Add the plugin to a book's book.json
• run gitbook install in the book's directory

This will download and install the plugin inside the book's node_module directory. Modifying the JavaScript files there will take effect on subsequent gitbook builds. So you can continue developing your plugin locally.

What has to be seen is how (if) that modified plugin can be published, once it's ready.

And it may be considered a (more or less severe) drawback that you now have a completely unpresentable plugin published on npm.

Answer 2

Comming late to this subject. But still relevant for me.

I also wanted to have custom plugins on local which didn't require publishing.

In the end as a hack I managed to do the following:

• gitbook install (without your custom plugin)

• in the serve folder go to node_modules

• create a folder gitbook-plugin-mytest

• add a index.js and a package.json

  you can look at : https://github.com/GitbookIO/gitbook/blob/master/docs/plugins/create.md

• in book.json in the "plugins" list add your "mytest" plugin

  "plugin": ["mytest"]

• now after gitbook serve your plugin should be added

---

maybe this can be turned into a CI / CD script, but for local environment where you don't require such control this should be enough.

Answer 3

A gitbook plugin is just a NPM module. You can use the way to develop npm module locally in development of gitbook plugin.

Npm provides the link command to handle this situation.

First, in your gitbook plugin folder, run below command to create globally-installed symbolic link to your plugin:

npm link

Next in your gitbook folder, run below command to link the global gitbook-plugin-name symbolic link under your gitbook's node_modules folder:

npm link gitbook-plugin-name

Configure your plugin in book.json. Now you can test the plugin in your gitbook without publish.

Answer 4

You could skip the initial publish to NPM by symlinking your plugin directory to your node_modules directory. Assume a directory structure:

projects/
  my-book/
    node_modules/
    other_files...
  awesome-plugin/
    plugin_files...

then you could do

cd projects/my-book/node_modules
ln -s ../../awesome-plugin

You may have to add the plugin to book.json to get it to register, but try it without first. Also I'm assuming a *NIX environment; you may have to look up the commands for Windows, but the concept is the same.

---

Separately from my above answer, you could use NPM's namespaced packages to publish your plugin to a private namespace (e.g., @uli_1973/awesome-plugin). Then, when you're ready for the big-time, you can claim the non-namespaced name for your plugin (awesome-plugin).