491

Currently, Stack Exchange’s Markdown parser only allows four-space indents to represent code blocks:

    // some code
    // another line of code

GitHub Flavored Markdown and other Markdown implementations allow for an alternative syntax, that doesn’t require indenting each code line:

```
// some code
// another line of code
```

This is much more convenient to type out. It would be super useful if Stack Exchange could support this syntax.


By extension, this syntax also allow you to specify the source language right after the opening ```:

```js
// some code
// another line of code
```

…which would then enable syntax highlighting for that specific language. Although it’s interesting metadata, I don’t think this feature is needed on Stack Overflow, as the syntax highlighting library works pretty well for various languages.

So, even if you would allow this syntax but ignore the ```language, this would greatly improve my productivity on Stack Exchange.

What do you think?

The moderators are currently collecting feedback regarding this feature, so please post a comment with your thoughts. Good idea? Bad idea? Don’t really care? What do you think are the benefits/drawbacks? Experiences? Let them know! Thanks!

  • 101
    +1 I think this would be great. Not having to worry about an extra 4-space indent when editing code the textbox would make it less necessary to pull it out into an external editor and then paste it back in. – cdeszaq Mar 9 '12 at 13:20
  • 8
    @BoltClock'saUnicorn: This feature wouldn't be intended for people who accidentally stumble across it, but for people who actually know it's there and find it is a more convenient method of posting code than indenting by four spaces (I would probably use it). – Greg Hewgill Mar 9 '12 at 20:35
  • 31
    This is a reasonable suggestion, we're considering it. A nice side effect would be that this kind of code block wouldn't have a "placed after a list" problem. – balpha Mar 11 '12 at 15:33
  • 3
    When adding it, please consider handling four-backtick "fences" just like the regular three-backtick fences. On a German keyboard it's extremely annoying to enter an odd number of backticks since it's a deadkey and you cannot change it without side-effects. – ThiefMaster May 17 '12 at 10:03
  • 3
    @Chichiray: Clicking is easier than dragging as the latter requires you to aim such that you select the text right, and ` is a single key where Ctrl+K is not; as a result click ``` click ``` is faster to perform. – Tamara Wijsman Aug 9 '12 at 15:31
  • 9
    I can't count how many times I've gone through and put 4 spaces on the clipboard, then flew down the lines of code repeatedly hitting Ctrl+V, DownArrow, Home to indent the entire block. – gobernador Aug 9 '12 at 17:38
  • 2
    @gobernador what text editor are you using?, it is usually possible to indent the whole thing if it is selected and then insert some tabs. Or in the editor of this site, just select the whole thing and click the 'code' icon and will indent for you – ajax333221 Aug 9 '12 at 22:58
  • 9
    @balpha Given this syntax is now standardized in CommonMark, could this be reconsidered? – Mathias Bynens Sep 18 '14 at 13:57
  • 5
    The new Documentation system (currently in private beta) is using a different, CommonMark-based parser with support for fenced code blocks. Documentation should be out of beta within a month or two. Maybe we'll see that parser used elsewhere on the site, after it's been exercised for a little while. – REINSTATE MONICA -Jeremy Banks Apr 11 '16 at 23:36
  • 4
    This has taken so long and is so annoying! Please, it doesn't need to be to CommonMark spec, just add triple-backticks. – iono Oct 6 '16 at 8:30
  • 9
    It's not much in terms of import but this is my absolute #1 feature request for SO. Like the only thing I can think of that I care about. – jcollum Nov 7 '16 at 16:20
  • 7
    I am wondering what's the reason for making this deferred, maybe a little bit of NIH syndrome? This was a very popular request, easy to implement and low risk. Why not spending 100x more effort on experimenting new ways of writing and hosting documentation. – sorin Nov 12 '16 at 11:42
  • 4
    Most of the comments here are about how easy or difficult it is for the person commenting to enter. I don’t care about that so much; I know enough tricks that I can get the indentation right, and if I’m worried I check the preview. However, people new to the site don’t know this. At least half the questions on SO with code blocks have bad indentation, and this is especially visible in the python tag. Right now I’m trying to answer a question when I don’t know what the code actually says because of inconsistent indentation, and I am not inclined to blame the asker for that. – Daniel H Sep 15 '17 at 15:21
  • 5
    I'll buy the Stack Overflow engineers a beer (or more) for fixing this. When writing code on Stack Overflow, I often write it in my editor and copy it over into the answer. It's a horrible experience that I hope can be fixed. PLEASE! – Yangshun Tay Jan 2 '18 at 7:37
  • 2
    i'll just leave this here ;) "as a social phenomenon, this philosophy can manifest as an unwillingness to adopt an idea or product because it originates from another culture, a form of tribalism"en.wikipedia.org/wiki/Not_invented_here – ChaseMoskal May 27 '18 at 1:52

10 Answers 10

190

Code fences work now.

function DeepThought(task) {
    this.task = task;
}
DeepThought.prototype.answer = function () {
    switch (this.task) {
        case "life, universe, and everything": return 42;
        default: throw "not implemented";
    }
}

(view source on this answer)

As much as that's possible for a partial feature, they are compliant with CommonMark 0.28. That means:

  • A code fence consists of three or more backticks ``` or tildes ~~~, indented by zero to three spaces.
  • The opening fence can be followed by a syntax indicator. On Stack Exchange, this can be a Prettify module name (e.g. ```lang-cxx) or a tag for which syntax highlighting has been configured (e.g. ```c++). ```none disables syntax highlighting.
  • The closing code fence needs to use the same character, and at least the same number as the opening code fence.
  • The code block will be de-dented by as many spaces as the opening code fence was indented with. So this:

    See this:
      ~~~
      foo
        bar
      ~~~
    

    turns into this:

    See this:

    foo
      bar
    
  • An unclosed fenced codeblock continues to the end of the block (e.g. block quote) or post.

That last point is also the reason for the only real edge case breakage that this causes with existing content. If somebody created a horizontal line in a post with something like ~~~~~~~~~~~~~~, that is now going to open a code block. As always when we make markdown changes, the question & answer view is not going to be impacted by this unless the post is edited, and it's extremely rare, so I'm not too worried about this.

  • 34
    Wow, cool! You folks are on fire this week. – Josh Caswell Jan 8 at 17:17
  • 4
    @JoshCaswell 10th Anniversary affect. – Nog Shine Jan 8 at 18:39
  • Hi balpha. When are we going to change help information? E.g. the "How to format" on the right side of asking a question etc. – iBug says Reinstate Monica Jan 9 at 5:56
  • 3
    I have just updated How do I format my code blocks?. – Sebastian Simon Jan 9 at 14:47
  • We should also update the “indent all code with 4 spaces” error. It likely won’t trigger on triple-backtick fences, but will it trigger on ~~~ fences? Also, it should mention fenced code blocks as an alternative. – Sebastian Simon Jan 9 at 15:06
  • 2
    @Xufox Good call on the "unformatted code" detector. Fix for that is in the pipeline. As for the other thing, there are a bunch of places where indenting is recommended. Once code fences have been working for a bit, we may revisit which way of creating code blocks should be the recommended one. – balpha Jan 10 at 10:45
  • 10
    I just told someone that triple backticks don't work on main, then had to eat my words when I tried and it worked. Could you guys please feature this post or fire up a separate announcement? Considering the large previously-malformed-but-now-valid post rate, this is important information. Also thanks. – Andras Deak Jan 10 at 18:04
  • 3
    Why did you decide to require e.g. lang-js instead of just js like other common implementations of fenced code blocks? – Mathias Bynens Jan 11 at 21:06
  • 4
    @MathiasBynens That's how it's always been when you specify the syntax highlighting language on SO, so that's what I went with for my example. You can leave off the lang-, that's going to work as well. – balpha Jan 11 at 21:10
  • I just noticed this accidentally—7 days after the fact. For a moment I thought I had gone crazy—“why is my GFM suddenly valid on SO!?!?” – binki Jan 16 at 19:16
  • Another victim. (Someone trying to change working formatting to equivalent working formatting; can't be due to anything other than lack of information.) – Andras Deak Jan 17 at 10:20
171

Benefits

  • Compatibility with GitHub-Flavored Markdown and other Markdown libraries that support this de facto standard (and possibly its variants). This enables copy-pasting from gists or Markdown files within repositories, which can be useful on programming-related sites like Stack Overflow.
  • The triple backtick syntax is easier and faster to type than indenting each line of code with four spaces.
  • Saves some storage in the database, too! ;)

All the above benefits apply to the new syntax, even without the additional functionality to specify the programming language. With that functionality, I’ll add another (huge) benefit:

  • As it’s much easier to specify the language of code blocks using this syntax (compared to the current syntax), I wouldn’t be surprised if this change caused more people to explicitly declare the programming language, so that the syntax highlighting can be more accurate. This is useful for answers that include, e.g. separate HTML and CSS code blocks.

Drawbacks

I honestly can’t think of any. It’s very likely no one is using the triple backtick-syntax at the moment as it doesn’t work; so I doubt it will break anything. If you don’t like the new syntax, feel free to stick to the old one.

Experiences

Ever since GitHub enabled this syntax, I’ve grown accustomed to it. I ♥ triple backtick syntax, and every time I’m forced to go back to the four-space-indent syntax, it feels awkward.

  • 15
    159 places have a triple-backtick (I was scared to search for a double-backtick, though): data.stackexchange.com/stackoverflow/query/edit/76842 As far as I can tell, none of them would be broken by implementing this. – Ry- Aug 9 '12 at 15:20
  • 3
    @minitech Thanks for the query. I see a few that might cause problems, but with just 159 results it's not beyond the realm of possibility to manually verify that each one is correct, or is fixed, if this were implemented. – Servy Aug 9 '12 at 15:23
  • 3
    @Servy I would even volunteer to manually verify these if it meant getting this feature! – Michael Gaskill May 21 '16 at 1:52
  • 1
    @MichaelGaskill I'd help! – Doktor J May 17 '18 at 17:46
77
+250

I don't really care either way whether this gets implemented: it's a superfluous extension to Markdown (unlike, say, inline HTML, spoiler markdown, or the as-yet-unimplemented-on-Stack-Exchange table syntax), but it is true the fenced code block has been added to pretty much every Markdown library that doesn't stick to just the original spec.

However, the triple backtick syntax is a GitHub extension, and it's not exactly the "de facto standard" Mathias Bynens portrays it as.

Fenced code blocks, as far as I understand it, were first introduced in the PHP Markdown Extra library as the following:

Fenced code blocks are like Markdown’s regular code blocks, except that they’re not indented and instead rely on a start and end fence lines to delimit the code block. The code block start with a line containing three or more tilde ~ characters, and ends with the first line with the same number of tilde ~. For instance:

This is a paragraph introducing:

~~~~~~~~~~~~~~~~~~~~~
a one-line code block
~~~~~~~~~~~~~~~~~~~~~

Other implementations followed suit, by either supporting only 3+ tildes or supporting both 3+ tildes and 3+ backticks. I ran through the implementations I know of, and Wikipedia's (incomplete) list of implementations (before GitHub went down), and found:

Supports only the 3+ tilde syntax:

Supports only the triple backtick syntax:

Supports both:

Supports neither, or is unspecified:

Based on this, I think Stack Exchange should support the tilde syntax, the triple backtick syntax, and the 3+ backtick syntax. Bonus: support of either the tilde syntax or the 3+ backtick syntax should solve the deadkey problem.

The syntax toolbar should continue to indent code with 4 spaces as per the original Markdown spec, or if that's not feasible, it should use the tilde syntax, which has the benefits of being the original version, compatible with GitHub, and marginally more supported by existing implementations.

  • 3
    Excellent research! Good point about supporting all variants of the syntax to eliminate the dead key problem. – Mathias Bynens Aug 16 '12 at 8:09
  • 4
    Thanks for the great research. I'm still not 100% sure we should do it, but this answer contains excellent information to base a decision on. – balpha Aug 17 '12 at 9:49
  • 5
    «Bonus: support of either the tilde syntax or the 3+ backtick syntax should solve the deadkey problem.»: while I agree with you say, this last one is false. In my standard Portuguese keyboard, both `` ` `` and ~ are deadkeys. – JMCF125 Feb 16 '14 at 18:49
  • 5
    Both tilde and backtick is dead keys on Swedish keyboards too. – Emil Vikström Apr 2 '14 at 18:00
  • 1
    @JMCF125: And what happens if you press the dead key twice? Yep, it acts as if it was not dead, twice. – Deduplicator Nov 3 '15 at 1:11
  • 9
    @user149432, The thing is that Github is 90% of the population, so if Github supports it.... – Pacerier Feb 18 '16 at 20:22
  • 5
    Yeah I have to agree with @Pacerier. Listing the libraries like this makes it seem like ~ and ``` are equally popular. In reality Github is huge, and not all libraries are equally popular. – Timmmm Sep 25 '17 at 14:06
  • Doxygen supports the tilde and the backtick syntax – albert Oct 2 '18 at 8:51
  • 2
    The deadkey problem links back to this answer. intended? – lucidbrot Nov 19 '18 at 13:58
  • the dead key shouldn't be too much of a problem unless the kb layout is b0rken - typing the dead key twice should result in one character. And yes, the Finnish layouts share these 2 with the Swedish ones (but we've got one layout with gazillion dead keys more as well) – Antti Haapala Jan 14 at 6:53
53

On Stack Overflow, all the time I'm seeing this happen to people who don't know the syntax.

class Foo {

public static void main(String[] args) {
    // y my code no is working
    Sytem.out.println(qrew3r);
}

}

Some people stop there and never fix it because it's close enough. Others figure out that the first and last lines aren't part of the code block because they're not indented. So they indent those two lines - only those two lines - because the editor doesn't provide an apparent way to indent the whole block.

class Foo {

public static void main(String[] args) {
    // y my code no is working
    Sytem.out.println(qrew3r);
}
}

The result is that we have a site that systematically causes newbs to post questions with poorly-formatted code. Whether or not you like fenced code blocks, when you look at all of the mistakes that users are making, you've got to appreciate that the current UX is broken.

  • 9
    ..."the editor doesn't provide an apparent way to indent the whole block". There is, though not apparent: Ctrl + k after you select the block. (On Mac it's + k) – Franklin Yu Sep 17 '16 at 23:53
  • 1
    @FranklinYu ooh, I did not know that. Thanks. – ArchNoob Apr 13 '17 at 17:49
  • 11
    It’s even worse in Python, where you often literally cannot tell what the code is supposed to do. In brace-delimited languages you can work past the bad formatting. – Daniel H Dec 19 '17 at 1:12
  • yes, this is really annoying and unintuitive. I have to google on how to fix this and goes back to StackOverflow to write an answer. The problem will grow bigger when combining with a list and long lines of code. – aldok Jan 23 '18 at 2:28
13

You can currently specify a language to be syntax-highlighted.

Example:

<!-- language: lang-js -->

    //JS code...

This should not discourage the question, it is even a plus because they don't need to code this feature anymore.

The only thing left to do is to implement the ```` code blocks system (which I believe, is not that hard)

  • 2
    Good to know — thanks! Sounds like a regular expression that converts the triple backtick-syntax into the existing syntax behind the curtains could be a quick fix. – Mathias Bynens Mar 10 '12 at 8:14
  • 30
    This is not as nice than the triple-backtick syntax though. – ThiefMaster Mar 23 '12 at 7:26
  • 2
    github supports the same using ```php for example – pocesar Apr 11 '13 at 20:35
  • @ThiefMaster, Exactly. This is a bother to type (or even to use the UI), often I just don't bother and do it the "old way". – Pacerier Feb 18 '16 at 20:22
  • 3
    This <!-- language: lang-js --> is horrific! I always need to go Google to remember the exact syntax – Yves M. May 9 '18 at 9:16
