morgul / tome Goto Github PK

2.0 6.0 1.0 909 KB

A modern wiki with minimal external dependencies.

JavaScript 73.04% HTML 21.99% CSS 4.97%

tome's Introduction

DEPRECATED

This version of the project is considered depricated (and no longer being developed). Development has moved to here:

(That version has not had it's first release yet, so it's still valid to use this version, just please understand that it will not be updated/maintained.)

Tome Wiki

Tome is an attempt to create a wiki that is slim, trivial to deploy, looks clean, and is written as a modern web application. It's core features are:

Built in search
Revision history
Ability to diff page revisions
3-way merge resolution
Syntax-highlighted editor
Markdown syntax
Mobile support
Persona-backed user system
Blog style Comments on pages
Logo/Name/CSS customization
(New) Anchor Tag support

Current Status

Right now I'm closing in on my first preview release.

The following items are left:

3-way merge resolution

Installing

To get going with tome, you will need to either make a new node project, or at the very least, make a new directory. Tome is installed as an npm package, and requires a couple of lines of code from you to get running. (This is so that we can allow you to easily customize it, without needing to edit any of the core files.)

Assuming you've made a directory called example-wiki, you should do the following:

$ cd example-wiki
$ npm install tome

This will install the latest version of Tome into the example-wiki directory.

Setup

Now, the bare minimum you need is a file to launch the Tome wiki:

var tome = require('tome');

tome.listen();

That's it! Now, you should have a tome instance running on http://localhost:4000.

Customizing

In order to customize Tome, you will want to add a configuration file. I recommend copying the config.example.js file from the main repository, and modifying that. It has some nice explanations about what the configuration options do, and how to use them. (Still, some of the information is replicated here, to make it easier to find.)

Serving static files

Tome uses connect as it's middleware. This means that it should be trivial for you to use connect to serve static files. ( Note: Tome uses connect 0.2.X at the moment. ) If you want to do so, you can do the following:

var connect = require('connect');
var tome = require('tome');

// Serve our local static directory
tome.app.use(connect.static('static'));

// Start the server
tome.listen();

This will serve the contents of the static directory at the root of your website.

Custom Logo

You can customize the logo used for Tome. Simple set the logo config option to any valid url, and it will load that logo in the navbar, as well as use it for the favicon. ( Note: The logo will be forced to 50px high. If you want this to look good on high dpi screens, I recommend using a logo that is 100px high. Width is less important, but if you make it too wide, it could cause issues with flow in the navbar. )

Custom CSS

While Tome doesn't support custom CSS directly, it does support an 'extra template' that is included at the bottom of the <body> tag in the index page. This means that in you config file, you can do:

...

extraTemplate: "/partials/custom_css.html"

...

Then, you will have to serve some static directory, and inside of it place a partials folder with a custom_css.html file inside of it. Here is an example of such a template:

<link href="http://fonts.googleapis.com/css?family=Electrolize" rel="stylesheet" type="text/css">
<link href="/css/dice.css" rel="stylesheet">
<link href="/css/powers.css" rel="stylesheet">

Testing

TBD.

tome's People

Contributors

Stargazers

Watchers

Forkers

erkattak

tome's Issues

Request flooding on live-preview of page with links

