How to include code in docs

  • Article
  • nineteen minutes to read

There are several ways to include code in an article published on docs.microsoft.com:

  • Individual elements (words) within a line.

    Hither'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 likewise be used for properties, methods, classes, and language keywords. For more information, run into Lawmaking elements later in this article..

  • Code blocks in the article Markdown file.

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

    Use inline code blocks when it's impractical to display code past reference to a code file. For more than information, see Lawmaking blocks afterwards in this article.

  • Lawmaking 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 past 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 data, come across Out-of-repo snippet references later in this commodity.

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

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

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

Likewise explaining the Markdown for each of these means to include lawmaking, the article provides some full general guidance for all lawmaking blocks.

Code elements

A "code chemical element" is a programming language keyword, class proper name, property name, and so forth. Information technology's not ever obvious what qualifies as lawmaking. For example, NuGet package names should exist treated as code. When in doubt, see Text formatting guidelines.

Inline lawmaking style

To include a code element in article text, surroundings it with backticks (`) to indicate code mode. Inline code way shouldn't utilise the triple-backtick format.

Markdown Rendered
By default, the Entity Framework interprets a holding that's named `Id` or `ClassnameID` as the principal key. By default, the Entity Framework interprets a holding that's named Id or ClassnameID as the primary fundamental.

When an commodity is localized (translated into other languages), text styled as code is left untranslated. If you lot desire to prevent localization without using code style, run across Non-localized strings.

Bold way

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

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

If you lot apply a link and refer to the aforementioned element later in the aforementioned context, make the subsequent instances code format rather than links.

Placeholders

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

az grouping delete -due north <ResourceGroupName>

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

<ResourceGroupName> is the resource grouping where...

Curly braces { } are discouraged for employ every bit syntactical placeholders. They may be dislocated with the same note used in replaceable text, format strings, string interpolation, text templates, and similar programming constructs.

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

<Resources-Grouping-Name> or <ResourceGroupName>

Code blocks

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

  • In the commodity Markdown file
  • In a lawmaking file in the aforementioned repository
  • In a code file in a different repository

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

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

Screenshots

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

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

These are simply a few of the reasons why IDE screenshots aren't recommended as a method of including lawmaking in an article. Employ IDE screenshots for code only if you're showing something almost the IDE itself, like IntelliSense. Don't employ screenshots just to bear witness colorization and highlighting.

Lawmaking validation

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

If you are including code blocks from some other repository, work with the owners on a maintenance strategy for the lawmaking and then 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 club to provide context. It helps readability when you highlight the primal lines that yous're focusing on in the snippet, equally in this instance:

Example showing highlighted code

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

Horizontal scroll bars

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

A good practise 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 absenteeism of a curl bar isn't the only criterion of readability. If breaking a line before 85 hurts readability or copy-paste convenience, feel gratuitous to go over 85.

Clearly place 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 volition compile correctly but is non recommended.

For these scenarios:

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

    Readers often skip article text and expect only at code, and so information technology'due south not enough to explicate the fault only in article text. It's also not enough to explain the fault only in code comments, because code comments aren't localized.

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

    Commented-out lawmaking won't disrupt the continuous integration (CI) arrangement if the article'south repo has one now or implements one in the hereafter.

For an example of how to present code that isn't recommended, run into Rune usage example: changing letter case. In this case, the communication to avoid information technology is even congenital into the code itself, as the C# method proper noun is ConvertToUpperBadExample.

Inline code blocks

Use inline code blocks only when it's impractical to brandish code by reference to a code file. Inline lawmaking is generally more than hard 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 tin can too be used for outputs and inputs (such every bit 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: past fencing it in triple-backticks (```) or by indenting it. Fencing is preferred because information technology lets you specify the language. Avoid using indentation because information technology's too easy to go incorrect and it may be hard for some other author to understand your intent when they need to edit your commodity.

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

Markdown:

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

Rendered:

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

Tip

