Maintaining a Custom Wiki

You will want to include your custom plugins in some or all of the servers you operate. Here we explore various workflows that simplify this task.

Warning: This workflow has proven to be unreliable and will be replaced by plugin support within wiki. It is left here for historical reference. See About Plugmatic Plugin

We'll assume you login to remote computers that hosts your wiki servers.

Our goal is for you to be able to install and run your custom wiki with the convenience of the standard distribution.

We describe how to host a custom configuration in github under <you> and install it with with any one of these progressively similar commands.

If you have just built a new version of a plugin you can load it into a locally installed version of wiki.

Wiki is published to npm from a github project, wiki, that brings client, server and plugins together from other places. github

Login to your own github account, <you>, then fork the wiki repo into your account. The fork button is in the second row of header buttons. When the fork completes, you can use this custom configuration for all installs.

The wiki repo keeps its list of plugins to be included with each install as the "dependents" field in the package.json file. You can edit this file using the github web editor or by cloning and pushing changes from your own computer.

For example, I've added the experimental search plugin by adding its npm name to the package.json list of dependents. github

If I hadn't already published my experimental plugin to npm, I could just as well add a dependent on the plugin's repo, here with npm shorthand so long as I included the javascript version of the plugin. github

In this form the repo is assumed to be hosted by github and the desired version on master. Other options are available with more complete syntax. doc

The node package manager (npm) has commands that will install plugins and update the package.json at the same time. You can add plugins and decide later if you want to keep them through other updates.

The advantage of this approach is that only one file is changed and changed such that one can easily merge updates from its upstream source. We'll adapt this section from the github help.

It's good practice to regularly sync your fork with the upstream repository. To do this, you'll need to use git on the command line. github

Here we will assume you will be working on a personal computer, like a laptop, and later installing changes you make on your remote servers.

Clone your repo and set the upstream on your computer.

Once setup, you can sync with fedwiki upstream. github

See More About Upstream Merge

You can stop if there are no changes. Otherwise, if the merge is successful, push the update to your own repo.

And install the new version on your servers.

Once you have customized a wiki to your liking with plugins that meet your needs you will want to share that configuration with others.

Before you get too far along this path be sure that you are using a recent version of npm.

You can share your github repo with others who install it instead of the normal npm wiki package. Npm offers a shorthand for this common case they can use.

With only a little more work you can publish your wiki configuration to npm and leave github out of the picture.

You will need an npm account which we will refer to as <npm-you>. Consult npm documentation to understand what they expect of users.

Edit the package.json file of your wiki-node configuration to include your name as a public scoped name.

Your use of github account for keeping your stuff in order and use your npm account for sharing it with others. When you add the @-scope to your package.json you are saying you intend to share with npm. Npm is smart enough to transition your users from github to npm for your sharing.

Caution: One can refer to your github account in their package.json. This only works successfully if you check built javascript into github. Our convention is to save coffeescript files in github and the generated javascript files in npm.

You say

Your users say

Here we are using an npm scoped name for the wiki server configuration. This will work correctly so long as a small package.json adjustment is included. issue

We will eventually offer the same flexibility for the plugin packages themselves but this requires some improvement of the wiki server's plugin location logic. issue

You may run afoul of npm's version numbering restrictions. It requires that each version published has a higher number. If would be easy for you to increment ahead of wiki's upstream version numbers.

You can solve this problem by using the next available version but declaring your version to be a beta version anticipating that release.

Then tag your publication accordingly.

Your users say