Provide a link to CommonMark documentation from the editor

I think it would be useful to have a link to the CommonMark reference, or optionally a custom topic, to help people with editing that cannot be performed by means of the toolbar buttons. If a link to a custom topic can be configured, plugin-specific markup such as that for the checkmark plugin could also be documented.

A question mark button all the way on the right in the toolbar button seems like a good way to add this link.

8 Likes

I can’t say if this would make it into core long term, but it seems like this would be a great candidate for a theme component to start.

11 Likes

A very quick turn-around: customize the key education.* texts on the site linking to the custom topic for your site. :sunglasses:

6 Likes

These messages only are displayed the first couple of times you compose a new topic/reply, aren’t they?

2 Likes

Yes, but that also makes them a far more appopriate place for this information :information_source:

4 Likes

I disagree. This would be a link to a reference to be consulted when you don’t remember some Markdown syntax you seldom use. It’s not something you read once and then never need to revisit.

1 Like

You seem to labor under the illusion that users will read anything you put on the screen.

They won’t.

The best approaches involve giving the information to the user just in time, when they are in most need of it – not dumping a bunch of random permalinks on the screen “just in case” that will be ignored 99.999% of the time, and add to overall clutter for all users.

3 Likes

No, sorry to disappoint you. :grin: This is simply a selfish suggestion for something that I personally would find handy. It is inspired by the GitHub editor which includes a link to the GH Markdown spec which I consult every now and then.

Agreed, that would be the ideal solution. Of course, that is easier said than done. This varies wildly between individual users, so I’m skeptic about the effectiveness of such an approach without extensive trials. Otherwise it’s just based on assumptions.

I assume the “Have you tied the :heart: button” is an example of this approach? For some reason, Discourse assumes I agree with the post I am replying to when my message contains very few characters. When I first ran into this, that assumption was wrong and caused nothing more than confusion and frustration.

That said, I don’t think there is an easy solution to educating users. There is probably no solution at all when dealing with users with different backgrounds, so please don’t take this as criticism.

2 Likes

If you want a generic Markdown reminder, check out commonmark.org !

1 Like

Another vote for a little :grey_question: over in the far upper/lower right of the composer box.

:ballot_box:

This plugin has been around for a while

15 Likes

The types of people who would find this handy are able to self-medicate by proactively seeking out and finding the information they need. They are already :star: students.

Furthermore … if users actually read anything (they don’t) they would have gotten to the formatting step of the interactive discobot welcome PM that all new users get. Which is best, since it’s dynamic and interactive using the actual editor and contains links to the help.

Check your PMs and you’ll see that very same welcome PM there too.

6 Likes

Thanks. I assumed something like this must already exist, but I failed to find it.

Unfortunately, it’s not working for me. Bug reported here: Plugin not working with Discourse 2.5.0.beta1 · Issue #12 · cpradio/discourse-plugin-composer-help-button · GitHub

3 Likes

I have had many people ask me how to use markdown so I’m for this idea.
It personally took me a long time to even figure out that the composer used markdown and to source instructions on how to use it.

My suggestion as a solution for this is to add a blue box on the top of the composer to new users saying something like:

“Learn more about how to format your text using markdown here: [link]”

The blue box can have a cross on the top right, so that people who no longer want to see it can close it permanently.

3 Likes

As Jeff said, discobot teaches some markdown basics. Is discobot enabled on your instance?

3 Likes

I do. Serendipity strikes and someone was pestering me and threatening to not use discourse if I couldn’t explain how to use it.

In the end I copy and pasted this article and globally pinned it in the forum. I learned a few things I didn’t know on the way.

2 Likes

A simpler approach might have been linking to

https://commonmark.org/help/

and

https://blog.discourse.org/2016/12/discourse-new-user-tips-and-tricks/

Both of those links are sent in the new user greeting PM that every new user gets after creating an account in Discourse.

3 Likes