Here's an example. If a user types following into the question box:

```#include <iostream>
int main()
    std::cout << "Hello, world!\n";

It will look like this:

int main()
    std::cout << "Hello, world!\n";

The first line of code is silently discarded. It's probably interpreted as a language name for highlighting purposes, and since it's not a valid language, it's ignored.

I'm not sure if the old markdown renderer handled this differently from the new one, but I don't remember seeing this problem before the renderer was changed.

I've seen this cause unnecessary confusion in at least 3 questions so far. (recent example on ru.SO)

I think something should be done about it.

  • We could display a warning/error if an invalid language is specified after ```.

  • Or we could silently add a line break in those cases.

  • Something else?

  • 3
    A warning would be a useful guide on how to use CommonMark, though I'm not sure how feasible it is to detect. Silently adding a line break would be just as bad. If someone simply misspelled a language identifier, you have the opposite problem of a random word getting added to the top of the code block unintentionally. – animuson Jul 8 at 14:39
  • @animuson "If someone simply misspelled a language identifier, you have the opposite problem of a random word getting added to the top of the code block" Then we could check if the string merely looks like a language name (i.e. if it contains any characters other than a-z, then it's surely not a language name and we add a line break, otherwise we leave it alone). – HolyBlackCat Jul 8 at 15:18
  • 1
    @animuson It's usually the new users who make this mistake (more experienced ones would check the preview before posting), and the new users often don't even know that you can specify a language there. In any case, a random word getting added to the top of a code block is better (IMHO) than a line being cut off. A mistyped language name should be fairly easy to recognize, so it won't be as confusing. – HolyBlackCat Jul 8 at 15:22
  • 4
    Shouldn't it be easy to detect if the language isn't recognized by the syntax highlighter? That's worth a warning anyway no matter if it's a typo, misuse, or simply an unsupported language. – Christian Rau Jul 8 at 15:23
  • 2
    I still think automatically adding a line break there in any case is a no-go. Trying to get it right makes the processor way too complicated. Detecting "something is wrong" and displaying a warning for it is far simpler and has zero chance to do something erroneous on the user's behalf. – animuson Jul 8 at 15:26
  • I've seen this issue off and on for a while, and it predates the CommonMark migration. I'll also check the source (via the edit button) if it seems something like an include is missing. – 1201ProgramAlarm Jul 8 at 17:57

One solution would be to add an "Insert Code Block" button on the toolbar. Clicking it prompts you to select a supported language from a dropdown list. The user clicks 'OK' and it inserts a correctly-formatted code block at the current cursor position (newlines above or below as needed) and moves the cursor to the line after the backticks so that the user can just start typing/pasting code. An approach like this would:

  • make this mistake less likely, since new users are more likely (I assume) to use buttons than write raw markup
  • prevent the user from specifying an invalid/unsupported language
  • consist of UI changes only, no changes to the parser (which I believe is a third-party component)

I know the toolbar currently has a "Code Sample" button, but it merely indents. It lacks the extra features of fenced code blocks.

Even better, though more work to implement: along with prompting for a language, the dialog could include a space to type/paste your code. Clicking "OK" would populate the generated code block with that code. This would be an opportunity for additional (optional) features that solve other problems, like fixing the sort of spacing/formatting problems that we commonly see when people copy/paste from an IDE.

| improve this answer | |
  • Not sure this will help. Users who made this mistake clearly have disregarded the Code sample button on the toolbar, and decided to write markup manually. I don't think adding a second button, or changing the existing one to use ``` instead of indenting, will change anything. – HolyBlackCat Jul 8 at 16:42
  • @HolyBlackCat - The workflow for a new user is click button, then paste code. With the existing button, this screws up the formatting and the user goes back and manually adds code fences to fix it. If clicking the button resulted in something that code could be pasted into successfully, then I'd expect far fewer people would bother with manually creating code fences. – bta Jul 8 at 16:58
  • 2
    Didn't think of that. For users who do it this way, it might help. But there's another possible workflow: user ignores the toolbar and looks directly at the quick markdown reference below the text area (that simply says ```code```), and proceeds to write markup by hand. – HolyBlackCat Jul 8 at 17:02
  • @HolyBlackCat - IMO that quick reference is misleading and isn't helping this particular problem. Single backticks and triple backticks behave differently, but the differences are too subtle for a new user. The inline code sample in the quick reference should show single backticks. With triple backticks (as shown), adding a newline introduces the easily-missed problem you describe. With single backticks, adding a newline causes noticeable formatting issues that make it obvious that something's wrong. – bta Jul 8 at 22:53
  • Now that I look at it in more detail, the drop-down "Code" help menu says to use single backticks for inline code samples, so I'd argue the quick reference bar should be consistent with that. Also, that drop-down menu could be improved by explicitly stating that a fenced code block must have the fence marks on a line by themselves. The example shows this, but there's no obvious indication that it's meaningful. – bta Jul 8 at 22:59
  • Agreed, the quick reference should show single backticks. As for explicitly stating that a newline is required, I think it's obvious from the example, but ¯\_(ツ)_/¯. – HolyBlackCat Jul 8 at 23:09

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .