joelotter/kajero

Interactive JavaScript notebooks with clever graphing

Kajero

Interactive JavaScript notebooks with clever graphing.

You can view a sample notebook here.

Features

• It's just Markdown - a Kajero notebook is just a Markdown document with a script attached.
• Every notebook is fully editable in the browser, and can be saved as Markdown or HTML.
• Notebooks can also be published as Gists, generating a unique URL for your notebook.
• JavaScript code blocks can be executed. They're treated as functions, with their return value visualised. Kajero can visualise arrays and objects, similar to the Chrome object inspector.
  • Code blocks can be set to run automatically when the notebook loads. They can also be set to hidden, so that only the result is visible.
• Data sources can be defined. These will be automatically fetched when the notebook is loaded, and made available for use inside code blocks.
• Includes Reshaper, for automatic reshaping of structured data.
• Includes D3, NVD3 and Jutsu, a very simple graphing library which uses Reshaper to transform arbitrary data into a form that can be graphed.

Related projects

• Reshaper - reshape data to match a schema
• Smolder - a library wrapper that attempts to reshape data going into your functions, using Reshaper
• Jutsu - a simple graphing library, with support for Smolder

Contributing

Issues and Pull Requests are both extremely welcome!

Command-line tools

Kajero includes a couple of simple command-line tools for users who don't want to use the inline editor to create their notebooks.

Installation

npm install -g kajero, or clone this repository.

You can build the JS library by running npm install, followed by gulp. For a production build, NODE_ENV=production gulp.

Commands

You can generate new notebooks directly from Markdown files without using the web editor.

• kajero html [file.md]

Will output generated HTML of a new notebook. You can pipe it to a file like this:

kajero html [file.md] > output.html

• kajero publish [file.md]

Will publish your notebook as a gist, and return a unique URL to your new notebook. You don't need to build the JS library for these scripts to work.

Running tests

Run the unit tests with npm test.

For coverage reporting, run with npm run test-cov. Note that the coverage percentages may not be exactly correct - this is because Istanbul runs over the compiled ES5 code, rather than the ES6 source.

kajero's Issues

A way to make the notebook "readonly"

I've noticed that once you publish the notebook its still has the editor built in. Would be nice if the notebook could be made readonly where you could execute the code on the page, but not edit the contents. I realize that the edits don't persist to other users, but I'd hate to have my PM try to use this :D

Support TeX with KaTeX

KaTeX is a great library for mathematical typesetting.

I had implemented support in commit 3b54131, but had to remove it in fe67c67 as there are issues that need to be resolved:

• Parsing the Markdown with embedded TeX is broken due to escaping in Markdown-It. waylonflinn/markdown-it-katex#5
• There are some bugs with the parsing in general, though this PR looks promising: waylonflinn/markdown-it-katex#4

Editor not keeping escaped characters

First off, AMAZING project! 👍

While playing around with the editor today I noticed that if I typed a letter that would need escaping, such as '[' then it would display in the editor just fine. However, when it would show me the markdown it would create, it removed the backslashes thus unescaping the character and breaking the page.

Example

This code is what my markdown file contains.

1. **start** → _program_ EOF
2. **program** → _block_ ENDL
3. **block** → LBRACE \[ _stmts_ \] RBRACE

After generating the html page, I get the following while in edit mode:

Finally, if I select save and view as markdown, I get the same as what I saw in editor mode.

Expected

I would have expected the square brackets to remain escaped like the original source was, but it seems to remove the backslashes, which causes the page to break if I attempt to regenerate the page.

Editing is broken

I used a sample kajero notebook but I couldn't get the code editing to work. When I pressed O, it typed O in the editor.

When trying to go to the end of the document by pressing G, it just typed G. Don't even ask what happened when I tried to macro things.

As it stands I can't use this product. Please fix vim editing or I want a refund.

Resolve returned Promises in code blocks

Support 'moustache' templates in text blocks

One suggestion from Hacker News was inline substitution of data in text blocks. A text block would be able to have the following Markdown:

The results show that there were {{this.numBadgers}} badgers, which implies...

This would allow values from probably either the data or this object to be included in text. I'll need to think about what this will look like when the value isn't defined though, due to the data not being fetched yet or the code block not having been run.

No font-awesome in Safari on mobile

Allow loading data from inside HTML document

It might be useful if data could be embedded into the same document - again in <script> tags - and the ID of those tags used as the datasource 'URL'.

Execution data not being removed when block deleted?

Investigate this!

Change nvd3 dependency when v1.8.3 is released

Currently depending on the master branch, which is a bad idea.

The PR I need is this one:
novus/nvd3#1389

CSS bugs in graph creator

Some margins and padding seem to be off on the homepage's graph creator - probably because it's no longer running in quirks mode.

CLI tool

Should be able to:

• Turn Markdown into HTML
• Publish Markdown as a Gist and return URL

Update Istanbul when possible

Istanbul currently has issues with ES6.

gotwarlost/istanbul#582

When fetching from Gist, data sources not fetched

I think this is because it does the componentDidMount before the initial fetch has finished. Perhaps make that fetch synchronous?

