CommonMark tutorial / help page feedback

#42

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
0 Likes

#43

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

0 Likes

#44

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

0 Likes

#45

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.

0 Likes

#46

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

#47

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

0 Likes

#48

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

#49

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.

0 Likes

#50

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.

0 Likes

#51

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.

0 Likes

#52

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.

0 Likes

#53

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

#54

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.

0 Likes

#55

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

1 Like