A “try it out” box would be useful. I’ll have a think about how to best implement it. The markdowntutorial.com version would need to be changed to support the CommonMark JavaScript reference implementation. Perhaps a stripped down version of the commonmark.js dingus could be used (with only the preview tab, no HTML or AST tabs).
I’ve uploaded the basic Middleman site and moved the guides I’ve written so far across:
Website: http://chrisalley.github.io/commonmark-website/
Git Repo: https://github.com/chrisalley/commonmark-website
The lefthand guides navigation is defined in guides.yml with a corresponding Markdown file/folder structure in the guides directory.
The plan going forward:
- Add a README to the git repo with documentation for setting up Middleman and editing the site’s pages
- Combine the markdowntutorial.com guides with the new CommonMark guides
- Write the remaining guides (listed in the left hand guides menu)
- Investigate adding a “try it out” input box" for use within the guides
- Improve the site’s design
- Once the site is in reasonable state, use it for commonmark.org
If you’re okay with this plan @codinghorror I’ll continue.
1 Like
Any movement on this? Would like to host some live, interactive, easy “how-to” guides on the domain for sure.
Maybe help.commonmark.org cc: @jgm ?
A small amount of movement. See these links for the latest version:
Website: http://chrisalley.github.io/commonmark-website
Git Repo: https://github.com/chrisalley/commonmark-website
I have some spare time over the next few days, so I’ll prioritise completing the guides. I don’t think it will take too long to write them.
I like what you put together @chrisalley and maybe it is complementary to what @gjtorikian put together at http://markdowntutorial.com/ ?
I would like to see a little “try it here!” box in all sections of the docs / tutorial so people can experiment in their browser as they read about stuff. I feel so strongly about this that perhaps we can just superimpose a little overlay editor at the bottom of the guide – rather like this editor right here in Discourse. It should be constantly inviting people to give it a shot and see what happens. Experiment!
@codinghorror, can you provide a version of the discourse dual-pane editor that uses commonmark.js?
(By the way, here’s a feature request for the dual-pane editor. Sometimes I forget what I’m doing and try to edit the right-hand pane. It would be nice if the app detected that and flashed a message, beeped, or something.)
1 Like
In any case, before anything is taken live, we need to look at the tutorial carefully. For example, this is given as an example of a thematic break (i.e. horizontal rule):
A paragraph before the thematic break.
---
A paragraph after the thematic break.
but in CommonMark it’s a setext header followed by a paragraph. Putting everything in a dual-paned editor would help us check for errors like this.
1 Like
As I see it, there are three formats that I would want, as a consumer of commonmark:
- Quick reference/Cheat sheet : a printable guide with limited descriptions
- Advanced Guide : Gotchas, details, full explanations. Basically what’s at http://chrisalley.github.io/commonmark-website/guides/headers/setext-headers/
- One page intro/demo : Nearly instant recognition of capabilities and syntax
For the “one page intro”, I would consider The Polymer Code Explainer as a close approximation.
I’ll see if I can make some kinda sassy example branched off of the commonmark-website repo.
1 Like
This editor in Discourse is, unfortunately
-
tightly coupled to Discourse
-
Not using any JS version of commonmark yet
I’d hope somebody could hack together a quick and dirty JS-only overlay pane that uses a commonmark JS lib and lets people type in the left, and see real time output on the right?
Whipped up a not-good prototype: http://htmlpreview.github.io/?https://github.com/cfergus/commonmark-quickstart/blob/master/index.html
I am already not in love with the highlighting functionality, but I’d be curious if it’s worth using for feedback, improving, or just throw it in the garbage.
Update: the emphasis and list guides are now written. I’ll write the guide for hyperlinks next.
I’ve now fixed that error. It would definitely be a good idea for someone else to review the tutorial once it is complete.
I like the idea of adding a Discourse-style editor to the bottom of the page. One difference between Discourse and the current Middleman site is that the latter is not a single page app. Changes in the editor would be lost as the user clicks between pages.
Alternatively we could add “try this” sections to specific pages of the guides, at particular points, similar to markdowntutorial.com. This might be the simplest approach.
I’m undecided about which approach is be best. From a usability point of view, keeping the editor open as the user clicks around the site makes sense. To do this we could turn the guides into a single page app and add a Discourse style editor to it. That might be a lot of work though.
For now, I will focus on completing the text for the long form guides.
Storing the entered data in the localStorage could suffice - no need to make a SPA. Browser support
1 Like
Our dingus (http://try.commonmark.org) is a quick-n-dirty side-by-side real-time thing. What I’d really like to add (which the discourse editor has) is scroll syncing of the left and right panes. So, ideally someone could add this and make the thing into a nicely packaged reusable component.
1 Like
I think the highlight-on-hover is a nice feature for a tutorial.
The link and image guides have now been written. Quotations next.
I’ve modified the dingus to use the ace editor, and to keep the preview pane in sync as the source pane scrolls. I also set it up to highlight the block in the preview that the cursor is in. It doesn’t work perfectly yet and can no doubt be improved, but I’m thinking it’s better than what we had. (Code is in dingus.html and dingus.js in the jgm/commonmark.js repo.)
2 Likes
Highlighting is cool, but sync scroll looks raggy (i’ve copied text from markdown-it demo, browser Firefox).
+++ Vitaly Puzrin [Feb 03 15 10:19 ]:
Highlighting is cool, but sync scroll looks raggy (i’ve copied text from markdown-it demo, browser Firefox).
I’ve improved it a bit – better now? It is still not as smooth as the sync scroll on the markdown-it demo. I’m tempted just to borrow your approach, if you wouldn’t mind. It’s open source, right?
Sure, you can take any peace of code from repos in markdown-it org, without need to refer, if you find it useful. Just note, me & Alex are not experienced in UI programming, and can’t guarantee quality of demo code. Our demo needs serious rewrite and wait it’s hero 
More test cases for dingus (with copied big text from our demo):
- When i scroll with up/down cursor, right part position is updated immediately. But if i scroll with mouse weel, rigtht part is not updated every time.
- If i quickly scroll with mouse wheel from top to the end, i see very long animation on right scroll.
- Click on permalink gives error “too long params” (that’s one of reason why we pass data via hash).
Slowly nearing the end of the first draft. The quotations guides are complete; code guides next.
1 Like