9

Since the start of 2019, code fences have been fully supported on Stack Exchange sites. By code fences, I mean the use of opening and closing triple backticks to format a code block. The effect of this is the same as indentation (which continues to be fully supported). Writing this in the editor:

```
code
more code
and more code
```

produces:

code
more code
and more code

The purpose of this post is to point out some issues to be aware of relating to code fences.

Lost text

One of the nice, convenient features of code fences is that one can specify a language for syntax highlighting by writing the language name on the same line as and after the opening set of backticks. So, a Bash script can be syntax highlighted as such by writing something like this in the editor:

```bash
code
more code
even more code
```

If a question has a tag like or or , any code-formatted text in the question and its answers will automatically get syntax highlighted. You can turn this off by putting none after the opening backticks:

```none
stuff that should not be syntax highlighted
such as output from an APT command
```

So far, so easy and nice. But there is a pitfall here. Any text on the same line as the opening backticks will be hidden. Obviously that is good if the text is there to set or unset syntax highlighting, but, very often users put the first part of the text they want to show on the same line as the opening backticks. When this is what was entered

```the command I ran
the output
some more output
```

this is what gets displayed

the output
some more output

This is obviously bad. When you see a post that seems like it might have the first line of the code missing, check the markdown by clicking edit and see if this is what happened to it.

Endless code

Another issue can happen at the end of the fence. The closing set of backticks has to be on its own line. If it's trailing on the same line as some text that is part of the block you want to format, it is considered to be part of the code itself, and the block remains open (so anything that follows is also formatted as code, down to the next line that opens with three backticks)

a code block
that goes on```

and on, even though this text is not supposed to be code

A less common problem is using mismatched numbers of backticks. Three is the minimum number of backticks for creating a code fence, and as far as I know there is no maximum, so a line starting with four or five or eight consecutive backticks will open a code block, and the same number must be used to close the block, so

four backticks above this line
turned this into code
```
those three backticks failed to close the block
on it goes!
until I type four backticks under this line

Posts that were created before code fences were supported that have text on the line after the opening backticks display similarly to inline code, without the text being hidden. Viewing these posts in the editor or the revision history displays them as they would be displayed currently. Here is an example to illustrate that, as well as the lost text and endless code issues:

Here's part of a post:

multiline inline code from before code fences were supported

And here's the same post showing the markdown that produced the above, and in the preview, what that markdown would produce now that code fences are supported. Note that the first line of the code is hidden and the code block never ends, and because the image and link URLs at the end of the post are now code formatted, they do not display where they are referenced:

editor + preview

What are we doing about it?

Eliah Kagan pointed out this issue and wrote some code to parse the results of SEDE queries that find code fences like this one to find posts with code fence issues. When we started working on fixing these posts, that code found 659 results, including some false positives and things that did not actually need fixing. We are slowly working on editing them. If anyone is interested in joining in with that, come to the Downboat and we will give you some work. Also, the approach to finding the posts could be refined - this query times out on Stack Overflow and takes a long time to run on Ask Ubuntu, and presumably it could be possible to query directly only for broken code fences, not just all the code fences (we tried that, and it was hard). I am currently using this thing, although it doesn't work very well. Even after fixing these posts, it is highly likely that incorrectly formatted code fences will continue to appear and we will need to keep querying for them.

In the meantime, everyone can help by spotting and fixing these issues with posts whenever you happen to interact with them (for example in the First Posts, Late Answers and Suggested Edits queues, but also anywhere else).


TL;DR

  • Text on the same line as the three backticks (```) that open a code fence will be hidden. Only syntax highlighting specifications such as sh python none should be written there. The code you want to display should start on the line after the opening backticks.
  • Three backticks that trail on the same line as the last line of a code block do not close the code block, but instead become part of the code block, which continues after them. The closing backticks need to be on a new line after the block, and need to match the opening backticks in number.

Please watch out for these issues and correct them by editing if possible.

0

You must log in to answer this question.

Browse other questions tagged .