Feedback on our interactive Markdown tutorial

Site feedback
26

Let’s get it translated and link to it from the Discourse message editor.

1 Like
27

Feedback: Extremely helpful. I’m transitioning my team (we do book and lit-journal publishing) from screwing around with Word documents by email, to using Markdown files committed to a local SVN repository. Many of them don’t quite get the concept, so having both a quick reference and a tutorial … well, I’ve already sent them the link. :slightly_smiling:

4 Likes
28

This was a very common request across all the sites I asked for feedback on the tutorial.

I’ve added a reset button which is initially hidden, to avoid page clutter, but appears dynamically when the editor no longer matches the initial page load text.

(also @Nick I was able to get the side nav visible on lesson starts which helps a lot, I think)

If you haven’t tried it yet, try it again. I added a little fun :tada: at the end.

2 Likes
29

I also ran into this and suggested a different mitigation tactic:

But the root of the problem is really, as you say, that we don’t expect escaping to come up at this point. At first I thought maybe escaping ought to have a section of its own, but on second thought that sounds like a bit much. But I do think the reader needs to be warned, like “heads up! small digression incoming”.

1 Like
30

I think escaping is actually expected at this point. I just only expect to be escaping unintended emphasis based on what I’ve been told at that point.

Currently, the example comes at me like:

  1. Apply style x to your text using character a
  2. Escape character a to avoid applying style y
    (wait I thought we were talking about style x, why are we talking about style y?

Things would flow more naturally to me if they followed this format:

  1. Apply style x to your text using character a
  2. Escape character a to avoid applying style x.

Sticking to this formula for the escaping examples that are spread throughout the tutorial helps make them more relevant, and associates the value they have as formatting characters when that is the intention alongside how to escape that formatting when its unintended.

Separately, and additionally I think a short overview section could be added toward the beginning that does introduce escaping more generically:

  1. Overview (first section)
    • markdown is awesome, here’s an example showing all the awesomeness
    • and it just stays out of the way when you just want to type some normal paragraph
    • but if it does get in the way on occasion, you can get around it easily

draft:

Overview

  1. One of the great things about markdown is that it lets you type text which looks just as good formatted as plain text as it does when it is rendered as HTML. Here’s an example of a post written in markdown shown as plain text and HTML:
    insert some long-ish example demonstrating multiple features
    Next

  2. Often, all you really want to type is unformatted text anyway. That basically looks the same in plain text and HTML without doing anything special:
    insert some medium example of a normal paragraph of text shown
    Next

  3. In the rare case that markdown’s formatting rules get applied when you don’t want them to be, you can put a \ before the special character to escape that formatting. Try escaping the - below in the signature so it doesn’t look like a list item:
    OK, let's get started!
    ``
    - Dave
    Next

I know CommonMark has put a fair bit of effort into making a few things more intuitive and less error-prone where it doesn’t deviate too much from the existing implementations. For instance, you can start a bullet list immediately after a paragraph with no blank like between them. But if there are still a number of examples that could justify a separate “common mistakes and how to avoid them” section, I think that could go at the end too.

1 Like
31

I read it more as

escape character a when you really want character a to appear verbatim

Each lesson introduces specific character sets, e.g.

  • Bold and Italic need * and _
  • Blockquote needs >

etc

32

Well I’ve done my best but I think @erlend_sh’s suggestion for that page is an improvement if you’re open to a smaller change for those of us who do find it confusing.

33

Menu of tutorials disappear on mobile android chrome

Screenshot_2016-01-01-11-09-05.png1080×1920 46.3 KB

Steps

  1. Visit site, start tutorial
  2. Note menu shows properly
  3. Click begin lesson
  4. Menu still shows
  5. Click try it
  6. Menu disappears
  7. Click back to Emphasis button
  8. Menu still not visible
  9. Refresh page, menu visible again
  10. Repeat steps 3 through 9
2 Likes
34

Yep, I noticed that just before I went to bed – now fixed. It was a side effect of showing/hiding the lesson nav titles on desktop. On touch the lesson titles should always be visible since they only appear on popup.

2 Likes
35

Bug report

http://commonmark.org/help/tutorial/07-code.html

  1. as asked, transform the table to code but using a pair of 3-backticks
  2. realize you’ve not followed the statement exactly:
  3. indent the code with 4 spaces
  4. remove the backtits
  5. expect a “success” dialog; be disappointed.

Even though the input is now correct, the success dialog is not triggered. The only way of triggering the success dialog is to reset and indent with 4 spaces right away.

1 Like
36

Yes, though I would argue you did succeed, you made a code block … success state can only be reached once per exercise :wink:

If someone thinks outside the :package: that’s great.

37

any chances for easy translations into other languages ?

38

I definitely want to add something to make translation easier… any recommendations? It’d be pure JS, no server side

39

it is prity generic maybe you can try using some BOOTS to do translation on fly

40

Translation on the fly makes no sense for this, all the text that needs to be translated is static and only changes on ‘updates’. That’s just expending resources for no reason.

41

Nice idea. I like it.

Some general feedback:

Too much clicking.
Intrusive ‘success’ popup/overlay becomes jarring after a few times.
The step by step structure of the exercises feels a bit dated. I wonder how this would look like as a one-page game where you progress down the page fluidly (ideally by never leaving the input field), rather than having to click through a series of standalone exercises.

Maybe guiding the user through using all of these features in markdown from an empty document would be better than these focused exercises. Just an idea.

42

Yeah, there were some entries that had the “everything on one page” layout but we preferred the step by step method for the tutorial. You can look at the two runners up in the contest, linked from this post:

One of them is what you are describing, a bunch of stuff on one long scrollable page.

43

Great Job

Loved the tutorial! Here is my feed back:

Emphasis

Can you make the whole sentence bold, and italicize the word “must”?

I miss read this and surrounded must with two underscores and a star on each side. I then saw my mistake, highlighted and dragged the underscores to the ends of the line. the app did not register the text change event until i entered a space

Images

Don’t bother specifying alt text or title.

expected: leave the alt text blank

Blockquotes

I mistakenly put a > in the middle of the line thanks to the word wrap

Nested Lists

The content under each numbered item isn’t nested properly. Can you fix it?

directions unclear. I created nested list using an indented dash for each sub item

1 Like
44

Yeah I don’t think drag events are counted as keydown events.

The last exercise is supposed to be a bit harder, since it is the last one.

45

Ok, http://commonmark.org has been updated with a prominent link to the reference and tutorial.

2 Likes