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

• Individual elements (words) within a line.

  Here's an example ofcode 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, seeCode 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, seeCode 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, seeIn-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, seeOut-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, seeInteractive code snippets later in this article.

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

Code elements

A "code element" is a programming language keyword, class name, property name, and so forth. It'snot always obvious what qualifies as code. For example, NuGet package names should be treated ascode. When in doubt, seeText 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 leftuntranslated. If you want to prevent localization without using code style, seeNon-localized strings.

Bold style

Some older style guides specify bold for inline code. Bold is an option when code style is soobtrusive as to compromise readability. For example, a Markdown table with mostly code elementsmight look too busy with code styling everywhere. If you choose to use bold style, usenon-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 toSystem.CommandLine in this text is a link.Subsequent references toSystem.CommandLine can be in code style.

Placeholders

If you want the user to replace a section of displayed code with their own values, use placeholdertext 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 includingcode in an article. Use IDE screenshots for code only if you're showing something about the IDEitself, 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 forerrors. The .NET repository does this. For more information,seeContributing in the .NETrepository.

If you are including code blocks from another repository, work with the owners on a maintenance strategy for the code so thatyour 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 helpsreadability when you highlight the key lines that you're focusing on in the snippet, as in thisexample:

You can't highlight code when you include it in the article Markdown file. It works only for codesnippets 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 toread. They're especially problematic on longer code blocks, where it may be impossible to see thescroll 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 lineslonger than 85 characters. But keep in mind that the presence or absence of a scroll bar isn't theonly criterion of readability. If breaking a line before 85 hurts readability or copy-paste convenience, feelfree 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, seeRune 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 isConvertToUpperBadExample.

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: byfencing itin triple-backticks (```) or by indenting it. Fencing is preferred because it lets you specifythe language. Avoid using indentation because it's too easy to get wrong and it may be hard foranother writer to understand your intent when they need to edit your article.

Language indicators are placed immediately after the opening triple-backticks, as inthe 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, seeLanguage 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 orenvironment 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 theLearn Authoring Pack.

1. In Visual Studio Code, clickAlt + M orOption + 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 andNone.
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":::

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, seeSnippet syntax reference later in thisarticle.

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.mdarticle file. The code file is referenced by a relative path toaspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.csin 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 theStudentController.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":::

Use only letters and underscores for the name.

The example displays thesnippet_Create section of the code file. The code file for this examplehas 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 theMethod code snippet is rendered, theLine tags aren't included in the rendered output.

Whenever you can, refer to a named section rather than specifying line numbers. Line numberreferences 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 wronglines 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. Linenumbers to highlight don't count from the start of the code file. In other words, lines 3 and 6of 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 coderepository as adependent repository. When you do that, you specify a name for it. That name thenacts like a folder name for purposes of code references.

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

In the root folder ofazure-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 tosamples-durable-functions as if it were a folder inazure-docs, you'reactually referring to the root folder in theazure-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 theLearn Authoring Pack.

1. In Visual Studio Code, clickAlt + M orOption + 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 andNone.
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 theazure-functions-durable-extension repository, that code file is in thesamples/csx/sharedfolder. As notedearlier, 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 canedit cell metadata by first enabling the the cell toolbar:View > Cell Toolbar > Edit Metadata.
   • Once the cell toolbar is enabled, selectEdit 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 adependent 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 thesupported 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 aTry It orRun button. Forexample:

    ```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. Theavailable options are:

• azurepowershell-interactive - Enables the Azure PowerShell Cloud Shell, as in the precedingexample
• 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 ownAzure 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 theinteractive attribute. Theavailable attribute values are:

• cloudshell-powershell - Enables the Azure PowerShell Cloud Shell, as in the precedingexample
• 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 ownAzure 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, theProgram.cs file generated bydotnet new console would be valid. These are most useful to show an entire small program, including theusing directives needed. Top level statements are not supported at this time.
• Method scaffolding (try-dotnet-method): The code block should represent the content of aMain method in a console application. You can assume theusing directives added by thedotnet 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 aMain 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 theSupported languagessection 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 theDocFX guidelines.

Supported languages

TheLearn 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, seeText formatting guidelines.