@chrisalley can you fold in the work from @gjtorikian ?
I like the idea of giving people a little “try it out!” input box below the instructions so they can experiment in real time.
I also really like your “things to watch out for” sections, those are hugely important. There are a few things that trip average people up and we should be up front about those.
Hah! Not sure how I missed this topic @codinghorror …from two months ago.
No worries about static files; GitHub - gjtorikian/markdowntutorial.com: Lessons to help guide new writers into Markdown! runs on GitHub Pages, so it’s already just a set of static content. Looks like the CommonMark site is also just on Pages. Should I just make a PR to move everything over? I can turn the domain into a redirect to the CommonMark site.
I’m in the process of preparing a Middleman site for the CommonMark-specific guides that I’m writing. This will allow us to edit the guides in Markdown, with the table of contents pulled from a YAML file. The built site will run on GitHub Pages. I’ll aim to get something up on GitHub tonight.
@gjtorikian I’m happy to work on combining your guides with these new guides and then (once ready) preparing the pull request.
I quite like the idea of a “try it out” input box. Maybe we can autodetect any code blocks in the markdown tutorial via javascript, and assign a “try me button”. This would copy the text to a floating markdown editing windows like in this “discourse based forum”
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:
If you’re okay with this plan @codinghorror I’ll continue.
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.)
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.
As I see it, there are three formats that I would want, as a consumer of commonmark:
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.
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
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.
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.)