13

Another reason to include this syntax: Some people are already using it.

However, it makes their posts look kind of strange, since it becomes inline code spread over multiple lines:

This is what it looks like when you put triple backticks above and below multiple lines of text.

By contrast, this is 
a multi-line code block
created by indenting text four spaces.
  • 1
    On 10 million questions the numbers are rather low: data.stackexchange.com/stackoverflow/query/488893?year=-1 – rene May 20 '16 at 20:15
  • 4
    @rene What if you add old revisions that people have fixed in the meantime? – Gilles 'SO- stop being evil' May 20 '16 at 20:44
  • @Gilles uuugghh, that will probably kill SEDE ;) I'll give it a try later – rene May 20 '16 at 20:45
  • 1
    @rene Does your query account for every version in a post's history? I find and fix triple-backtick posts to proper syntax all the time, and I wonder if the "low" number is only low due to human effort. Personally, I don't mind doing it, but if I and others no longer needed to fix these posts, we could use that time for something more useful. – Dan Lowe Jan 14 '17 at 22:01
  • @DanLowe no that query didn't take posthistory into account. This one does but I limited both the date range as well as the number of rows because the full table scan on the posthistory table is killing the performance and it timesout if I fetch much more rows. – rene Jan 14 '17 at 23:03
12

Another major benefit is when marking down code within lists. Creating block codes within list is often a major annoyance, contrast:

