JINGO

A git based wiki engine written for node.js, with a decent design, a search capability and a good typography.

<!-- toc -->

Table of contents

• Introduction
• Features
• Installation
• Authentication and Authorization
• Known limitations
• Customization
• Editing
• Configuration options reference

<!-- toc stop -->

Introduction

The aim of this wiki engine is to provide an easy way to create a centralized documentation area for people used to work with git and markdown. It should fit well into a development team without the burden to have to learn a complex and usually overkill application.

Jingo is very much inspired by (and format-compatible with) the github own wiki system Gollum, but it tries to be more a stand-alone and complete system than Gollum is.

Think of jingo as "the github wiki, without github but with more features". "Jingo" means "Jingo is not Gollum" for more than one reason.

There is a demo server running at http://jingo.cica.li:6067/wiki/home

Features

• No database: Jingo uses a git repository as the document archive
• Markdown for everything, github flavored
• Jingo uses Codemirror or Markitup as the markup editor, with a nice (ajax) preview (see the features key in the config file)
• It provides a "distraction free", almost full screen editing mode
• Compatible with a wiki created with the Gollum wiki
• Revision history for all the pages (with restore)
• Show differences between document revisions
• Paginated list of all the pages, with a quick way to find changes between revisions
• Search through the content and the page names
• Page layout accepts custom sidebar and footer
• Gravatar support
• Can include IFRAMEs in the document (es: embed a Google Drive document)
• Generate Table of Contents for pages
• Can use custom CSS and JavaScript scripts
• White list for authorization on page reading and writing
• Detects unwritten pages (which will appear in red)
• Automatically push to a remote (optionally)
• Mobile friendly (based on Bootstrap 3.x)
• Quite configurable, but also works out of the box
• Works well behind a proxy (i.e.: the wiki can be "mounted" as a directory in another website)
• Pages can be embedded into another site
• Authentication via Google, Github, LDAP and local name/password

For code syntax highlighting, Jingo uses the node-syntaxhighlighter module. For the list of supported languages, please refer to this page.

Installation

npm install -g jingo or download/clone the whole thing and run npm install.

Note: if you already have Jingo installed, please also run npm prune (some modules can be stale and need to be removed).

Jingo needs a config file and to create a sample config file, just run jingo -s, redirect the output on a file and then edit it (jingo -s > config.yaml). The config file contains all the available configuration options. Be sure to provide a valid server hostname (like wiki.mycompany.com) if you use a 3rd party provider for authentication (like Google or GitHub). It is needed for them to be able to get back to you.

This document contains also the reference for all the possible options.

If you define a remote to push to, then Jingo will automatically issue a push to that remote every pushInterval seconds. To declare a remote for Jingo to use, you'll need to identify the name of your local remote. The following example shows how a local remote is typically defined:

git remote add origin https://github.com/joeuser/jingorepo.git'

Based on that example, you would update config.yaml with the remote name "origin" as follows:

remote: "origin"

You can also use the git remote command to get the name of your remote.

You can also specify a branch using the syntax "remotename branchname". If you don't specify a branch, Jingo will use master. Please note that before the push, a pull will also be issued (at the moment Jingo will not try to resolve conflicts, though).

The basic command to run the wiki will then be

jingo -c /path/to/config.yaml

Before running jingo you need to initialise its git repository somewhere (git init is enough). Additionally the user running the process needs to have git config --global user.name and git config --global user.email configured. Else your document's repo will get scrambled and you have to reinitialize it again (rm -rf .git && git init).

If you define a remote to push to, be sure that the user who'll push has the right to do so. This means you have to configure the remote via the git:// URI that uses ssh authentication to push and have created and published the process user's ssh public key to the remote.

If your documents reside in subdirectory of your repository, you need to specify its name using the docSubdir configuration option. The repository path must be an absolute path pointing to the root of the repository.

If you want your wiki server to only listen to your localhost, set the configuration key localOnly to true.

Authentication and Authorization

You can enable the following strategies: Google logins (OAuth2), GitHub logins (OAuth2), ldap logins or a simple, locally verified username/password credentials match (called "local").

The Google Login and the GitHub login uses OAuth 2 and that means that on a fresh installation you need to get a client id and a client secret from Google or GitHub and put those informations in the configuration file.

For Google, follow these instructions (you need to be logged in in Google):

• Open the Google developer console
• Create a new project (you can leave the Project id as it is). This will take a little while
• Open the Consent screen page and fill in the details (particularly, the product name)
• Now open APIs & auth => Credentials and click on Create new client id
• Here you need to specify the base URL of your jingo installation. Google will fill in automatically the other field with a /oauth2callback URL, which is fine
• Now you need to copy the Client ID and Client secret in your jingo config file in the proper places

For GitHub, follow these instructions (you need to be logged in in GitHub):

• Register a new application here
• Enter whatever Application name you want
• Enter your installation URL (localhost is OK, for example "http://localhost:6767/")
• Enter <your installation URL>/auth/github/callback as the Authorization callback URL
• Press the Register application button
• In the following page, on the top right corner, take note of the values for Client ID and Client Secret
• Now you need to copy the Client ID and Client secret in your jingo config file in the proper places

Warning In certain cases the Github authentication system return an empty email and Jingo is not happy about this. To avoid problems, when using Github set the authorization.emptyEmailMatches configuration option to true.

The ldap method uses url as the ldap server url, and optionally a bindDn and bindCredentials if needed. The searchBase and searchFilter are required for searching in the tree. In the configuration searchAttributes is also available. Since we want to install the (binary) support to LDAP only when needed, please manually npm install passport-ldapauth to use the LDAP support.

The local method uses an array of username, passwordHash and optionally an email. The password is hashed using a non salted SHA-1 algorithm, which makes this method not the safest in the world but at least you don't have a clear text password in the config file. To generate the hash, use the --hash-string program option: once you get the hash, copy it in the config file.

You can enable all the authentications options at the same time. The local is disabled by default.

The authorization section of the config file has three keys: anonRead, validMatches and emptyEmailMatches.

If anonRead is true, then anyone who can access the wiki can read anything. If anonRead is false you need to authenticate also for reading and then the email of the user must match at least one of the regular expressions provided via validMatches, which is a comma separated list. There is no "anonWrite", though. To edit a page the user must be authenticated.

emptyEmailMatches allows access when remote authentication providers do not provide an email address as part of user data. It defaults to false, but will usually need to be set to true for GitHub authentication (GitHub only returns email addresses that have been made public on users' GitHub accounts).

The authentication is mandatory to edit pages