Add support for executing code in other languages

Coffescript is the obvious candidate for the first next supported languages, because of it's golden rule "it's just javascript". But a multitude of other languages that compile to javascript or run on a browser VM would be nice. Of course, there is the risk of bloat.

Purescript, APL, scala, I personally find these much more suited for processing batches of tabular data.

Could you briefely outline the procedure for adding support for other languages? Other forks could be maitained with focus on other languages.

Add error handling to eval

gulp build fails - need to install codemirror and nvd3 first

I cloned the code, ran npm install, set NODE_ENV=production, and gulp as the readme says, Gulp complained about codemirror and nvd3 missing. So, I ran npm install codemirror, npm install nvd3, and then gulp worked.

Should you update the readme to include those steps, or add those dependencies to your npm configuration?

Note: I am on Windows 10, and using Git Bash for a console (if it matters)

Better code editing

Things like auto-indentation and proper tabs would be good.

Setup handling for first edit

First edit should

• Enable footer
• Set author to placeholder text?
• Change 'forked from'

Date should be changed on every edit.

Graphs disappearing

The graphs disappear in the editor when a new block is added above, or the graph is moved up or down.

Not critical as the blocks can just be re-run - slightly annoying, though.

Open source licenses

Remember to include fonts.

Run buttons disappear on Safari mobile

[Suggestion] Generate pdf out of markdown

This is merely a suggestion for an already cool project. Having the ability to generate a pdf version of the notebook, to view the content in offline mode or where a browser is not indicated, for example kindle/tablets.
Removes the dynamic and graph functionality, but libraries like ConTeXt and pandoc could be helpful in this.

Sort out indentation in embedded Markdown

Discussion: suggestions to look better

When I click on text block text area appears instead of rendered text. I think it's not very nice.

1. Text area is smaller than real document. It's has a fixed height. I have tried to remove it and result looks better.
2. It would be nice when font-sizes in view and edit mode will be same.
3. Left panel with lines should be moved more left, because in current time it creates margin that doesn't exists in edit mode
4. Finally, I think that after clicking on pencil all content should come into edit mode. And instead we can shadow all text in other blocks to show what user is editing now. It's something like focus mode in iA writer (https://vimeo.com/138858474 - look at 55 second If you don't know how focus mode works)

P.S: Kajero is great!

Clean up CSS

It's all in one big Sass file! Needs reorganised a bit.

Inline HTML is not rendered

Way to embed in other projects

Kajero is probably the best content editor based on Markdown that I've seen to date. It would be really nice to be able to embed it as an editor/viewer in other projects. As an example we have an internal (and honestly hacked together) knowledge base system built on Markdown today. If I could replace my crappy editor with Kajero everyone's lives would be easier ;)

Nice work, hope your Master's Project is as well accepted internally as it is externally.

Fetch doesn't work in Safari

Use XMLHttpRequest, or work out why Babel isn't transpiling it.

Scrollbars

Should be hidden unless totally necessary

Consider wiping all execution data on change

May not be necessary. Ask about in evaluation?

Consider removing Reselect

If it's not being used, it's just causing unnecessary bloat.

Add meta tags

• Title
• Facebook tags
• Twitter tags

Minify/Uglify

Try to retain source maps if possible.

Consider using Function() instead of eval

Investigate differences RE scoping etc

Code block options

Should allow options for code blocks like:

• Autorun
• Hidden

How do you start the server

I installed the software with the 'npm' command. How do I start a new notebook?

Tidy up Markdown parsing code

Seriously

Edit buttons overlap text in edit mode in Safari

Tooltips on all buttons

TESTS

Allow usage of third-party libraries

Hello @JoelOtter How can use smth like lodash or Rxjs? Also how about show result of async operators, for example:

setTimeout(() => somePrintFn(10), 4000);

code using backticks fails

Writing code with backticks like this to produce this output causes a JavaScript error when then generated HTML page is accessed in a browser:

bundle.js:formatted:68268Uncaught TypeError: Cannot read property 'get' of undefined

This is because the codeBlocks array on line 54 of src/js/markdown/js is an empty array.

Graph creator UI

This is the big one...

Chrome data saver causes icons not to show

See picture below. I am running Windows 10 64-bit.

Discussion: What would it take to turn this in to a front-end for a JSON API?

Let's count out user permissions for a second, as I'm sure the standard practices are enough (stop me if I'm wrong).

Assuming a simple REST API that works with JSON objects with Markdown content areas, how difficult would it be to use Kajero to view the rendered content, edit in-browser, then submit the change to the API?

Please explain as though you're talking to someone with only rudimentary JS knowledge. :)

Love the design, and would like to use this for a personal project.

No font-awesome in Edge

Shows a cross-origin error

Reorganise dependencies before publish

If I'm going to publish to NPM, I need to reorganise the dependencies - figure out what's a dev dependency and what's a real dependency, wrt the (optional) CLI tool. It may be that they're all dependencies.

Should be text-select cursor over Gist URL field

Currently pointer.

Add optional footer