- Bullet 1

 Lorem Ipsum (paragraph 1).

 Lorem Ipsum (paragraph 2).

        var foo1 = bar1;
        var foo2 = bar2;
        var foo3 = bar3;

 Lorem Ipsum (paragraph 3).

to:

- Bullet 1

 Lorem Ipsum (paragraph 1).

 Lorem Ipsum (paragraph 2).
```javascript
var foo1 = bar1;
var foo2 = bar2;
var foo3 = bar3;
```

 Lorem Ipsum (paragraph 3).

Bulk of the annoyance comes from the editor not being able to do 8-space indents as CtrlK un-indents instead of converting four spaces to eight. "Also, is that blank gap 7 spaces or 9 spaces?"

Of course, the problem is magnified when trying to put block codes within nested lists. Contrast:

- Bullet 1
 - Bullet 1.1

     Lorem Ipsum (paragraph 1).

     Lorem Ipsum (paragraph 2).

            var foo1 = bar1;
            var foo2 = bar2;
            var foo3 = bar3;

     Lorem Ipsum (paragraph 3).

to:

- Bullet 1
  - Bullet 1.1

   Lorem Ipsum (paragraph 1).

   Lorem Ipsum (paragraph 2).
```javascript
var foo1 = bar1;
var foo2 = bar2;
var foo3 = bar3;
```

   Lorem Ipsum (paragraph 3).

