Help me answer questions about markdown formatting from my users


(Tobias Eigen) #1

I am grappling with some questions about markdown formatting from my users - very succinctly framed in the quoted text below, with names changed. How do you respond to questions like these that are pretty valid? Generally speaking I tell them that this is expected behavior of markdown and they have to learn and use markdown, but that only goes so far to help them.

One thing I note is that the markdown editor toolbar handles some things amazingly well, like links, but falls down on other things, like selecting some text and changing to bullet points, or selecting multiple lines of text and bolding or italicizing.

Also a new complaint that is cropping up is that copy/pasted text from outlook or word are truncated, with some long and some short lines.

I wanted to clarify the troubles Bar and Foo had, since there seemed to be some confusion over the phone. I observed these troubles because I was in the same room as Bar as she was struggling with the site, and Foo chimed in that she had similar problems.

To clarify:

  • Both were inputting into the left pane in the browser. They both understand that they are supposed to use markdown in the left pane, that it has its own syntax, and that the preview appears on the right. They understand the basic syntax. They both are on board with using the website to format more complicated emails to groups. Here were a few of their problems.
  • Foo had several separate lines that she had copied over from an email. The equivalent of several one-line paragraphs. She highlighted them all and tried to italicize them. But instead of being italicized, asterisks appeared at either end of her selection in the preview pane as well as in the input pane (not, as she expected, asterisks in the input pane and italics in the preview pane). She had to go in to each individual line and italicize them independently. The same applied to italicizing multiple bulletpoints at once. She had to do it individually to each bulletpoint. There were a lot of lines - it took a lot of time. Any way to italicize a lot of text at once?
  • Foo said that she wanted to put in more break spaces in her message, especially after a dividing line. She said that once she used <br> and it worked great. But she’s since tried recreating it and it doesn’t work. How does someone use html formatting in Discourse? Do you have to press a certain button to make an html tag recognizable as html?
  • Foo said she understands if there are limitations to the formatting options, but it would be nice if there was a reference guide to how the markdown syntax works in discourse - what you can and cannot do and how. So she knows whether she’s trying to do something impossible, or if there is indeed a better way of doing things. I agree!! Can you share a guide to markdown as it works in Discourse? I don’t expect you to make one - hopefully one already exists.
  • Bar was having trouble getting “Undo” to work. Sometimes it worked, and sometimes it did not. I just tried it now (Command+Z) and it did not work. Under what conditions does Undo work? How do you undo formatting when writing in the browser?
  • Both Bar and I had several lines we wanted to convert to bulletpoints. In Gmail or Word, you highlight those lines, click the bulletpoint button, and voila, each line gets converted to a bulletpoint. Not so with Discourse. If you highlight several lines, then press the bulletpoint button, all the lines are combined into one bulletpoint. Alternatively, if you place your cursor at the point in a paragraph that you want separated into a new bulletpoint (not highlighting anything, just pressing the bulletpoint button), it pushes your text down and inserts a bullet point with the words “List item” afterwards. Then you have to go and delete the words “List item” and move your text to that spot. Again, we understand if there are limits to this syntax, but we want to make sure we’re not missing anything - Is there an easy way to make multiple bulletpoints at once? Let us know and we will happily apply it.

I think those were the problems I observed.

Edit: here’s what I wrote to them now as a start:

It’s going to be hard for us to satisfy everyone, unfortunately, and especially people embedded in the Microsoft Outlook/Word world are going to resist and be frustrated. There is no silver bullet to just ‘fix’ this so it behaves the same as Outlook/Word.

Instead, we need to build up a team of moderators who understand and buy into how discourse works who can gently nudge and train new people as well as help with editing/fixing formatting when it goes awry.


If you have a long text prepared in Word you can convert it! I found a two-step way to do it that works pretty well for me but may be a bit much to ask non-techies who fear HTML.

But on the other hand, if you have very long text you want to share, maybe it’s best to save it as an attachment and to write a shorter post in discourse introducing it.

Need Help Formatting Posts from Microsoft Word
How to bring in formatted text from Word into a Discourse post?
(Tarak'ha) #2

I don’t know if Discourse ships with CommonMark or Markdown Extra, which I think are the two main flavors that most use.

Anyone with more intimate knowledge of the codebase is welcome to clarify. That way, at least @tobiaseigen can give his community members a link to either or as a start.

(Jens Maier) #3

Actually, neither. Discourse uses markdown-js and a lot of its own magic with frequent bugs and quirks…

To address Foo’s and Bar’s problems:

Aaaand I just found a bug. This causes a JS error:

- <p> foo

  • The intended way to quote stuff is to prefix each line with "> ".
  • The best way to italicize several paragraphs at once is to use HTML tags <i> and </i>.
  • Any HTML is sanitized; inline-styles, most classes and many block tags are removed, e.g. <table>. <br> should survive, however, unless the parser is in a state where it expects plain text without any markup.
  • If undo/redo don’t work as expected, you’ve found a bug. If you would like to support Discourse, try to find the shortest set of steps required to reliably reproduce the issue and report your findings on meta. (E.g. “type a word, add an image via drag&drop, summon Hastur The Unspeakable; pressing Ctrl-Z to undo now fails.”)

(Tobias Eigen) #4

This is all very helpful - thanks! :smile: Much appreciated.

Has anyone written a comprehensive guide to discourse markdown?

Is there an easy way to convert say a word document to markdown?

(Jeff Atwood) #5

As for Word, first strip it of its html weirdnesses.

(Sam Saffron) #6

I entirely agree with this assessment and can not wait for the day we move to a CommonMark compliant parser that is less insane to debug.

(Tobias Eigen) #7

Yeah, I use then to-markdown - an HTML to Markdown converter written in JavaScript myself but don’t really want to impose this workflow on ordinary civilians.

Honestly, it should be possible to copy/paste straight from Word and have it look reasonably good, with basic formatting and bullets intact.

(Jeff Atwood) #8

That’s a HUGE ask. Good luck with that. Because Word is profoundly fucked up in its formatting

(Tobias Eigen) #9

Haha! Your response shocked the hell out of me and then I had to laugh.

Yes, I know this and was venting about this annoying problem that never seems to want to go away.

In drupal we used to have a “paste from word” option that worked reasonably well, similar to the word2cleanhtml site. Pop up window, paste in text, then see what you got. Clean up text that still looked garbled.

(Scott Trager) #10

That paste from word was included with the WYSIWYG editor module and actually was fantastic for my end users at the time- saved a LOT of time especially when users frequently clip stuff out of docs.

(Jeff Atwood) #11

It’s possible there could be some “paste from Word” plugin at some point, but I really don’t want to write this unless someone is paying us to do it.

(Tarak'ha) #12

@tobiaseigen, I did some searching and think you should direct your community members to this Word to markdown converter. It uses the files themselves, not a copy&paste of the text.

I use a combination of WriteMonkey and Text Editor Everywhere to help with writing long-form replies. However, I’ve been looking at MarkdownPad too which is basically a Markdown Word Processor. But WM is doing well for me and supports Markdown Extra out of the box. It’s also less expensive to get the full version. Any donation amount gets the donator a donor-key that unlocks everything.

(Tobias Eigen) #13

And… check this out - a google docs > markdown converter script. Seems to work pretty well.