So here’s what I propose: a small contest to build an interactive Markdown tutorial and reference, which we will eventually host at the home page of commonmark.org, and can be freely mirrored anywhere in the world.
Rules
It should be primarily in JavaScript and HTML. Ideally entirely so. If you need to use a server-side scripting language, that’s fine, but try to keep it simple, and make sure it’s something that is reasonable to deploy on a generic Linux server anywhere.
You can pick any approach you want, but it should be highly interactive, and I suggest that you at minimum provide two tracks:
A gentle, interactive tutorial for absolute beginners who are asking “what the heck does Markdown even mean?”
A dynamic, interactive reference for intermediates and experts who are asking more advanced usage questions, like “how do I make code inside a list, or a list inside a list?”
There’s a lot of variance in Markdown implementations, so teach the most common parts of Markdown, and cover the optional / less common variations either in the advanced reference areas or in extra bonus sections. People do love their tables and footnotes! We recommend using a CommonMark compatible implementation, but it is not a requirement.
Your code must be MIT licensed.
Judging will be completely at the whim of myself and John MacFarlane. Our decisions will be capricious, arbitrary, probably nonsensical, and above all, final.
We’ll run this contest for a period of one month, from today until April 28th, 2015.
If I have hastily left out any clarifying rules I should have had, they will go here.
Of course, the real reward for building is the admiration of your peers, and the knowledge that an entire generation of people will grow up learning basic Markdown skills through your contribution to a global open source project.
Fabulous Prizes
But on top of that, I am offering … fabulous prizes!
Let’s start with my Recommended Reading List. I count sixteen books on it. As long as you live in a place Amazon can ship to, I’ll send you all the books on that list. (Or the equivalent value in an Amazon gift certificate, if you happen to have a lot of these books already, or prefer that.)
Second prize is a CODE Keyboard. This can be shipped worldwide.
Third prize is you’re fired. Just kidding. Third prize is your choice of any three books on my reading list. (Same caveats around Amazon apply.)
If you want privacy, you can private message me the entries, email me (if you can find my email address, which I leave as an easy exercise for the reader), or if you are comfortable with posting your contest entry in public, here is a topic for you to post links and gather feedback.
Here’s my take on a Markdown tutorial: http://www.markdown-tutorial.com. It’s an AngularJS app that doesn’t have any real server-side dependencies. It uses angular-commonmark for rendering. The code’s available on GitHub.
Here’s my take on a Markdown tutorial:
[3]http://www.markdown-tutorial.com. It’s an AngularJS app that doesn’t
have any real server-side dependencies. It uses angular-commonmark for
rendering. The code’s available on [4]GitHub.
I really like the format!
A few thoughts on the content:
In lesson 2, “This is an h1 tag” is probably not the most beginner-friendly text to use. What is a tag? What does h1 mean? Maybe speaking of level-1 headings, level-2, etc., or top-level, second-level, etc. would be nicer.
In lesson 3, your example only shows the “lazy” style of blockquote marking, where the > is on the first line only. It would be better, in my opinion, to show the classic style first and then explain the “lazy” option, perhaps in a separate slide.
Lists: you don’t explain the tight/loose list distinction. You also don’t explain how one includes multiple paragraphs (or other block-level content) under a list. This is something a beginner should learn, I think.
Ordered lists: it would be good to note that the numbers used are ignored, except the start number (if this is targeting CommonMark, that is – if it is a more general “Markdown” tutorial, then you have to figure out how to deal with the fact that in original Markdown the start number is also ignored).
Nested lists: “You can create nested lists by indenting list items by two spaces.” Well, not always. In CommonMark, it depends on the width of the list marker, and how far it is indented. If you’re targeting CommonMark, you should tell them to put the nested list item so it lines up with the beginning of the content that comes after the list marker in the enclosing list item. If you’re targeting Markdown in general – well, then you’re out of luck, because this is an area where there is quite a bit of divergence. Gruber’s description hints at a four-space indentation requirement, but Markdown.pl doesn’t exactly obey this. (It certainly doesn’t always allow a nested list to be created with just a two-space indent; how much indentation is required seems to depend on context in a completely unintuitive way – see this example on babelmark2.)
Inline links: You don’t mention the possibility of adding a title to the link.
Reference links: You might want to give examples of shortcut reference links as well. These are convenient and very widely used.
Images: It would be good, I think, to give an example with some alt text, since it’s good practice to include that.
You don’t have any examples involving code spans or code blocks. Maybe your idea is that coders will not need a tutorial like this?
You don’t say anything about how to escape special characters - e.g. if you want to literally say *foo* and don’t want emphasis.
You don’t say anything about including raw HTML (maybe this is okay).
I think some of my comments above show that it might be difficult to give a clear “Markdown” tutorial rather than a CommonMark one. But, for the nested lists at least, if you teach them the four-space rule (paragraphs under a list item, and nested lists, should be indented four spaces), their lists will be most likely to work across many different Markdown implementations.
I had one more thought about your tutorial. Would it make sense to give people specific exercises to do, rather than just asking them to edit the text in the box?
For example: show an image of a rendered document (say, a nested list) and ask them to reproduce it in Markdown.
When they’ve got it right (which you could determine by comparing the HTML rendered from their text with the target), you could ring a bell, say hurray, etc. When they’ve got it wrong, maybe an arrow could point to the part that still needs work.
And they can’t go on to the next level til they’ve completed the previous one…
The site now prompts users to recreate specific examples and displays notifications when they’ve successfully replicated the example. I’ve also updated the introductory tour to explain the role of the examples. If you’ve already completed the tour you’ll need to clear local storage for the site to see it again.
I can lock the lessons until the user completes the previous lessons. However, it does prevent casually referencing the examples. Is the goal to have a reference site or an end-to-end tutorial? I can make it work either way.
Thanks for the feedback. I’ve added lessons for escape characters, code spans, and code blocks. I’ve also updated the explanations for the lessons based on your feedback and tried to make distinctions about where CommonMark differs from other Markdown implementations. Please let me know if I missed the mark on any of these items.
@codinghorror Do you want me to add the winning tutorial to the work in progress Middleman site over on my GitHub? The non-interactive guide I wrote is basically complete (minus a few sections). We should decide whether that’s still needed and then discuss how the interactive tutorial would best fit in with the rest of the site.
3 books of your choice from my recommended reading list, or the Amazon value equivalent in a gift certificate ($125.35)
Congratulations all! I’ll be contacting the winners to figure out where to send the prizes. And I’ll send our individual feedback to each entrant, as well.