It gets worse with double nested lists. Contrast:

- Bullet 1
 - Bullet 1.1
     - Bullet 1.1.1

         Lorem Ipsum (paragraph 1).

         Lorem Ipsum (paragraph 2).

                var foo1 = bar1;
                var foo2 = bar2;
                var foo3 = bar3;

         Lorem Ipsum (paragraph 3).

to:

- Bullet 1
  - Bullet 1.1
   - Bullet 1.1.1

     Lorem Ipsum (paragraph 1).

     Lorem Ipsum (paragraph 2).
```javascript
var foo1 = bar1;
var foo2 = bar2;
var foo3 = bar3;
```

     Lorem Ipsum (paragraph 3).

Hopefully inserting block codes within list will be less time-consuming after the update.

6

Another (very) minor benefit is that you can use this syntax to break up code blocks. For example, this code (rendered in an engine) will create three separate blocks with very tight breaks:

```
block1
```
```
block2
```
```
block3
```

I'm not aware of any way to do this using the indent style as unindented lines (no matter how many you interject) don't break the boxes up:

block1





block2


block3
  • 8
    Just interject <!--> between the code blocks. I'm tempted to edit your answer to show it, but it's probably better you try for yourself. – Glorfindel Aug 2 '17 at 20:16
  • 3
    <!> is enough. Also <?> (which is three adjacent keys, but out of order) and many other variants.  I like </>. – Scott Feb 13 at 7:00
  • 1
    I've always used an empty comment <!-- --> or a horizontal line --- depending on the situation – phuclv May 24 at 5:01