GitHub Flavored Markdown supports delimiting code blocks with tildes (~) as well every bit with backticks (`). The symbol used to open up and close the code block must exist consequent within the same code block.

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

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

Annotation

If you re-create and paste lawmaking from a Word document, make sure it has no "curly quotes," which aren't valid in code. If it does, change them back to normal quotes (' and "). Alternatively, rely on the Docs Authoring Pack, smart quotes replacement feature.

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 yous the ability to highlight lines of code and makes the wider context of the snippet available on GitHub for developers to utilize. Y'all can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the assistance of the docs.microsoft.com Authoring Pack.

  1. In Visual Studio Code, click Alt + M or Option + M and select Snippet.
  2. One time Snippet is selected, y'all 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 exist included in the snippet. The options are: ID, Range and None.
  5. Based on your selection from Footstep 4, provide a value if necessary.

Brandish unabridged lawmaking file:

              :::code linguistic communication="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="ii-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, meet Snippet syntax reference after in this commodity.

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/grime.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 aforementioned repository.

Selected line numbers

Example:

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

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

Adopt 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 messages and underscores for the name.

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

              // 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 post-obit case:

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

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

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

Highlighting selected lines

Case:

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

The case highlights lines 2 and 5, counting from the start of the displayed snippet. Line numbers to highlight don't count from the kickoff of the lawmaking file. In other words, lines 3 and half-dozen of the code file are highlighted.

Out-of-repo snippet references

If the lawmaking file y'all desire to reference is in a different repository, set up upward the code repository equally a dependent repository. When y'all exercise that, you specify a name for it. That name then acts similar a folder name for purposes of lawmaking 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 together the post-obit 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 yous refer to samples-durable-functions as if information technology 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 assist of the docs.microsoft.com Authoring Pack.

  1. In Visual Studio Lawmaking, click Alt + M or Pick + M and select Snippet.
  2. Once Snippet is selected, y'all will be prompted for Total 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 y'all've found the file, select the file.
  5. Side by side, select an option to determine which line(southward) of code should be included in the snippet. The options are: ID, Range and None.
  6. Based on your selection from Footstep five, provide a value.

Your snippet reference will expect like this:

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

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

Notation

The name you assign to the dependent repository is relative to the root of the primary repository, but the tilde (~) refers to the root of the physician set. The doc set root is determined by build_source_folder in .openpublishing.publish.config.json. The path to the snippet in the preceding case works in the azure-docs repo because build_source_folder refers to the repo root (.). If build_source_folder were articles, the path would starting time with ~/../samples-durable-functions instead of ~/samples-durable-functions.

Snippets in a Jupyter notebook

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

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

Add together metadata to notebook

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

    • In Jupyter, you can edit jail cell metadata by beginning enabling the the cell toolbar: View > Cell Toolbar > Edit Metadata.
    • In one case the cell toolbar is enabled, select Edit Metadata on the cell you wish to name.
    • Or you lot can edit metadata straight in the notebook's JSON structure.

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

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

    For case:

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

    Tip

    Y'all can add together any other metadata you'd like to help you rails where the cell is existence used. For example:

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

Ready repository admission

If the notebook file you desire to reference is in a different repository, set up the code repository every bit a dependent repository.

Jupyter notebook snippet syntax reference

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

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

For example:

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

Important

This syntax is a block Markdown extension. It must be used on its own line.

Use whatsoever of the supported languages for the <linguistic communication> identifier.

Interactive code snippets

Inline interactive lawmaking blocks

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

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

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

                              ```azurepowershell-interactive     New-AzResourceGroup -Proper 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($"Hullo {aFriend}");

To turn on this characteristic for a particular code block, use a special linguistic communication identifier. The available options are:

  • azurepowershell-interactive - Enables the Azure PowerShell Cloud Beat, equally in the preceding example
  • azurecli-interactive - Enables the Azure Cloud Trounce
  • csharp-interactive - Enables the C# REPL

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

Code snippets included by reference

You tin can enable interactive style for code snippets included by reference. To turn on this characteristic for a particular lawmaking cake, apply the interactive attribute. The available attribute values are:

  • cloudshell-powershell - Enables the Azure PowerShell Cloud Trounce, every bit in the preceding example
  • cloudshell-bash - Enables the Azure Cloud Shell
  • attempt-dotnet - Enables Endeavour .Net
  • effort-dotnet-class - Enables Try .Internet with grade 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 Crush and PowerShell Cloud Shell, users can only run commands against their ain 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 total program text. For instance, the Programme.cs file generated by dotnet new console would exist valid. These are most useful to prove an entire modest program, including the using directives needed. Top level statements are not supported at this time.
  • Method scaffolding (try-dotnet-method): The code cake should represent the content of a Primary method in a console awarding. You can assume the using directives added by the dotnet new console template. This setting is nigh useful for short snippets that demonstrate one feature.
  • Class scaffolding (endeavor-dotnet-class): The code cake should stand for a grade with a Main method every bit the programme entry indicate. These tin be used to show how members of a grade interact.

Snippet syntax reference

Syntax:

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

Important

This syntax is a block Markdown extension. It must be used on its own line.

  • <language> (optional)

    • Language of the code snippet. For more information, see the Supported languages section after 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 exist retrieved from the file and how it should be displayed:
      • range: 1,3-5 A range of lines. This case includes lines i, 3, 4, and 5.
      • id: Create The ID of the snippet that needs to exist inserted from the code file. This value cannot coexist with range.
      • highlight: 2-4,6 Range and/or numbers of lines that demand to be highlighted in the generated lawmaking snippet. The numbering is relative to the lines displayed (as specified past range or id), non the file.
      • interactive: cloudshell-powershell, cloudshell-fustigate, try-dotnet, try-dotnet-class, effort-dotnet-method String value determines what kinds of interactivity are enabled.
      • For details about tag name representation in code snippet source files past language, see the DocFX guidelines.

Supported languages

The Docs Authoring Pack includes a feature to provide argument completion and validation of the bachelor language identifiers for code fence blocks.

Fenced code blocks

Proper name Valid aliases
.NET Cadre CLI dotnetcli
1C 1c
ABNF abnf
Access logs accesslog
Ada ada
ARM assembler armasm, arm
AVR assembler avrasm
ActionScript actionscript, as
Alan alan, i
AngelScript angelscript, asc
ANTLR antlr
Apache apache, apacheconf
AppleScript applescript, osascript
Arcade arcade
AsciiDoc asciidoc, adoc
AspectJ aspectj
ASPX aspx
ASP.Cyberspace (C#) aspx-csharp
ASP.Cyberspace (VB) aspx-vb
AutoHotkey autohotkey
AutoIt autoit
Awk awk, mawk, nawk, gawk
Axapta axapta
AzCopy azcopy
Azure CLI azurecli
Azure CLI (Interactive) azurecli-interactive
Azure Powershell azurepowershell
Azure Powershell (Interactive) azurepowershell-interactive
Bash bash, sh, zsh
Basic basic
BNF bnf
C c
C# csharp, cs
C# (Interactive) csharp-interactive
C++ cpp, c, cc, h, c++, h++, hpp
C++/CX cppcx
C++/WinRT cppwinrt
C/AL cal
Cache Object Script cos, cls
CMake cmake, cmake.in
Coq coq
CSP csp
CSS css
Cap'due north Proto capnproto, capnp
Clojure clojure, clj
CoffeeScript coffeescript, coffee, cson, iced
Crmsh crmsh, crm, pcmk
Crystal crystal, cr
Cypher (Neo4j) cypher
D d
DAX Power BI dax
DNS Zone file dns, zone, bind
DOS dos, bat, cmd
Dart dart
Delphi delphi, dpr, dfm, pas, pascal, freepascal, lazarus, lpr, lfm
Unequal diff, patch
Django django, jinja
Dockerfile dockerfile, docker
dsconfig dsconfig
DTS (Device Tree) dts
Dust dust, dst
Dylan dylan
EBNF ebnf
Elixir elixir
Elm elm
Erlang erlang, erl
Excel excel, xls, xlsx
Extempore extempore, xtlang, xtm
F# fsharp, fs
FIX fix
Fortran fortran, f90, f95
Yard-Code gcode, nc
Gams gams, gms
GAUSS gauss, gss
GDScript godot, gdscript
Gherkin gherkin
GN for Ninja gn, gni
Get go, golang
Golo golo, gololang
Gradle gradle
Groovy cracking
HTML html, xhtml
HTTP http, https
Haml haml
Handlebars handlebars, hbs, html.hbs, html.handlebars
Haskell haskell, hs
Haxe haxe, hx
Hy hy, hylang
Ini ini
Inform7 inform7, i7
IRPF90 irpf90
JSON json
Java coffee, jsp
JavaScript javascript, js, jsx
Kotlin kotlin, kt
Kusto kusto
Leaf foliage
Lasso lasso, ls, lassoscript
Less less
LDIF ldif
Lisp lisp
LiveCode Server livecodeserver
LiveScript livescript, ls
Lua lua
Makefile makefile, mk, mak
Markdown markdown, doc, mkdown, mkd
Mathematica mathematica, mma, wl
Matlab matlab
Maxima maxima
Maya Embedded Language mel
Mercury mercury
mIRC Scripting Language mirc, mrc
Mizar mizar
Managed Object Format mof
Mojolicious mojolicious
Monkey monkey
Moonscript moonscript, moon
MS Graph (Interactive) msgraph-interactive
N1QL n1ql
NSIS nsis
Nginx nginx, nginxconf
Nimrod nimrod, nim
Goose egg cypher
OCaml ocaml, ml
Objective C objectivec, mm, objc, obj-c
OpenGL Shading Language glsl
OpenSCAD openscad, scad
Oracle Rules Language ruleslanguage
Oxygene oxygene
PF pf, pf.conf
PHP php, php3, php4, php5, php6
Parser3 parser3
Perl perl, pl, pm
Plaintext no highlight plaintext
Pony pony
PostgreSQL & PL/pgSQL pgsql, postgres, postgresql
PowerShell powershell, ps
PowerShell (Interactive) powershell-interactive
Processing processing
Prolog prolog
Properties properties
Protocol Buffers protobuf
Puppet puppet, pp
Python python, py, gyp
Python profiler results contour
Q# qsharp
Q m, kdb
QML qml
R r
Razor CSHTML cshtml, razor, razor-cshtml
ReasonML reasonml, re
RenderMan RIB rib
RenderMan RSL rsl
Roboconf graph, instances
Robot Framework robot, rf
RPM spec files rpm-specfile, rpm, spec, rpm-spec, specfile
Ruby crimson, rb, gemspec, podspec, thor, irb
Rust rust, rs
SAS SAS, sas
SCSS scss
SQL sql
STEP Part 21 p21, pace, stp
Scala scala
Scheme scheme
Scilab scilab, sci
Shape Expressions shexc
Shell shell, console
Smali smali
Smalltalk smalltalk, st
Solidity solidity, sol
Stan stan
Stata stata
Structured Text iecst, scl, stl, structured-text
Stylus stylus, styl
SubUnit subunit
Supercollider supercollider, sc
Swift swift
Tcl tcl, tk
Terraform (HCL) terraform, tf, hcl
Exam Anything Protocol tap
TeX tex
Thrift thrift
TOML toml
TP tp
Twig twig, craftcms
TypeScript typescript, ts
VB.NET vbnet, vb
VBScript vbscript, vbs
VHDL vhdl
Vala vala
Verilog verilog, v
Vim Script vim
Visual Bones vb
Visual Basic for Applications vba
X++ xpp
x86 Assembly x86asm
Forty twoscore, tao
XQuery xquery, xpath, xq
XAML xaml
XML xml, xhtml, rss, atom, xjb, xsd, xsl, plist
YAML yml, yaml
Zephir zephir, zep

Next steps

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