28

I've seen countless posts where using Markdown blocks has been "wacky".

Many of these posts used citation blocks for error logs, for example, while others used bold or italics. Some also use the code block to declare the paths, addresses, and logs.

In all of this, what is the correct use of blocks?

In which block should the logs be inserted?

When and how should citation blocks be used?

In order to decrease the confusion, should we intervene modifying the posts?

13
  • Closely related, about error logs: meta.stackoverflow.com/questions/286706/…
    – 0Valt
    Commented Sep 23, 2020 at 11:27
  • 12
    Code is basically the equivalent of unformatted text, whereas Quote is just fancy normal text. If a log contains anything that may be sensitive to formatting (alignment, special characters, ...) it should be code. Commented Sep 23, 2020 at 11:28
  • 2
    Agreed, judging from experience, if an error is a one-liner "cannot read [prop] of undefined" (for example), it is easier to read as a quote (easier to parse visually), whereas it makes sense to format as code when the asker dumps the whole stack trace for the error along the way.
    – 0Valt
    Commented Sep 23, 2020 at 11:31
  • 2
    error output and logs should be formatted as code if it's a stacktrace or anything else where it's extremely useful for the output lines to be after each other instead of soft wrapped with no hard newlines. For cases where it isn't as important, either is fine, but there's some cases where a code block should be preferred over quotes. really case-dependent, so it's really enough to compare readability. Commented Sep 23, 2020 at 11:31
  • 23
    Things that should not ever be wrapped in code syntax highlighting: names of libraries or frameworks in prose, e.g. "I'm using jQuery".
    – TylerH
    Commented Sep 23, 2020 at 13:08
  • @Zoe just like normal text, quote blocks can force line breaks using two spaces followed by a carriage return. See Line breaks section in this answer.
    – user692942
    Commented Sep 23, 2020 at 13:39
  • 3
    @Lankymart which would you rather though: append 2 spaces to every line in a relatively long stacktrace, or just use a code block? Code blocks are also guaranteed to render properly on mobile, where as quotes wrap text on small enough screens Commented Sep 23, 2020 at 13:42
  • @Zoe agree just pointing out that quote blocks do support hard breaks. Personally I only use quote blocks for error messages (not stack traces or dumps) and code, logs etc I use a variation of the code block via syntax highlighted or lang-none for logs.
    – user692942
    Commented Sep 23, 2020 at 13:55
  • 1
    Judging by what I have seen in several questions recently, the correct way to format code is using a block quote, because if you post it as code, the system tells you to trim down your code and add some explanatory text, whereas if you post it as a quote, it's not code and thus evades the quality checker and let's you post your code dump with no effort and no explanation! Hooray! Commented Sep 24, 2020 at 1:33
  • I dislike word should. You just need some amount of common sense and learning by looking at what other users do. If you do it wrong, your post/edits will be rejected/rollback/edited. We do not need strict instructions on when to use something and when not.
    – Sinatr
    Commented Sep 24, 2020 at 7:04
  • 1
    @Sinatr, as I said in the question, some users do wacky things and got their answers. So, being in the same website, maybe we should use the same "dictionary", the same writing style to be more understandable (this is the keyword😀)
    – Deleter
    Commented Sep 24, 2020 at 8:51
  • We already do. First of all there is not so much you can do with formatting. I am totally fine if user put his error inside code block as well as quote block, or when he highlight something important like this or like this once or twice (too much - and it will become less readable). There are hidden features, but not many knows about them. So why bother? Why create rules and think where to put them if there is no problem? Or do you have some concrete "wacky" post for us to have a look?
    – Sinatr
    Commented Sep 24, 2020 at 9:15
  • Many to show, many I edited for these reasons (and then the posts were deleted). Some users used citation blocks, others italics, others bold. it is true that perhaps putting too many rules is wrong, but I think even more that it is necessary to discourage the use of blocks randomly. If it quack as a duck, then it's a duck ergo, why use a quote block if it's a code?😂
    – Deleter
    Commented Sep 24, 2020 at 10:27

5 Answers 5

33

Code (be it snippets, complete code blocks, or identifiers as defined by each language but that are interspersed with regular text) should be formatted as code. So should file paths and file names.

For error/standard output and logs, it is a bit less defined. While some users strongly prefer quotes or code-blocks; I personally think it depends on the type of output/error log; which is very technology/tag dependent.

I've seen a lot of error logs in the web side of technology were formatting them as code is simply very bad by hindering readability without adding any additional detail (even when the user remembers to use lang=none).

But for certain technologies or even for specific questions, simply formatting the error or output as a quote instead of monospaced code can hide the necessary details to diagnose the issue.

In my experience, these preferences are more or less consistent within each tag, so trying to set any hard site-wide rule would not be very useful.

If possible, I always try to avoid anything that would force the reader to use horizontal scrolling, which has a really nasty impact on readability. Which means that that for long error messages where I know preserving spacing is not essential, I would use block-quotes.

