CommonMark tutorial / help page feedback

Hmm yeah, looks like it works on the live site though. So I’ll just delete that link from above.

oh duh, it’s supposed to be http://commonmark.org/help/tutorial/ my bad :confounded:

OK, I think I “got” them all, but y’all will have to “check” my work.

I would argue against using a.com and b.org, and a.png and b.jpg for links and image links.

It is not logical to say that the two expressions gives the same result with different urls, is it?
It would also be preferable that the result equaled the expression that made it, if space is permitted, so that the user can experience the true result of the expressions.
There should be a one-to-one connection that makes it instantly understandable to everyone.

This help page will be for beginners, some probably not even programmers.

And I don’t buy the argument (in a twitter exchange I had) that one should defer the details of this to the tutorial (links section is 3 clicks away, 13 clicks if you do the tutorial sequential).

You need a way to distinguish between the two links, or else newcomers might think that the entire 3-liner is all one link, with an awfully complicated syntax. I wouldn’t mind the links being identical if they were more clearly visually separated in another way, e.g. by putting a big and bold “OR” after the first link.

Feel free to do a mockup for it or send a PR if you have a good way to show readers “Here’s method 1, and here’s method 2” without getting too verbose.

I think the page is great as it is, and that the OR is quite visible to separate the alternatives.
I see your point, but I think that someone who would think that the the two alternatives belongs together would get it wrong even if it where a/a or a/b.

Not a big deal for me, someone asked for feedback on Twitter, I thought it made more sense my way, and then it became a bigger issue that it should have…

Thank you for a civil reply and for taking your time.

Tor

1 Like

What a nice and stylish tutorial!

One small suggestion (first “notch” in “05 Links”): The blurb about reference-style link definitions says:

The link definition can be placed anywhere in the document, but is generally at the bottom.

What if a novice tries, for the exercise that follows, to put the link definition “anywhere, and generally at the bottom” like this:

You can do anything at [this site][id]
[id]: http://html5zombo.com

It’s certainly easy to then find out what’s wrong by trial-and-error (or maybe this is even intended as another exercise?), but how about mentioning the required blank line? Maybe:

Link definitions can be placed after a blank line anywhere in the document, but they are generally written near the bottom of the document.

1 Like

Sure that seems like a nice clarification, will add.

Also:

  • added some missing fancy quotes to success messages
  • converted wikipedia hurricane link to goo.gl shortened link for ease of entry on mobile

Have nested lists been discussed? I see them very often and would expect them to be mentioned on the /help page.

Yes, that is covered at some length in the tutorial, please try it.

Oh I missed that in the tutorial, was expecting a mention of nested lists on the main /help page.

BTW are nested list part of the specification at all? Found some philosophical discussion about blank lines in lists there but for example, the rule of indenting by four spaces, is that codified in the spec? The best I found was section 5.2.1, Motivation, but that’s just some discussion of the original Markdown.pl implementation.

Nested lists are covered, yes. Lists are block-level elements, so nested lists are just a special case of the nesting of block-level elements under list items.
You’ll find specific discussion of sublists, and examples, starting a bit before
http://spec.commonmark.org/0.24/#example-250

1 Like

Are four spaces recommended for simple nested lists or does CommonMark have no “opinion” here?

CommonMark has a more flexible treatment of nested lists than the “four-space rule.” (See the spec for a discussion.) However, the tutorial recommends four spaces indentation, because this approach will work with virtually every Markdown implementation. Anything else and your mileage will vary.

1 Like

Thought so, thanks for confirming it. I still think nested lists should me mentioned on the main /help page as it’s quite a common use case.

For /help/, instead of displaying all available syntax options all at once, could we add a basic tab toggle instead?

I like how the middle row is hidden on mobile, it looks a lot cleaner and less overwhelming. I think this is the way to go on desktop as well. The less common options can be hidden behind a toggle. The added win is that this would also make the alternative syntax available on mobile.

I don’t find the two columns to be overwhelming; this is the first time I’ve ever heard that bit of feedback from anyone… and I have asked in a lot of places for feedback on this.

It is definitely intentional that one column is “optional” or “extra” mostly to fit on smaller devices.

I don’t know whom and how you asked, but if you could do actual user tests it may well be that you discovered that @erlend_sh has a valid point. I’m not sure, though.

Anyway, it‘s usually considered acceptable to reduce complexity for mobile reading, but inacceptable to make content completely inaccessible.

Hi everyone!

I have an question about http://commonmark.org/help/
What’s the policy of translation of this page?
I’ll be happy to contribute russian-translated version of this page if you are open to hosting it at something like http://commonmark.org/help/ru/

If I’m asking in a wrong place, please redirect me to correct location…

1 Like

For the main page, a translation is OK! It is static HTML.

For the 10 minute tutorial, we need to come up with a JS translation framework approach. Which is a lot more work.

To clarify:
I have an approval to work on it?

1 Like