Skip to main content

Formatting text and code

Don’t use screenshots of text

Using a screenshot to show code and text is almost never a good idea. This has been thoroughly discussed, and you should read a full list of problems with screenshots to understand why this is important. Instead of posting screenshots of code, you should copy and paste any relevant code and text into the question and format it so that it’s easy for others to read, copy, and search.

There are some times when screenshots are helpful, such as showing how your application is not rendering as expected, or any time a simple copy and paste will not preserve the information you need to present. You may want to show both a screenshot and copied text, if the screenshot adds important information to the text.

Learn to use Markdown effectively

Stack Overflow uses Markdown to enable you to format the content of your questions and answers. There is a markdown reference you can use for common formatting tasks. We strongly recommend you learn how to use Markdown, not just because it makes your content easier to read on Stack Overflow, but also because you will likely continue to use it in other places, such as GitHub READMEs, and Docusaurus content.

The following are some specific Markdown tips that we feel are especially useful for formatting questions.

Use triple backticks (```) for multi-line code blocks

The easiest way to format some block of code is to paste it into a “code fence” with triple backticks on their own lines to mark the start and end of the code.

Paste your code here between the fences.

Note that a backtick character ` (typically located in the upper left of your keyboard) is different from the apostrophe character ' (located near the return key).

For even better formatting, you can also specify the language of the code in the fence. This helps source code coloring and makes your code easier to read. For example, to specify that code is JavaScript:

console.log("Code fences with source coloring are much easier to read");

Use triple backticks (```) for stack traces and formatted text

If there is some text you want to show that should preserve its formatting, also use a code fence for that. Stack traces are a good example, as is tabular output from things like SQL queries.

Use a blockquote (>) for long error messages

Using a code fence for long lines requires the reader to scroll the block horizontally, which makes it harder to read. Instead, use a blockquote to make it clear that you are quoting some text, and also allow all of the text to be readable on screen with minimal effort.

Here is what a long message looks like in a code fence:

ServiceException: 401 Anonymous caller does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).

Can you read the entire message? How much work did you put into doing that? Probably more than you'd prefer. There should be no need to scroll horizontally to read all of it.

Here is what the same message looks like when formatted as a blockquote:

ServiceException: 401 Anonymous caller does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).

Note that you can now easy to read the entire message without putting in any work.

You can format text using a blockquote by simply prefixing the the line with > . The Stack Overflow editor also allows you to select some text to format using the blockquote button (it looks like a fat quotation mark).

Use a blockquote (>) for quoting others’ text

If you are copying someone else’s text from a website or other source, use a blockquote for that to be clear that they are not your words.

Use cmd/ctrl-K to adjust the indentation of your code

If you copy/paste the code from your regular editor into Stack Overflow, it may be more deeply indented than needed. This can make it difficult to read, as longer lines will require horizontal scrolling. To make it easier to read, you can select the code block, and then press ctrl-K (cmd-K on macOS) to reduce the indentation and shorten the length of each line.

Follow relevant code style conventions

Make sure your code uses common indentation and style conventions for the language you're using. If your code doesn't for any reason, consider using code formatting tools to update it. For example, is a simple, online tool to normalize the indentation of a piece of JavaScript/JSON text.

Show files and directories with tree

When working with a directory structure, consider putting some effort into showing that as text rather than a screenshot. There is a handy tool called tree, which is a command line program that shows the entire structure of a directory as formatted text. The output it generates can be easily copied into a code fence, and is usually better than trying to take a screenshot of your IDE or file manager. There are many flavors of tree out there for different operating systems and languages. Here is what the output looks like for a small Node.js project using TypeScript:

├── dist
│ ├── index.js
│ └── kysely.js
├── node_modules
├── package-lock.json
├── package.json
├── src
│ ├── index.ts
│ └── kysely.ts
└── tsconfig.json

You can see how this clearly shows the structure of the project and where files are nested under directories, and doesn't require a problematic screenshot.

Use correct English grammar and punctuation

We strongly suggest that you proofread your content before posting it, which should make it easier for others to read. If your content doesn’t follow standard English conventions, readers might skip your question entirely because it’s too difficult to read, or even downvote it or vote to close it.

We understand that many people are not native speakers of English, which makes it more difficult. If you find yourself struggling with English, we recommend writing your question using a composition tool that checks grammar and spelling before copying it into Stack Overflow.

Google Docs is free and does a great job of checking English text. Consider writing the text of your question in Google Docs first, and use its suggestions to resolve any grammar and punctuation problems there. The downside is that Docs does not work well with code snippets, so it’s probably not worthwhile to try to format your minimal, complete, reproducible example with it.

Check your formatting before posting

Stack Overflow shows you the formatted content of your question or answer as you type it. It’s common for people to post their questions without checking the formatting - this runs the risk of making your post difficult to read, which means it’s more likely to be skipped and even downvoted.