For example:

Deprecation Notice: Class Foo\Bar\Baz located in ./foo/bar/Baz.php does not comply with psr-4 autoloading standard. It will not autoload anymore in Composer v2.0. in phar:///usr/local/bin/composer/src/Composer/Autoload/ClassMapGenerator.php:201

On the other hand, if the output is multiline, and I believe including all the original spacing would make the result more readable (or even that not including the original output would make debugging the problem harder), I will just use an unformatted code-block:

Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   src/Domain/Entity/Lead
    new file:   src/Domain/Entity/PartnerUser

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   src/Domain/Entity/PartnerProfile

So in essence, it depends. Users should use their own judgement to style the output as faithfully as possible; while trying to preserve readability as much as they can. If they get it wrong, hopefully other users can help with edits to get the best possible result.

11
  • 3
    I usually like to put error messages as code inside a quote block to help highlight that it is not my content but rather a response that I'm quoting, which I think is the most important distinction for error messages. Though indeed if the error message isn't a stack trace or something where code formatting is critical, then I just wrap it in a quote block.
    – TylerH
    Commented Sep 23, 2020 at 13:07
  • Please don't put error messages that has multiple lines in quote blocks. It's completely unreadable. The errors are almost always easy to skim when they're put into a proper code block.
    – Scratte
    Commented Sep 23, 2020 at 13:17
  • @Scratte You realise that a quote block can do multiple lines just remember to leave two spaces after a carriage return.
    – user692942
    Commented Sep 23, 2020 at 13:19
  • @Lankymart I just tried. It doesn't seem to adhere to the carriage return at all. No matter how many spaces I put after each line. I mean it does.. until one decides to put in into a quote.
    – Scratte
    Commented Sep 23, 2020 at 13:23
  • 1
    @Scratte Sorry meant to say two spaces followed by a carriage return, see the edit here.
    – user692942
    Commented Sep 23, 2020 at 13:29
  • 1
    There's a comprehensive list here.
    – user692942
    Commented Sep 23, 2020 at 13:35
  • @Lankymart I cannot see the actual commonMark as I do not have edit privileges. But I tried this: Just normal, then two spaces at the end of each line which was fine until I marked it and pressed the quotes that messed up the lines to only having 5 lines, not 9. Un-quoting them made it even worse, not bringing it back to the way it was.
    – Scratte
    Commented Sep 23, 2020 at 13:39
  • 1
    @Scratte don't use the quote block tool to convert it, just start with > then past your lines adding two spaces at the end of each line you want to break.
    – user692942
    Commented Sep 23, 2020 at 13:43
  • @Lankymart That seems to make a big difference :) Unfortunately most of the errors in quotes I see on main is really just a big.. mess. Likely due to the tool.
    – Scratte
    Commented Sep 23, 2020 at 13:47
  • 1
    @Scratte personally I'd use code block with lang-none for logs and large errors (stack traces). If it's just a one or two line error message I use a quote block.
    – user692942
    Commented Sep 23, 2020 at 13:58
  • How about a code block inside a quote block? I've done that one before... Commented Sep 24, 2020 at 14:47
27

When in doubt, prefer code formatting for technical content such as file paths, tracebacks, or logs.


Quote style is basically fancy but regular text. Any content that purposely or accidentally matches markdown or html will be interpreted. All alignment and whitespace will be lost, and replaced with standard text alignment and wrapping.

This is only adequate when you know that no relevant information is lost.

Code style is unformatted, monospace text. Especially with lang=none, content is displayed as-is without any misinterpretation or reformatting (*). This also allows to copy/paste content for displaying in an external viewer as per preference.

This is always a safe default for any technical content.


(*) Notwithstanding what the wizard does, e.g. replacing tabs with spaces.

9
  • Seems a lot of people here don't understand how quote blocks can be used. It will only wrap text if you don't place a hard carriage return followed by two spaces, but most people are either too lazy or just don't know it's possible.
    – user692942
    Commented Sep 23, 2020 at 13:22
  • @Lankymart Do you mean \n or \r ? \n did not work to enforce linebreaks inside quote blocks for me. Commented Sep 23, 2020 at 13:25
  • See edit I just made.
    – user692942
    Commented Sep 23, 2020 at 13:28
  • @Lankymart Thanks for the clarification. Note that this is not specific to quote formatting, it will work in regular text as well. Commented Sep 23, 2020 at 13:30
  • I know, but like I say it can be used in quote blocks.
    – user692942
    Commented Sep 23, 2020 at 13:31
  • 11
    "When in doubt, prefer code formatting" ... for error messages, code, file paths. Not for anything else. I spend entirely too much time cleaning up other people's edits to add code formatting to words that are not code (like names of programing languages, libraries, frameworks, etc.). Commented Sep 23, 2020 at 13:48
  • @HereticMonkey Good point. Adjusted the wording. Commented Sep 23, 2020 at 13:49
  • Yeah. Saw a testcase in a document that said: "4. Return to your Windows machine" Just what Commented Sep 24, 2020 at 13:51
  • 3
    I'd add that not using code formatting for quotes/etc isn't just an aesthetic thing. Tools like screen readers change how they read content if it's marked as code and the experience is said to be awful. Commented Sep 24, 2020 at 15:13
