How to include code in documentation

There are several ways other than screenshots to include code in an article published on Microsoft Learn:

• Individual elements (words) within a line.

  Here's an example of code style.

  Use code format when referring to named parameters and variables in a nearby code block in your text. Code format may also be used for properties, methods, classes, and language keywords. For more information, see Code elements later in this article..

• Code blocks in the article Markdown file.

      ```csharp
      public static void Log(string message)
      {
          _logger.LogInformation(message);
      }
      ```
  

  Use inline code blocks when it's impractical to display code by reference to a code file. For more information, see Code blocks later in this article.

• Code blocks by reference to a code file in the local repository.

  :::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
  

  For more information, see In-repo snippet references later in this article.

• Code blocks by reference to a code file in another repository.

  :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
  

  For more information, see Out-of-repo snippet references later in this article.

• Code blocks that let the user execute code in the browser.

  :::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
  

  For more information, see Interactive code snippets later in this article.

Besides explaining the Markdown for each of these ways to include code, the article provides some general guidance for all code blocks.

Code elements

A "code element" is a programming language keyword, class name, property name, and so forth. It's not always obvious what qualifies as code. For example, NuGet package names should be treated as code. When in doubt, see Text formatting guidelines.

Inline code style

To include a code element in article text, surround it with backticks (`) to indicate code style. Inline code style shouldn't use the triple-backtick format.

When an article is localized (translated into other languages), text styled as code is left untranslated. If you want to prevent localization without using code style, see Non-localized strings.

Bold style

Some older style guides specify bold for inline code. Bold is an option when code style is so obtrusive as to compromise readability. For example, a Markdown table with mostly code elements might look too busy with code styling everywhere. If you choose to use bold style, use non-localized strings syntax to make sure that code is not localized.

Links

A link to reference documentation may be more helpful than code format in some contexts. If you use a link, don't apply code format to the link text. Styling a link as code can obscure the fact that the text is a link.

If you use a link and refer to the same element later in the same context, make the subsequent instances code format rather than links. For example:

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

Rendered:

The first reference to System.CommandLine in this text is a link. Subsequent references to System.CommandLine can be in code style.

Placeholders

If you want the user to replace a section of displayed code with their own values, use placeholder text marked off by angle brackets. For example:

az group delete -n <ResourceGroupName>

You may note that the brackets must be removed when substituting real values. The Microsoft Writing Style Guide calls for italics, which you may format within angle bracketed inline code:

<ResourceGroupName> is the resource group where...

Curly braces { } are discouraged for use as syntactical placeholders. They may be confused with the same notation used in replaceable text, format strings, string interpolation, text templates, and similar programming constructs.

Placeholder names can be separated by hyphens ("kebab case"), with underscores, or not separated at all (Pascal case). Kebab case may generate syntax errors and underscores may conflict with underlining. All-caps may conflict with named constants in many languages, though it may also draw attention to the placeholder name.

<Resource-Group-Name> or <ResourceGroupName>

Code blocks

The syntax for including code in a doc depends on where the code is located:

• In the article Markdown file
• In a code file in the same repository
• In a code file in a different repository

Following are guidelines that apply to all three types of code blocks:

• Screenshots
• Automate code validation
• Highlight key lines of code
• Avoid horizontal scroll bars
• Clearly identify bad code

Screenshots

All of the methods listed in the preceding section result in usable code blocks:

• You can copy and paste from them.
• They're indexed by search engines.
• They're accessible to screen readers.

These are just a few of the reasons why IDE screenshots aren't recommended as a method of including code in an article. Use IDE screenshots for code only if you're showing something about the IDE itself, like IntelliSense. Don't use screenshots just to show colorization and highlighting.

Code validation

Some repositories have implemented processes that automatically compile all sample code to check for errors. The .NET repository does this. For more information, see Contributing in the .NET repository.

If you are including code blocks from another repository, work with the owners on a maintenance strategy for the code so that your included code does not break or go out of date as new versions of the libraries the code uses are shipped.

Highlighting

Snippets typically include more code than necessary in order to provide context. It helps readability when you highlight the key lines that you're focusing on in the snippet, as in this example:

You can't highlight code when you include it in the article Markdown file. It works only for code snippets included by reference to a code file.

Horizontal scroll bars

Break up long lines to avoid horizontal scroll bars. Scroll bars on code blocks make code hard to read. They're especially problematic on longer code blocks, where it may be impossible to see the scroll bar and the line you want to read at the same time.

A good practice for minimizing horizontal scroll bars on code blocks is to break up code lines longer than 85 characters. But keep in mind that the presence or absence of a scroll bar isn't the only criterion of readability. If breaking a line before 85 hurts readability or copy-paste convenience, feel free to go over 85.

Clearly identify bad code

In some scenarios, it's helpful to point out coding patterns that should be avoided, for example:

• Code that will cause a compiler error if attempted.
• Code that will compile correctly but is not recommended.

For these scenarios:

• Explain the error both in code comments and article text.

  Readers often skip article text and look only at code, so it's not enough to explain the error only in article text. It's also not enough to explain the error only in code comments, because code comments aren't localized.

• Consider commenting out the code if it would cause a compiler error.

  Commented-out code won't disrupt the continuous integration (CI) system if the article's repo has one now or implements one in the future.

For an example of how to present code that isn't recommended, see Rune usage example: changing letter case. In this example, the advice to avoid it is even built into the code itself, as the C# method name is ConvertToUpperBadExample.

Inline code blocks

Use inline code blocks only when it's impractical to display code by reference to a code file. Inline code is generally more difficult to test and keep up to date compared to a code file that is part of a complete project. And inline code may omit context that could help the developer to understand and use the code. These considerations apply mainly to programming languages. Inline code blocks can also be used for outputs and inputs (such as JSON), query languages (such as SQL), and scripting languages (such as PowerShell).

There are two ways to indicate a section of text in an article file is a code block: by fencing it in triple-backticks (```) or by indenting it. Fencing is preferred because it lets you specify the language. Avoid using indentation because it's too easy to get wrong and it may be hard for another writer to understand your intent when they need to edit your article.

