Collaborative markdown with math. Main features:
- Markdown is styled in-place, no source/preview separation.
- Edits are synced in real time.
- Access control is simply by sharing the secret URL. No sign up needed to collaborate.
- LaTeX-syntax formulas rendered in-place when cursor is outside formula.
Alpha quality – will eat your math, burn your bookmarks & expose your secrets. I mean it. See for example #85 — saving would sometimes be silently broken, for half a year! I'm working to make it more robust (and tested) but for now, be careful.
CodeMirror is also MIT.
MathJax is under Apache License 2.0.
My CodeMirror-MathJax glue is also MIT.
The collaborative editor Firepad is MIT. It calls firebase javascipt API.
Firebase is a proprietary service; their client-side javascipt API firebase.js is also proprietary, though apparently fine to distribute in practice — (#4). [firbease.js has been accidentally MIT-licensed for a time but I've upgraded to newer versions so this doesn't apply.]
I'm not including firebase.js directly but using it as a git submodule.
Document hosting and privacy(?) on Firebase
The downside is users can't really control their data. Running a "self-hosted" copy of the site still leaves all data in the hands of Firebase. See #4 for more discussion.
The upside is all forks interoperate; you can change the design or tweak the editor and still access same documents. E.g. https://mathdown.net/index.html?doc=demo and http://rhythmus.be/mathdown/index.html?doc=demo look different but access the same doc -- and real-time collaboration between them works!
I'm so far on the free Firebase plan - 100 devices (not sure if 1:1 with users), 1GB Data Storage (used < 100MB). => Will need 49USD/mo plan as soon as I get non-negligible usage. https://mathdown.firebaseio.com/?page=Analytics (only visible to me)
Deletion is impossible
The current Firebase security rules make document history append-only. That's a nice safety feature but it means that once a document's URL gets out, it's full history is forever accessible to the the world. This must change eventually (#92).
Basically whatever CodeMirror supports: IE8+ and about everything else. But mobile is currently almost unusable (#81).
The only cookies I'm aware of:
GEARsession cookie set by OpenShift hosting (I presume for server stickiness, which I don't actually need).
mjx.menucookie set for a year(?) if you manually change MathJax settings.
I'm not sure Firebase never sets cookies. Things will change once I implement login (#50).
After checking out, run this to materialize client-side dependencies:
git submodule update --init --recursive
--remote to upgrade to newest versions of all submodules (need to commit afterwards if anything changed). Known constraints on updating all deps:
* firepad only includes pre-built dist/firepad.js in tagged versions (after every release they strip it back). * [CodeMirror-MathJax currently doesn't support MathJax 2.5](https://github.com/cben/CodeMirror-MathJax/issues/33).
(I'm directly working in
gh-pages branch without a
master branch. GH Pages automatically resolves https://... submodules. It's no longer the primary hosting but it's still useful to test the static version works.)
To install server-side dependencies (and devDependencies) listed in
(But when deploying to RHcloud or Heroku, npm install might run in
--production mode and devDependencies won't be available.)
To see whether any updates are needed/possible, run
npm outdated. To update run:
npm update --save npm shrinkwrap Then commit the new `package.json` and `npm-shrinkwrap.json`.
TODO: find way to use same node.js version in dev and prod?
test/browser-on-saucelabs.spec.coffee runs tests on several browsers using free browser testing courtesy of Sause Labs.
There are pathetically few tests.
To run the tests:
npm install # once npm test
To run only some tests and/or browsers, use:
./node_modules/.bin/mocha --grep firefox
The test runs automatically on any commit and pull request. I've tried several free services for this, and currently prefer Travis:
- Travis - works, open source code. Controlled by
- Wercker - works. Controlled by
- Drone - Docker-based, open source rewrite in progress. Alas, always timed out during test. Test config on the web.
- Shippable - builds history only accessible by me? Bad, I want public. Controlled by
- Codeship - same, dashboard is private. Test config on the web.
Where it's deployed and how to run your fork
The main deployment runs on https://mathdown-cben.rhcloud.com/ (Openshift hosting operated by RedHat), and mathdown.net points to it. The dynamic server has also been tested on Heroku. See deployment/ subdirectory for details.
However you run it, you can open the same document ids (
doc=...) and real-time collaboration will work!
Quick ways to run:
![Launch on OpenShift](https://launch-shifter.rhcloud.com/launch/LAUNCH ON.svg) — make sure to replace with your fork & branch as needed. Don't enable scaling without reading "Creating an app" in deployment/README.md. Grab a tea - takes up to 10 minutes. (Remember it'll not auto-update, it'll be up to you to git push newer versions...)
Deploy on Heroku:
heroku create my-mathdown --remote heroku-my-mathdown git push heroku-my-mathdown gh-pages:master
Run local server (
npm install # once env PORT=8001 npm start # Prints URL you can click
(you can choose any port of course. Ctrl+C when done.)
This app mostly works as pure static pages, and I intend to keep it this way.
From a checkout, just open
index.htmlin your browser.
Github Pages serves the gh-pages branch at https://cben.github.io/mathdown.
For other branches/commits, there is no trivial solution - rawgit.com would be great but doesn't currently support submodules.
The easiest way to run (and share) uncommitted modifications is probably Cloud 9. TODO: test, details.
The only benefits the dynamic server is going to bring (not implemented yet) will be:
- Including the document text in the HTTP response for search engines (#7).
Other things called "mathdown":
- https://github.com/mayoff/Mathdown/tree/mathjax — Markdown.pl hacked for MathJax pass-through
- https://github.com/keishi/kernlog/blob/master/markdown/extensions/mathdown.py — math in python-markdown, part of "Yet another blog for google app engine"
- http://kwkbtr.info/log/201010050320 — a way to combine Showdown + Mathjax
- https://gitlab.com/padawanphysicist/tw5-mathdown/tree/master — Math (via TeXZilla) + Markdown-it in TiddlyWiki5
- https://github.com/domluna/mathdown — Watches markdown files, converts to HTML with KateX.
- https://github.com/jirkalewandowski/mathdown — heuristically recognizes LaTeX formulas in text with no delimiters.
I should really talk to these folk whether it's OK that I'm using the name and the domain...