Feedback on our interactive Markdown tutorial

Contribute Site feedback
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 « J'aime »