How to Write Code Blocks and Inline Code in Markdown

calendar Sep 25, 2025  · Technical Writing Documentation Markdown Writing Tips Content Creation  ·
Share on: linkedin copy

Technical writers often need to embed code in their articles, whether snippets, configurations, commands, or examples. When presented clearly, code in your articles reinforces understanding and helps readers follow along more easily. When presented poorly, it creates confusion and frustration. This article demonstrates how to use inline code and code blocks effectively in Markdown, ensuring your code is readable, maintainable, and helpful to your audience.

Illustration of writinig code blocks and inline code in Markdown

Why code presentation matters

  • Makes examples easier to read and follow.
  • Helps readers reproduce commands without mistakes.
  • Enables tools such as syntax highlighters and linters to provide better feedback.
  • Simplifies version control, collaboration, and reuse.

Inline code vs code blocks

Markdown supports two ways of showing code:

  • Inline code (code spans): Wrap code in single backticks (`) for cmdlet names, variables, or file names within sentences. Example: "Use the `Get-Process` cmdlet to list processes."
  • Code blocks (code fences): Use triple backticks (```) to format multi-line code. Specify a language tag (e.g. ```powershell) to enable syntax highlighting.
Use Case Inline (code span) Code Block
Cmdlet, variables, or file names in text Yes —
One-line command Depends on length Yes
Multi-line command, script, or configuration — Yes
Code requiring indentation or alignment — Yes

Code block types and syntax highlighting

The PowerShell Docs style guide references three different types of code blocks, two of which are included in this article:

  • Syntax blocks: Show the structure of a command and its parameters. They aren't meant to be run as-is, so don't include a language tag.
  • Example blocks: Show runnable code. Always include a language tag (for example, powershell).

Specifying the language provides syntax highlighting, which helps with:

  • Distinguishing keywords, strings, and comments.
  • Understanding structure, such as loops or conditionals.
  • Spotting errors like unmatched braces or quotes.

Markdown examples

Syntax block (no language tag):

1``` 2Get-Command [-Name] <String[]> [-Module <String[]>] [<CommonParameters>] 3```

Example block (with language tag):

1```powershell 2# Example: list commands in the Microsoft.PowerShell.Management module 3Get-Command -Module Microsoft.PowerShell.Management 4```

Output block:

1```Output 2CommandType Name Version Source 3----------- ---- ------- ------ 4Cmdlet Add-Content 7.0.0.0 Microsoft.PowerShell.Management 5... 6```

Note: Output is not a standard language tag in most publishing platforms. If it isn't supported on your platform, use a code block without a language tag, or use a supported tag that avoids syntax highlighting (such as text or console, depending on your platform).

Formatting and annotating code blocks

To make code blocks more useful:

  • Include comments in the code to explain non-obvious parts.
  • Describe outputs or show expected results in a separate fenced code block without syntax highlighting.
  • Break up long lines to avoid horizontal scrolling or wrapping.
  • Ensure consistent indentation (spaces instead of tabs, commonly four spaces).
  • Add context before or after the code block to explain what it does, when to run it, and what prerequisites apply.

Code examples

Before running the following code, ensure that you have PowerShell 7 or later installed.

 1function Get-Greeting {  2 [CmdletBinding()]  3 param (  4 [Parameter(Mandatory)]  5 [string]$Name  6 )  7  8 # Return a greeting message for the given name  9 Write-Output "Hello, $Name!" 10} 11 12# Example usage 13Get-Greeting -Name Alice 
1Hello, Alice!

Common pitfalls to avoid

  • Using long commands in inline code instead of a code block.
  • Mixing tabs and spaces, which causes alignment problems.
  • Labeling code blocks with the wrong language.
  • Including prompts (PS C:\>) that make examples more difficult to copy and paste.
  • Overloading code with comments that restate the obvious.

Summary

When writing code examples in Markdown, keep these principles in mind:

  • Use inline code for short references and code blocks for longer commands or scripts.
  • Label runnable examples with a language tag (except syntax-only blocks).
  • Keep formatting clean: consistent indentation, short lines, and no mixed tabs/spaces.
  • Provide context before and after code so readers know when and how to use it.
  • Show command output separately where it improves clarity.
  • Use comments sparingly, focus on why, not what.

Inline code and code blocks are more than formatting choices. They shape how readers understand, trust, and apply your examples. Clear, consistent formatting makes your documentation clearer, more accurate, and easier to maintain.

References

Technical writing series