While editing, every character causes a refresh of the 'live preview', which causes a HEAD against /api/page/* to see if the page exists. This could be very expensive.

Diff button on Recent diffs against the wrong revision

The diff buttons on the Recent page diff against the previous (in the list), not the previous from the same page.

Add a comment system

All collaborative oriented wikis have a comment system, however, I'm unsure how I would like this to work.

One of the simpler options would be to have it work like a comment system on a blog. Comments could be their own page (like edit is), and formatted using Boostrap Media objects.

That's just one idea, though.

Last item in filtered history doesn't have `prevRev` set correctly.

When you limit the size of the revision history for either Recent Activity, or page History, the last item doesn't get prevRev set correctly. This is because we're limiting too early; we need to do our operations over a larger dataset.

Add ability to specify Bootswatch theme

We need to be able to specify our Bootswatch theme in the config file, this way it's easy to change.

Add the ability to link to headings

Need to ability to link to headings in pages, for example:

[Some Section](pages/foo/bar/baz#some-section)

This is a bit of an issue because angular used hash routing for it's router.

Add a 'lock' icon to pages that are marked private

This icon should be added to the page header, at the very least. Additionally, it could be nice to mark wiki links with the lock icon as well.

Handle Collaborative Merge scenario

If I'm editing a document and a change is made to that document while I'm still editing it, I will overwrite those changes without knowing about them.

Instead, we need to detect this scenario, and offer a 3-way-merge.

The proposal is as follows:

When PUTing to a wiki url, send our current revision as prevRevID.
Check to see if the prevRevID matches the current revision (before saving)
- If it matches, save.
- If it doesn't match, respond with a 409 and return the new revision.

Note: It has been suggested that we use E-Tags for this. However, there's a significant added complication to this, as express already uses eTags itself. Add to this the fact that there's some debate about the validity of eTags, I'd rather do the more straightforward solution.

The 'private' options is not respect on new pages

When you select 'Private' on a page that you are creating for the first time, it is not saved.

Work around: Create the page, save it, and then edit it again to mark it as private.

'Limit' parameter gives random results on History and Recent Activity

On both the history page, and recent activity, when you select a limit, you get a random list of that many history items; not the last X items, as one would expect.

This is because when doing the query in thinky, the orderBy isn't working correctly. I have an outstanding issue in thinky asking how to do this:

neumino/thinky#103

Worse case scenario, we need to put a date on Revision as well as Commit.

Human verification question can be brute forced

Technically, the Human verification questions could be brute forced because I allow you to attempt to hit the registration endpoint as many times as you want.

The way I propose to fix this is to generate a nonce for the registration attempt, and can't be reused. This means they'd have to keep getting a new nonce, which would also give them a new human verification question, increasing the difficulty of brute-forcing the answers.

This isn't impenetrable by any means; it's just raising the cost of attempting to brute force. We can also enforce rate-limiting on the registration endpoint, as normal users should only be hitting it ~ once ever second or two.

Can't turn off registration

You can't turn off registration; the option appears to be ignored.

Add "private" pages

Add the ability to flag a page as "private". These pages will only be visible for people who are logged in. Everyone else should get a message that says, "We're sorry, but this page had been marked private. Please log in to view."

Additionally, we can set a list of users who are allowed to view the page. None specified means anyone logged in.

Add ability to revert to a previous revision

This involves simply updating slug to point to a past revision. However, the proposal in #9 would break this, so we need to be careful.

Registration page Persona pop-up is blocked

When you complete the registration page, the Persona popup is blocked (at least on Chrome). It isn't blocked when you attempt to do a sign-in, however.

I have no idea what's going on here; I may be handling registration incorrectly. Perhaps once registration completes, I need to redirrect to the main page, and then attempt the login, as if they had clicked the button? Or should I send them to a success page, and tell them, "You may now sign in."?

Getting recent activity is slow

Much like #9, getting the list of latest revisions is slow. We're currently doing this primarily using lodash:

https://github.com/Morgul/tome/blob/master/server/database.js#L286-L300

This is impossibly slow and will only get slower.

@whitelynx I could also use some ideas on how to speed this up.

Upgrade to AngularJS 1.3.X

This mostly works; the only thing that breaks is code mirror, and it breaks in a weird way.

Switch to local authentication

Using a login like Google+, or Persona simply makes our ability to control registration FAR more difficult than it needs to be. Instead, we can do our own registration/login, and keep complete control over it.

Since the size of this is intended to be rather small, I believe basic protections, like PBKDF2 will be good enough for most users.

Getting comments is slow.

Currently, here is how we get the comments:

https://github.com/Morgul/tome/blob/master/server/database.js#L391-L406

Ignoring line #399 (which is required by #2), it's still pretty slow. This is because we have to map over all the comments, and then do a second query to get the slug for a given comment. We need a much better way to get slug from page.

What I'm wondering is, might it be better to have slug point to a page, and then get the latest revision of that page by doing:

return db.Revision.filter({ page_id: page }).orderBy(r.row('commit')('committed')).limit(1).run();

This assumes #2 is fixed, but should be a pretty fast lookup. Especially if I index page_id.

@whitelynx, what do you think?

Make Tome installable through npm

If tome is installable through npm, we need to make it smart about a couple of things.

Detect config.js in the root project, not in the root of the tome package.
Expose a listen function from server.js

Optional:

Support serving a static folder, which will override other static pages.