0

Only drawback I could see is being unclear as to which is the 'right way'. But on a whole I think this would be a great feature to add for someone like me who doesn't want to be using either the button above or spacing in.

  • 5
    But there is not "right way". All ways that works are correct. – Emil Vikström Apr 2 '14 at 18:01
-3

The main benefit I see coming from this is that you'll be able to see a little more of the code in the edit box without wrapping. Making it a little easier to specify language is nice too, but I find that the tags take care of it in a large majority of cases.

I'm certainly not opposed, but I don't think it will make fixing code formatting that much easier. You can already select the lines and hit the Code Sample button to add the first level of indent. From there on it's the same amount of work to add additional indents--either copy four spaces and use CTRL-V as a tab key for each line, or copy into editor, fix, and copy back. I think being able to select multiple lines and indent/unindent multiple times would be a lot more helpful than this.

On the downside, ``` would be one of the least intuitive bits of markdown. Doesn't really have the same WYSIWYG feel, at least for me. Using the same sequence to start and end the formatted section could also be a bit confusing, particularly when there are multiple code blocks in a post.

Something like {{{ to start and }}} to end would be clearer, or a custom html tag like, <codeblock></codeblock>, or just allow the <code> tag to span multiple lines to create a block. Or, combine with specifying the language, for example: <java></java>.

  • 1
    It's a big help when you have mixed tabs and spaces, too. – Ry- Aug 9 '12 at 15:36
  • 2
    @bemace I know you can select the lines and then hit the Code button, but as a heavy keyboard user, I find typing three backticks, a line break, Cmd + V, another line break, and three closing backticks is much faster. – Mathias Bynens Aug 9 '12 at 15:36
  • 1
    I like the thought of the language tags <java></java>. – gobernador Aug 9 '12 at 17:35
  • 8
    But why invent a new syntax when several existing Markdown implementations already support the triple backtick syntax? Interoperability (and copy-pastability) with other Markdown flavors is a big plus IMHO! – Mathias Bynens Aug 9 '12 at 19:05
  • @MathiasBynens as I explained, with multiple code blocks delimited by ``` separated by a line or two of text (as is common on Stack Overflow) it could get very confusing trying to determine which ``` are starting a code block, and which are ending a code block-- or rather, which lines are code and which are text. – Brad Mace Aug 9 '12 at 19:08
  • 3
    @bemace There would be no confusion if the existing Markdown implementations that support this syntax are followed. Triple backtick code blocks need two line breaks before and after (unless they’re at the start or end of the input). – Mathias Bynens Aug 16 '12 at 8:06
  • 4
    @BradMace, It's actually even more confusing to invent a New Syntax if there's no substantial improvement. There's more people using Github than SE, no harm just following. – Pacerier Feb 18 '16 at 20:22

You must log in to answer this question.

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