Interactive documenation

[viebel]

Mathjs really rocks!

It would be great to have interactive documentation for math.js.

It's super easy to create interactive documenation with the klipse plugin.

As a POC, I've written a short interactive article that demonstrate the power of math.js evaluator:
http://read.klipse.tech/symbolic-calculation-in-javacript/

Disclaimer: I'm the author of the klipse plugin.

[josdejong]

Thanks. Nice idea to make the code examples in the documentation interactive.

One solution is to embed an editor, like your klipse plugin or what I did with Math Notepad (see these docs, you can edit all code).

Another solution is to put a link on top or at the bottom which copies the code to say http://jsbin.com (or a klipse web service) so the user can edit and save everything himself (like the "click here to fiddle around" on the front page of http://mathjs.org/). I may like this approach more since it gives the user more control and freedom to play around. What do you think?

[FSMaxB]

I think a link to something like jsbin should be in addition to the inline editor, because it pulls people out of context.

[viebel]

I agree with @FSMaxB
The best reading experience to me is interactive and without having to leave the page.

Would you like to try integrating klipse on your doc pages?

[josdejong]

Thanks Max, that's a good point.

Yes Yehonathan, sounds good to give this a try integrating klipse in the website of math.js. I haven't thought out in details what would be needed there. There is a script which generates the html docs from markdown, I suppose we have to add some code there to embed klipse where applicable (maybe via an annotation in the markdown code before or around the relevant code blocks, or maybe we can simply match block fences tagged with js). Would you like to give this a try @viebel and see whether you can get klipse integrated?

[viebel]

What is the script that generates html? Is there a way to add a script tag to all the pages?

…

On Tue, Jan 3, 2017, 20:38 Jos de Jong ***@***.***> wrote: Thanks Max, that's a good point. Yes Yehonathan, sounds good to give this a try integrating klipse in the website of math.js. I haven't thought out in details what would be needed there. There is a script which generates the html docs from markdown, I suppose we have to add some code there to embed klipse where applicable (maybe via an annotation in the markdown code before or around the relevant code blocks, or maybe we can simply match block fences tagged with js). Would you like to give this a try @viebel <https://github.com/viebel> and see whether you can get klipse integrated? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#768 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA6VPrrvI6sWwle5hADiuEfHUMw_cLEIks5rOpWegaJpZM4LW_VH> .

[josdejong]

It's all in the gh-pages branch. There is a gulpfile with a couple of tasks. The most relevant part to get started is the 'docs' task, which does some preprocesses of the markdown docs:

https://github.com/josdejong/mathjs/blob/gh-pages/gulpfile.js#L102-L114

The actual generation of HTML from the markdown is done by Github Pages (which uses jekyll), when you push something new to gh-pages and the site is deployed.

[josdejong]

The readme in the root of gh-pages explains how to built the website locally:

https://github.com/josdejong/mathjs/blob/gh-pages/README.md

[viebel]

Here is a 1st draft #771

[viebel]

@josdejong did you have time to review #771 ?

[josdejong]

Not yet, will look at it asap (work, family, stuff, you know...), I expect to be able to check it out tomorrow night.

[viebel]

No hurry. Take your time...

…

On Thu, 5 Jan 2017 at 20:30 Jos de Jong ***@***.***> wrote: Not yet, will look at it asap (work, family, stuff, you know...), I expect to be able to check it out tomorrow night. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#768 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA6VPt_o3g1i4fZU_A2FbpQTy9p7zF0eks5rPTbZgaJpZM4LW_VH> .