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 ```
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.
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 bash or scripts or java, 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.
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:
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:
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).
- Text on the same line as the three backticks (
```) that open a code fence will be hidden. Only syntax highlighting specifications such as
noneshould 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.