5

I'll go for a "rule of thumb" approach:

  • Code blocks (created by three backticks, new line, code, new line, three backticks ```) should be used for any content that may be displayed in a code editor or terminal. This includes:
    • Code, of course
    • Program or terminal output
    • Stack traces and log files

Here's an example of something you want to wrap in a code block. You may run with an error like:

curl: command not found
  • Code snippets (the ones with the Run button) should be used for complete, runnable HTML/JS code examples. This is also important, I've seen this type of snippets used for unsupported languages or incomplete examples, which makes the Run button totally useless. In these cases, a code block is required.
  • Blockquotes should be used, well, for quoting. This means citing text from a website, or documentation. Always cite the source.

Here's an example, extracted from Docker LABEL instruction reference:

The LABEL instruction adds metadata to an image. A LABEL is a key-value pair. To include spaces within a LABEL value, use quotes and backslashes as you would in command-line parsing.

  • Inline code (created wrapping the text between two backticks ``) should be used for any relevant word or statement that is inlined with your explanations and that on its own should belong to a code block, this is, variable names, method calls, terminal commands, etc.

For example:

You cannot use printf to print text directly to a file. You should first create a FILE * pointer using fopen (see fopen manpage) and then call fprintf as you would with printf but passing the created file pointer as the first argument (see fprintf manpage)

2
  • I completely agree. This should be the correct way to approach formatting in my opinion. As for inline code, we are told not to use it to define languages, libraries and packages ... is that correct?
    – Deleter
    Commented Sep 26, 2020 at 5:44
  • 1
    Yeah. I won't really mind if you inlined a package name, same for filenames, like saying "I am modifying my package.json to include the package @angular/http". It is a good way to highlight relevant technical content. But I see saying "I am modifying my package.json to include the package @angular/http" just as valid. So I guess this case is more up to user's preference, there is not an universal way of formatting. Commented Sep 26, 2020 at 21:33
2

In order to decrease the confusion, should we intervene modifying the posts?

If someone has monospaced console output or a stack trace that isn't formatted as code (this question is a good example of doing it correctly), please do edit it to fix it. There is agreement that text that was designed to be read in a monospaced font should stay that way so a suggested edit fixing that should get approved.

Likewise, a suggested edit to change a non-monospaced error message from plain/italic/bold text to either code or quote formatting should get approved.

I would not suggest an edit to change a non-monospaced error message from quote formatting to error code or vice versa, even if you think the change improves readability. There isn't consensus on this matter (personally, quote formatting for anything that's not a quote makes me itch) so it's likely that an edit switching between the two would be seen as no improvement.

Other things that should be safe in suggested edits:

  • Adding quote formatting to actual quotes
  • Removing quote formatting that's just used for emphasis
  • Removing code formatting that's just used for emphasis
-13

Only when it makes sense, if that makes sense. Code blocks only makes sense when you are posting a block of code, same with quotes (you are quoting something).

From another angle you can say do not use formatting at all, unless it is absolutely necessary. Judicious use of formatting makes post easier to read, meanwhile unnecessary use of formatting achieve the exact opposite.

5
  • 14
    Stuff only makes sense if you understand when they're meant to be used. Doesn't help people who don't understand when they're meant to be used, because they don't have a concept of when it makes sense Commented Sep 23, 2020 at 13:57
  • @Zoe but then you get into the argument that "what is code" and should all code be formatted as code. I prefer not to use formatting unless you know that it would be used correctly. The list of where it should be used and where shouldn't is way too long.
    – Braiam
    Commented Sep 23, 2020 at 14:32
  • 4
    That's the wrong equivalent though. The equivalent here that makes sense is to people new to coding who have no idea what ints, strings, floats, and bools are, and then you ask them to pick one they feel is correct for storing a specific type of data. They have no idea what the difference is, so they can't use their intuition, and have to guess instead. "what is code" isn't the relevant argument, but what should be formatted as code in addition to code is. And some people are gonna try to format, even if it ends up being wrong, rather than doing nothing, in part because (1/2) Commented Sep 23, 2020 at 15:10
  • 4
    the ask page includes formatting hints. What you do isn't always representative of what everyone does, hence why this question needs a better answer than this outright trash Commented Sep 23, 2020 at 15:11
  • @Zoe no. What make trash is that we throw text to the users, and when that doesn't work, we throw even more text. That is utterly garbage. Never worked, and the fact that this question exist at all is a living testament of that. You can go to your couch thinking that it made a difference, but it doesn't. The best formatting advice anyone can give you in the internet is do not use any at all.
    – Braiam
    Commented Sep 23, 2020 at 19:52

You must log in to answer this question.

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