Online collaborative markdown with math. Main features:
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.
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)
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:
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:
The main deployment currently runs on Heroku. See deployment/ subdirectory for details. I'm interested at going back to static hosting.
However you run it, you can open the same document ids (
doc=...) and real-time collaboration will work!
Quick ways to run:
Deploy on Heroku:
heroku create my-mathdown --remote heroku-my-mathdown git push heroku-my-mathdown gh-pages:master
some other ways to deploy on Heroku might not work due to my use of submodules (?)
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.html in 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:
Other things called "mathdown":
I should really talk to these folk whether it's OK that I'm using the name and the domain...