JINGO

A simple git based wiki engine written for Node.js.

The aim of this wiki engine is to provide a very easy way to create a centralized documentation area for people used to working with git and markdown. It should fit well into a development team without the need to learn or install ad-hoc servers or applications. Jingo is very much inspired by the github wiki system (gollum), but 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 a reason.

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

Features

No database: uses a git repository as the document archive
No user management: authentication provided via with Google logins or simple login
Markdown for everything, github flavored
Uses Codemirror or Markitup as the markup editor, with a nice (ajax) preview (features key in the config file)
Provides a "distraction free", almost full screen mode
Inspired by the well known github Gollum wiki
Show differences between document revisions
Search through the content and the page names
Layout accepts custom sidebar and footer
Gravatar support
Can include IFRAMEs in the document (es: embed a Google Drive document)
Can use custom CSS and JavaScript scripts
White list for authorization on page reading and writing
Detects unwritten pages (will appear in red)
Automatically push to a remote

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

Installation

npm install jingo or download the whole thing and run "npm install"

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. The config file contains all the available configuration keys. Be sure to provide a valid server hostname (like wiki.mycompany.com) for Google Auth to be able to get back to you.

If you define a remote to push to, then jingo will automatically issue a push to that remote every pushInterval seconds. You can also specify a branch using the syntax "remotename branchnama". If you don't specify a branch, that will be 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 (using forever -w is highly recommended, though)

Before running jingo you need to initialise its git repository somewhere (git init is enough).

If you define a remote to push to, be sure that the user who'll push has the right to do so.

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 two authentication methodologies: Google logins (OAuth2) or a simple, locally verified username/password credentials match (called "alone"). If you use the alone method, you can have only one user accessing the wiki (thus the name).

The Google 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 and put those informations in the configuration file. Follow these instructions:

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

The alone method uses a username, a 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 both authentication options at the same time. The alone is disabled by default.

The authorization section of the config file has two keys: anonRead and validMatches. If the anonRead is true, then anyone 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.

The authentication is mandatory to edit pages from the web interface, but jingo works on a git repository; that means that you could skip the authentication altogether and edit pages with your editor and push to the remote that jingo is serving.

Common problems

Sometimes upgrading your version of node.js could break the iconv module. Try updating it with npm install iconv.

Known limitations

The authentication is mandatory (no anonymous writing allowed). See also issue #4
The repository is "flat" (no directories or namespaces)
Authorization is only based on a regexp'ed white list with matches on the user email address
There is one authorization level only (no "administrators" and "editors")
At the moment there is no "restore previous revision", just a revision browser
No scheduled pull or fetch from the remote is provided (because handling conflicts would be a bit too... interesting)

Please note that at the moment it is quite "risky" to have someone else, other than jingo itself, have write access to the remote jingo is pushing to. The push operation is supposed to always be successfull and there is no pull or fetch. You can of course manage to handle pull requests yourself.

Customization

You can customize jingo in four different ways:

add a left sidebar to every page: just add a file named _sidebar.md containing the markdown you want to display to the repository. You can edit or create the sidebar from jingo itself, visiting /wiki/_sidebar (note that the title of the page in this case is useless)
add a footer to every page: the page you need to create is "_footer.md" and the same rules for the sidebar apply
add a custom CSS file, included in every page as the last file. The name of the file must be _style.css and must reside in the repository. It is not possible to edit the file from jingo itself
add a custom JavaScript file, included in every page as the last JavaScript file. The name of the file must be _script.js and must reside in the repository. It is not possible to edit the file from jingo itself

All those files are cached (thus, not re-read for every page load, but kept in memory). This means that for every modification in _style.css and _script.js you need to restart the server (sorry, working on that). This is not true for the footer and the sidebar but ONLY IF you edit those pages from jingo (which in that case will clear the cache by itself).

jingo uses twitter Bootstrap and jQuery as its front-end components.

Editing

To link to another Jingo wiki page, use the Jingo Page Link Tag.

[[Jingo Works]]

The above tag will create a link to the corresponding page file named jingo-works.md. The conversion is as follows:

Replace any spaces (U+0020) with dashes (U+002D)
Replace any slashes (U+002F) with dashes (U+002D)

If you'd like the link text to be something that doesn't map directly to the page name, you can specify the actual page name after a pipe:

[[How Jingo works|Jingo Works]]

The above tag will link to jingo-works.md using "How Jingo Works" as the link text.

wpc009/jingo