Language indicators are placed immediately after the opening triple-backticks, as in the following example:

Markdown:

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

Rendered:

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

For information about the values you can use as language indicators, see Language names and aliases.

If you use a language or environment word after the triple-backticks (```) that isn't supported, that word appears in the code section title bar on the rendered page. Whenever possible, use a language or environment indicator in your inline code blocks.

In-repo snippet references

The preferred way to include code snippets for programming languages in docs is by reference to a code file. This method gives you the ability to highlight lines of code and makes the wider context of the snippet available on GitHub for developers to use. You can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the help of the Learn Authoring Pack.

1. In Visual Studio Code, click Alt + M or Option + M and select Snippet.
2. Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference. To search locally, select Full Search.
3. Enter a search term to find the file. Once you've found the file, select the file.
4. Next, select an option to determine which line(s) of code should be included in the snippet. The options are: ID, Range and None.
5. Based on your selection from Step 4, provide a value if necessary.

Display entire code file:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

Display part of a code file by specifying line numbers:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Display part of a code file by specifying a snippet name:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

The following sections explain these examples:

• Use a relative path to the code file
• Include only selected line numbers
• Refer to a named snippet
• Highlight selected lines

For more information, see Snippet syntax reference later in this article.

Path to code file

Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

The example is from the ASP.NET docs repo, aspnetcore/data/ef-mvc/crud.md article file. The code file is referenced by a relative path to aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs in the same repository.

Selected line numbers

Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

This example displays only lines 2-24 and 26 of the StudentController.cs code file.

Prefer named snippets over hard-coded line numbers, as explained in the next section.

Named snippet

Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Use only letters and underscores for the name.

The example displays the snippet_Create section of the code file. The code file for this example has snippet tags in comments in the C# code:

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

Named code snippets can be nested, as shown in the following example:

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

When the Method code snippet is rendered, the Line tags aren't included in the rendered output.

Whenever you can, refer to a named section rather than specifying line numbers. Line number references are brittle because code files inevitably change in ways that make line numbers change. You don't necessarily get notified of such changes. Your article eventually starts showing the wrong lines and you have no clue anything has changed.

Highlighting selected lines

Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

The example highlights lines 2 and 5, counting from the start of the displayed snippet. Line numbers to highlight don't count from the start of the code file. In other words, lines 3 and 6 of the code file are highlighted.

Out-of-repo snippet references

If the code file you want to reference is in a different repository, set up the code repository as a dependent repository. When you do that, you specify a name for it. That name then acts like a folder name for purposes of code references.

For example, the docs repository is Azure/azure-docs, and the code repository is Azure/azure-functions-durable-extension.

In the root folder of azure-docs, add the following section in .openpublishing.publish.config.json:

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

Now when you refer to samples-durable-functions as if it were a folder in azure-docs, you're actually referring to the root folder in the azure-functions-durable-extension repository.

You can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the help of the Learn Authoring Pack.

1. In Visual Studio Code, click Alt + M or Option + M and select Snippet.
2. Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference. To search across repositories, select Cross-Repository Reference.
3. You will be given a selection of repositories that are in .openpublishing.publish.config.json. Select a repository.
4. Enter a search term to find the file. Once you've found the file, select the file.
5. Next, select an option to determine which line(s) of code should be included in the snippet. The options are: ID, Range and None.
6. Based on your selection from Step 5, provide a value.

Your snippet reference will look like this:

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

In the azure-functions-durable-extension repository, that code file is in the samples/csx/shared folder. As noted earlier, line numbers for highlighting are relative to the start of the snippet rather than the start of the file.

Snippets in a Jupyter notebook

You can reference a cell in a Jupyter notebook as a code snippet. In order to reference the cell:

1. Add cell metadata to the notebook for the cells you wish to reference.
2. Set up access to the repository.
3. Use Jupyter notebook snippet syntax in your markdown file.

Add metadata to notebook

1. Name the cell by adding cell metadata in the Jupyter notebook.

   • In Jupyter, you can edit cell metadata by first enabling the the cell toolbar: View > Cell Toolbar > Edit Metadata.
   • Once the cell toolbar is enabled, select Edit Metadata on the cell you wish to name.
   • Or you can edit metadata directly in the notebook's JSON structure.

2. In the cell metadata, add a "name" attribute:

   "metadata": {"name": "<name>"},
   

   For example:

   "metadata": {"name": "workspace"},
   

   Tip

   You can add any other metadata you'd like to help you track where the cell is being used. For example:

       "metadata": {
         "name": "workspace",
         "msdoc": "how-to-track-experiments.md"
       },
   

Set up repository access

If the notebook file you want to reference is in a different repository, set up the code repository as a dependent repository.

Jupyter notebook snippet syntax reference

Once your notebook contains the required metadata, reference it in your markdown file. Use the <cell-name-value> you added to the notebook, and the <path> you set up as your dependent repository.

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

For example:

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

Use any of the supported languages for the <language> identifier.

Interactive code snippets

Inline interactive code blocks

For the following languages, code snippets can be made executable in the browser window:

• Azure Cloud Shell
• Azure PowerShell Cloud Shell
• C# REPL

When interactive mode is enabled, the rendered code boxes have a Try It or Run button. For example:

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

renders as follows:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

renders as:

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

To turn on this feature for a particular code block, use a special language identifier. The available options are:

• azurepowershell-interactive - Enables the Azure PowerShell Cloud Shell, as in the preceding example
• azurecli-interactive - Enables the Azure Cloud Shell
• csharp-interactive - Enables the C# REPL

For the Azure Cloud Shell and PowerShell Cloud Shell, users can run commands against only their own Azure account.

Code snippets included by reference

You can enable interactive mode for code snippets included by reference. To turn on this feature for a particular code block, use the interactive attribute. The available attribute values are:

• cloudshell-powershell - Enables the Azure PowerShell Cloud Shell, as in the preceding example
• cloudshell-bash - Enables the Azure Cloud Shell
• try-dotnet - Enables Try .NET
• try-dotnet-class - Enables Try .NET with class scaffolding
• try-dotnet-method - Enables Try .NET with method scaffolding

Here are some examples:

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

For the Azure Cloud Shell and PowerShell Cloud Shell, users can only run commands against their own Azure account.

For the .NET Interactive experience, the contents of your code block depends on which of the three scaffolding experiences you choose:

• No scaffolding (try-dotnet): The code block should represent a full program text. For example, the Program.cs file generated by dotnet new console would be valid. These are most useful to show an entire small program, including the using directives needed. Top level statements are not supported at this time.
• Method scaffolding (try-dotnet-method): The code block should represent the content of a Main method in a console application. You can assume the using directives added by the dotnet new console template. This setting is most useful for short snippets that demonstrate one feature.
• Class scaffolding (try-dotnet-class): The code block should represent a class with a Main method as the program entry point. These can be used to show how members of a class interact.

Snippet syntax reference

Syntax:

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

• <language> (optional)

  • Language of the code snippet. For more information, see the Supported languages section later in this article.

• <path> (mandatory)

  • Relative path in the file system that indicates the code snippet file to reference.

• <attribute> and <attribute-value> (optional)

  • Used together to specify how the code should be retrieved from the file and how it should be displayed:
    • range: 1,3-5 A range of lines. This example includes lines 1, 3, 4, and 5.
    • id: Create The ID of the snippet that needs to be inserted from the code file. This value cannot coexist with range.
    • highlight: 2-4,6 Range and/or numbers of lines that need to be highlighted in the generated code snippet. The numbering is relative to the lines displayed (as specified by range or id), not the file.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method String value determines what kinds of interactivity are enabled.
    • For details about tag name representation in code snippet source files by language, see the DocFX guidelines.

Supported languages

The Learn Authoring Pack includes a feature to provide statement completion and validation of the available language identifiers for code fence blocks.

Fenced code blocks

Next steps

For information on text formatting for content types other than code, see Text formatting guidelines.