Markdown 설명서

• 3/10/2024
• 29 minutes to read

이 문서는 VisualAcademy Docs를 만들 때 사용되는 Markdown에 대한 설명서입니다.

https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html

This article provides an alphabetical reference for writing Markdown for Microsoft Learn.

Markdown is a lightweight markup language with plain text formatting syntax. The Microsoft Learn platform supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Microsoft Learn also supports custom Markdown extensions that provide richer content on the Microsoft Learn site.

You can use any text editor to write Markdown, but we recommend Visual Studio Code with the Learn Authoring Pack. The Learn Authoring Pack provides editing tools and preview functionality that lets you see what your articles will look like when rendered on Microsoft Learn.

Youtube 비디오 인클루드

> [!Video https://www.youtube.com/embed/arZaLRMm8kw]

HTML 헤더 영역에 메타 태그 추가

HTML 태그의 헤더 영역에 title, description 등과 함께 메타 태그를 넣을 수 있습니다. md 파일 최상단에 다음과 같은 형태로 추가하면 됩니다.

---
title: ASP.NET Core 7.0 CRUD API 만들기
description: TODO 리스트 CRUD Web API 만들기 with ASP.NET Core 7.0 Minimal APIs
author: redplus

og:url: https://www.memoengine.com/docs/aspnetcore/aspnetcore-todo-list/
og:title: ASP.NET Core 7.0 CRUD API 만들기
og:type: website
og:image: /docs/aspnetcore/snippets/todos/images/visualacademy-todos-1366.png
og:description: TODO 리스트 CRUD Web API 만들기 with ASP.NET Core 7.0 Minimal APIs
---

Alerts (Note, Tip, Important, Caution, Warning)

Alerts are a Markdown extension to create block quotes that render on Microsoft Learn with colors and icons that indicate the significance of the content.

Avoid notes, tips, and important boxes. Readers tend to skip over them. It's better to put that info directly into the article text.

If you need to use alerts, limit them to one or two per article. Multiple notes should never be next to each other in an article.

The following alert types are supported:

> [!NOTE]
> Information the user should notice even if skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Essential information required for user success.
> [!CAUTION]
> Negative potential consequences of an action.
> [!WARNING]
> Dangerous certain consequences of an action.

These alerts look like this on Microsoft Learn:

Angle brackets

If you use angle brackets in text in your file (for example, to denote a placeholder), you need to manually encode the angle brackets. Otherwise, Markdown thinks that they're intended to be an HTML tag. For example, encode <script name> as <script name> or \<script name>. Angle brackets don't have to be escaped in text formatted as inline code or in code blocks.

Apostrophes and quotation marks

If you copy from Word into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up with things like this when the file is published: It’s Here are the encodings for the "smart" versions of these punctuation marks:

• Left (opening) quotation mark: “
• Right (closing) quotation mark: ”
• Right (closing) single quotation mark or apostrophe: ’
• Left (opening) single quotation mark (rarely used): ‘

Blockquotes

Blockquotes are created using the > character:

> This is a blockquote. It is usually rendered indented and with a different background color.

The preceding example renders as follows:

This is a blockquote. It is usually rendered indented and with a different background color.

Bold and italic text

To format text as bold, enclose it in two asterisks:

This text is **bold**.

To format text as italic, enclose it in a single asterisk:

This text is *italic*.

To format text as both bold and italic, enclose it in three asterisks:

This text is both ***bold and italic***.

Code snippets

Columns

The columns Markdown extension gives authors the ability to add column-based content layouts that are more flexible and powerful than basic Markdown tables, which are only suited for true tabular data. You can add up to four columns, and use the optional span attribute to merge two or more columns.

While the columns extension still works, we no longer recommend it for creating custom layouts. We've found that many custom column layouts have accessibility issues or otherwise violate the style guidelines. Don't create custom layouts. Use standard Microsoft Learn features.

The syntax for columns is as follows:

:::row:::
   :::column span="":::
      Content...
   :::column-end:::
   :::column span="":::
      More content...
   :::column-end:::
:::row-end:::

Columns should only contain basic Markdown, including images. Headings, tables, tabs, and other complex structures shouldn't be included. A row can't have any content outside of column.

For example, the following Markdown creates one column that spans two column widths, and one standard (no span) column:

This renders as follows:

Comments

Microsoft Learn supports HTML comments if you must comment out sections of your article:

<!--- Here's my comment --->

Headings

Microsoft Learn supports six levels of Markdown headings:

# This is a first level heading (H1)

## This is a second level heading (H2)

...

###### This is a sixth level heading (H6)

• There must be a space between the last # and heading text.
• Each Markdown file must have one and only one H1 heading.
• The H1 heading must be the first content in the file after the YML metadata block.
• H2 headings automatically appear in the right-hand navigating menu of the published file. Lower-level headings don't appear, so use H2s strategically to help readers navigate your content.
• HTML headings, such as <h1>, aren't recommended, and in some cases will cause build warnings.

HTML

Although Markdown supports inline HTML, HTML isn't recommended for publishing to Microsoft Learn, and except for a limited list of values will cause build errors or warnings.

Images

The following file types are supported by default for images:

• .jpg
• .png

To support other image types, such as .gif, you must add them as resources in docfx.json:

"resource": [
  {
    "files" : [
      "**/*.png",
      "**/*.jpg,
      "**/*.gif"
    ],

Standard conceptual images (default Markdown)

The basic Markdown syntax to embed an image is:

![<alt text>](<folderPath>)

Example:
![alt text for image](../images/Introduction.png)

Where <alt text> is a brief description of the image and <folder path> is a relative path to the image. Alternate text is required for screen readers for the visually impaired. It's also useful if there's a site bug where the image can't render.

Underscores in alt text aren't rendered properly unless you escape them by prefixing them with a backslash (\_). However, don't copy file names for use as alt text. For example, instead of this:

![ADextension_2FA_Configure_Step4](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Write this:

![Active Directory extension for two-factor authentication, step 4: Configure](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Standard conceptual images (Learn Markdown)

The custom :::image::: extension on Microsoft Learn supports standard images, complex images, and icons.

For standard images, the older Markdown syntax will still work, but the new extension is recommended because it supports more powerful functionality, such as specifying a localization scope that's different from the parent topic. Other advanced functionality, such as selecting from the shared image gallery instead of specifying a local image, will be available in the future. The new syntax is as follows:

:::image type="content" source="<folderPath>" alt-text="<alt text>":::

If type="content" (the default), both source and alt-text are required.

Complex images with long descriptions

You can also use this extension to add an image with a long description that is read by screen readers but not rendered visually on the published page. Long descriptions are an accessibility requirement for complex images, such as graphs. The syntax is the following:

:::image type="complex" source="<folderPath>" alt-text="<alt text>":::
   <long description here>
:::image-end:::

If type="complex", source, alt-text, a long description, and the :::image-end::: tag are all required.

When your changes are in preview or published, you can check whether the long description exists by right-clicking on the image and selecting Inspect (when using Microsoft Edge browser, although other browsers have similar features). This action brings you to the image source in the HTML code, underneath which you'll find a visually-hidden class. Expand the dropdown on this class, and you'll find your long description:

Automatic borders

The :::image::: extension also supports the border property, which automatically adds a 1-pixel gray border around your image. The border property is true by default for content and complex images, so you'll get the border automatically unless you explicitly add the property with a value of false. The border property is false by default for icon images.

The border property is the recommended way to add a border. Don't create your own borders manually.

Specifying loc-scope

Sometimes the localization scope for an image is different from that of the article or module that contains it. This can cause a bad global experience: for example, if a screenshot of a product is accidentally localized into a language the product isn't available in. To prevent this, you can specify the optional loc-scope attribute in images of types content and complex, and is required for screenshots that show a product with a different localization scope than the article or module that contains it.

Icons

The image extension supports icons, which are decorative images and should not have alt text. The syntax for icons is:

:::image type="icon" source="<folderPath>":::

If type="icon", source should be specified but alt-text shouldn't be.

The border property is false by default for icons. If your decorative image requires the standard image border, explicitly add border="true" to the :::image::: tag.

Included Markdown files

Where markdown files need to be repeated in multiple articles, you can use an include file. The includes feature instructs Microsoft Learn to replace the reference with the contents of the include file at build time. You can use includes in the following ways:

• Inline: Reuse a common text snippet inline with within a sentence.
• Block: Reuse an entire Markdown file as a block, nested within a section of an article.

An inline or block include file is a Markdown (.md) file. It can contain any valid Markdown. Include files are typically located in a common includes subdirectory, in the root of the repository. When the article is published, the included file is seamlessly integrated into it.

Includes syntax

Block include is on its own line:

[!INCLUDE [<title>](<filepath>)]

Inline include is within a line:

Text before [!INCLUDE [<title>](<filepath>)] and after.

Where <title> is the name of the file and <filepath> is the relative path to the file. INCLUDE must be capitalized and there must be a space before the <title>.

Here are requirements and considerations for include files:

• Use block includes for significant amounts of content--a paragraph or two, a shared procedure, or a shared section. Don't use them for anything smaller than a sentence.
• Includes won't be rendered in the GitHub-rendered view of your article because they rely on Microsoft Learn extensions. They'll be rendered only after publication.
• Write all the text in an include file in complete sentences or phrases that don't depend on preceding or following text in the article that references the include. Ignoring this guidance creates an untranslatable string in the article.
• Don't embed include files within other include files.
• /Includes folders are excluded from build. Therefore, images stored in /includes folders and referenced in included files won't be displayed in published content. Store images in a /media folder outside the /includes folder.
• As with regular articles, don't share media between include files. Use a separate file with a unique name for each include and article. Store the media file in the media folder that's associated with the include.
• Don't use an include as the only content of an article. Includes are meant to be supplemental to the content in the rest of the article.

Indentation

In Markdown, spaces before the first character of a line determine the line's alignment relative to the preceding lines. Indentation especially influences numbered and bulleted lists to render multiple levels of nesting in a hierarchical or outline format.

To indent text to align with a preceding paragraph or an item in a numbered or bulleted list, use spaces.

The following two examples show how indented paragraphs render based on their relationship to other paragraphs.

1. This is a numbered list example (one space after the period before the letter T).
   This sentence is indented three spaces.
   This code block is indented three spaces.
   
- This is a bulleted list example (one space after the bullet before the letter T).
  This sentence is indented two spaces.
  > [!TIP]
  > This tip is indented two spaces.
  - This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T).
    This sentence is indented four spaces.
    > This quote block is indented four spaces.

The example above renders as:

1. This is a numbered list example (one space after the period before the letter T). This sentence is indented three spaces.

   This code block is indented three spaces.
   

• This is a bulleted list example (one space after the bullet before the letter T). This sentence is indented two spaces.

  TIP

  This tip is indented two spaces.

  • This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T). This sentence is indented four spaces.

    This quote block is indented four spaces.

Links

Lists (Numbered, Bulleted, Checklist)

Numbered list

To create a numbered list, you can use all 1s. The numbers are rendered in ascending order as a sequential list when published. For increased source readability, you can increment your lists manually. Don't use letters in lists, including nested lists. They don't render correctly when published to Microsoft Learn. Nested lists using numbers will render as lowercase letters when published. For example:

1. This is
1. a parent numbered list
   1. and this is
   1. a nested numbered list
1. (fin)

This renders as follows:

1. This is
2. a parent numbered list
   1. and this is
   2. a nested numbered list
3. (fin)

Bulleted list

To create a bulleted list, use - or * followed by a space at the beginning of each line:

- This is
- a parent bulleted list
  - and this is
  - a nested bulleted list
- All done!

This renders as follows:

• This is
• a parent bulleted list
  • and this is
  • a nested bulleted list
• All done!

Whichever syntax you use, - or *, use it consistently within an article.

Checklist

Checklists are available for use on Microsoft Learn via a custom Markdown extension:

> [!div class="checklist"]
> * List item 1
> * List item 2
> * List item 3

This example renders on Microsoft Learn like this:

Next step action

You can use a custom extension to add a next step action button to Microsoft Learn pages. The syntax is as follows:

> [!div class="nextstepaction"]
> [button text](link to topic)

For example:

Non-localized strings

You can use the custom no-loc Markdown extension to identify strings of content that you would like the localization process to ignore. All strings called out will be case-sensitive; that is, the string must match exactly to be ignored for localization. To mark an individual string as non-localizable, use this syntax:

:::no-loc text="String":::

For example, in the following, only the single instance of Document will be ignored during the localization process:

# Heading 1 of the Document

Markdown content within the :::no-loc text="Document":::.  The are multiple instances of Document, document, and documents.

Lorem :::no-loc text="Find a \"Quotation\""::: Ipsum.

You can also use metadata in the YAML header to mark all instances of a string within the current Markdown file as non-localizable:

author: cillroy
no-loc: [Global, Strings, to be, Ignored]

In the metadata description and the Markdown main content the word document is localized, because it does not start with a capital D.

---
title: Title of the Document
author: author-name
description: Description for the document
no-loc: [Title, Document]
---
# Heading 1 of the Document

Markdown content within the document.

Selectors

Selectors are UI elements that let the user switch between multiple flavors of the same article. They are used in some docsets to address differences in implementation across technologies or platforms. Selectors are typically most applicable to our mobile platform content for developers.

Because the same selector Markdown goes in each article file that uses the selector, we recommend placing the selector for your article in an include file. Then you can reference that include file in all your article files that use the same selector.

There are two types of selectors: a single selector and a multi-selector.

Single selector

> [!div class="op_single_selector"]
> - [Universal Windows](../articles/notification-hubs-windows-store-dotnet-get-started/)
> - [Windows Phone](../articles/notification-hubs-windows-phone-get-started/)
> - [iOS](../articles/notification-hubs-ios-get-started/)
> - [Android](../articles/notification-hubs-android-get-started/)
> - [Kindle](../articles/notification-hubs-kindle-get-started/)
> - [Baidu](../articles/notification-hubs-baidu-get-started/)
> - [Xamarin.iOS](../articles/partner-xamarin-notification-hubs-ios-get-started/)
> - [Xamarin.Android](../articles/partner-xamarin-notification-hubs-android-get-started/)

Multi-selector

> [!div class="op_multi_selector" title1="Platform" title2="Backend"]
> - [(iOS | .NET)](./mobile-services-dotnet-backend-ios-get-started-push.md)
> - [(iOS | JavaScript)](./mobile-services-javascript-backend-ios-get-started-push.md)
> - [(Windows universal C# | .NET)](./mobile-services-dotnet-backend-windows-universal-dotnet-get-started-push.md)
> - [(Windows universal C# | Javascript)](./mobile-services-javascript-backend-windows-universal-dotnet-get-started-push.md)
> - [(Windows Phone | .NET)](./mobile-services-dotnet-backend-windows-phone-get-started-push.md)
> - [(Windows Phone | Javascript)](./mobile-services-javascript-backend-windows-phone-get-started-push.md)
> - [(Android | .NET)](./mobile-services-dotnet-backend-android-get-started-push.md)
> - [(Android | Javascript)](./mobile-services-javascript-backend-android-get-started-push.md)
> - [(Xamarin iOS | Javascript)](./partner-xamarin-mobile-services-ios-get-started-push.md)
> - [(Xamarin Android | Javascript)](./partner-xamarin-mobile-services-android-get-started-push.md)

... will be rendered like this:

Subscript and superscript

You should only use subscript or superscript when necessary for technical accuracy, such as when writing about mathematical formulas. Don't use them for non-standard styles, such as footnotes.

For both subscript and superscript, use HTML:

Hello <sub>This is subscript!</sub>

This renders as follows:

Hello _{This is subscript!}

Goodbye <sup>This is superscript!</sup>

This renders as follows:

Goodbye ^{This is superscript!}

Tables

The simplest way to create a table in Markdown is to use pipes and lines. To create a standard table with a header, follow the first line with dashed line:

|This is   |a simple   |table header|
|----------|-----------|------------|
|table     |data       |here        |
|it doesn't|actually   |have to line up nicely!|

This renders as follows:

You can align the columns by using colons:

| Fun                  | With                 | Tables          |
| :------------------- | -------------------: |:---------------:|
| left-aligned column  | right-aligned column | centered column |
| $100                 | $100                 | $100            |
| $10                  | $10                  | $10             |
| $1                   | $1                   | $1              |

Renders as follows:

Line breaks within words in any table cell

Long words in a Markdown table might make the table expand to the right navigation and become unreadable. You can solve that by allowing rendering to automatically insert line breaks within words when needed. Just wrap up the table with the custom class [!div class="mx-tdBreakAll"].

Here is a Markdown sample of a table with three rows that will be wrapped by a div with the class name mx-tdBreakAll.

> [!div class="mx-tdBreakAll"]
> |Name|Syntax|Mandatory for silent installation?|Description|
> |-------------|----------|---------|---------|
> |Quiet|/quiet|Yes|Runs the installer, displaying no UI and no prompts.|
> |NoRestart|/norestart|No|Suppresses any attempts to restart. By default, the UI will prompt before restart.|
> |Help|/help|No|Provides help and quick reference. Displays the correct use of the setup command, including a list of all options and behaviors.|

It will be rendered like this:

Line breaks within words in second column table cells

You might want line breaks to be automatically inserted within words only in the second column of a table. To limit the breaks to the second column, apply the class mx-tdCol2BreakAll by using the div wrapper syntax as shown earlier.

Inconsistent column widths between tables

You may notice that the column widths of the tables in your articles look odd or inconsistent. This behavior occurs because the length of text within the cells determines the layout of the table. Unfortunately, there's no way to control how the tables render. This is a limitation of Markdown. Even though it would look nicer to have the width of table columns be consistent, this would have some disadvantages too:

• Interlacing HTML code with Markdown makes topics more complicated and discourages community contributions.
• A table that you make look good for a specific screen size may end up looking unreadable at different screen sizes as it preempts responsive rendering.

Data matrix tables

A data matrix table has both a header and a weighted first column, creating a matrix with an empty cell in the top left. Microsoft Learn has custom Markdown for data matrix tables:

|                  |Header 1 |Header 2|
|------------------|---------|--------|
|**First column A**|Cell 1A  |Cell 2A |
|**First column B**|Cell 1B  |Cell 2B |

The example renders as:

Every entry in the first column must be styled as bold (**bold**); otherwise the tables won't be accessible for screen readers or valid for Microsoft Learn.

HTML Tables

HTML tables aren't recommended for Microsoft Learn. They aren't human readable in the source - which is a key principle of Markdown.

DocFX Flavored Markdown

DocFX supports DocFX Flavored Markdown, aka DFM. It supports all GitHub Flavored Markdown syntax and compatible with CommonMark. Also, DFM adds new syntax to support additional functionalities, including cross reference and file inclusion.

Yaml Header

Yaml header in DFM is considered as the metadata for the Markdown file. It will transform to yamlheader tag when processed. Yaml header MUST be the first thing in the file and MUST take the form of valid YAML set between triple-dashed lines. Here is a basic example:

---
uid: A.md
title: A
---

Cross Reference

Cross reference allows you to link to another topic by using its unique identifier (called UID) instead of using its file path.

For conceptual Markdown files UID can be defined by adding a uid metadata in YAML header:

---
uid: uid_of_the_file
---

This is a conceptual topic with `uid` specified.

For reference topics, UIDs are auto generated from source code and can be found in generated YAML files.

You can use one of the following syntax to cross reference a topic with UID defined:

1. Markdown link: [link_text](xref:uid_of_the_topic)
2. Auto link: <xref:uid_of_the_topic>
3. Shorthand form: @"uid_of_the_topic"

All will render to:

<a href="url_of_the_topic">link_text</a>

If link_text is not specified, DocFX will extract the title from the target topic and use it as the link text.

Do not use the @uid link in brackets (like this: (@uid)). DocFX cannot parse this link. The @uid link should be separated with white spaces. If you need to add a link in brackets, use [](xref:uid).

File Inclusion

DFM adds syntax to include other file parts into current file, the included file will also be considered as in DFM syntax.

There are two types of file inclusion: Inline and block, as similar to inline code span and block code.

Inline

Inline file inclusion is in the following syntax, in which <title> stands for the title of the included file, and <filepath> stands for the file path of the included file. The file path can be either absolute or relative.<filepath> can be wrapped by ' or ".

...Other inline contents... [!include[<title>](<filepath>)]

Block

Block file inclusion must be in a single line and with no prefix characters before the start [. Content inside the included file will transform using DFM syntax.

[!include[<title>](<filepath>)]

Section definition

User may need to define section. Mostly used for code table. Give an example below.

> [!div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar"]
> ```cs
> <cs code text>
> ```
> ```javascript
> <js code text>
> ```

The above blockquote Markdown text will transform to section html as in the following:

<div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar">
  <pre><code>cs code text</code></pre>
  <pre><code>js code text</code></pre>
</div>

Code Snippet

Allows you to insert code with code language specified. The content of specified code path will expand.

[!code-<language>[<name>](<codepath><queryoption><queryoptionvalue> "<title>")]

• <language> can be made up of any number of character and '-'. However, the recommended value should follow Highlight.js language names and aliases.
• <codepath> is the path relative to the file containing this markdown content in file system, which indicates the code snippet file that you want to expand.
• <queryoption> and <queryoptionvalue> are used together to retrieve part of the code snippet file in the line range or tag name way. We have 2 query string options to represent these two ways:

• In ? query string, the whole file will be included if none of the first three option is specified.
• If dedent isn't specified, the maximum common indent will be trimmed automatically.
• <title> can be omitted as it doesn't affect the DocFX markup result, but it can beautify the result of other Markdown engine, like GitHub Preview.

Code Snippet Sample

[!code-csharp[Main](Program.cs)]

[!code[Main](Program.cs#L12-L16 "This is source file")]
[!code-vb[Main](../Application/Program.vb#testsnippet "This is source file")]

[!code[Main](index.xml?start=5&end=9)]
[!code-javascript[Main](../jquery.js?name=testsnippet)]
[!code[Main](index.xml?range=2,5-7,9-) "This includes the lines 2, 5, 6, 7 and lines 9 to the last line"]
[!code[Main](index.xml?highlight=2,5-7,9-) "This includes the whole file with lines 2,5-7,9- highlighted"]

Tag Name Representation in Code Snippet Source File

DFM currently supports the following <language> values to be able to retrieve by tag name:

• C family
  • Start with: // <{name}>
  • End with: // </{name}>
  • Languages: actionscript, arduino, assembly (alias: nasm), c (alias: cpp, c++, objective-c, obj-c, objc, objectivec), csharp (alias: cs), cshtml, cuda, d (alias: dlang), fsharp (alias: fs), go (alias: golang), java, javascript (alias: js, node), pascal, php, processing, rust, scala, smalltalk, swift, typescript (alias: ts)
  • File extensions: .as, .asm, .ino, .c, .cc, .cpp, .cs, .cshtml .cu, .cuh, .d, .fs, .fsi, .fsx, .go, .h, .hpp, .java, .js, .pas, .php, .pde, .rs, .scala, .st, .swift, .ts
• Basic family
  • Start with: ' <{name}>
  • End with: ' </{name}>
  • Languages: vb, vbhtml, vbnet, vbscript
  • File extensions: .bas, .vb, .vba, .vbhtml, .vbs
• Markup language family
  • Start with: <!-- <{name}> -->
  • End with: <!-- </{name}> -->
  • Languages: cshtml, html, vbhtml, wsdl, xml, xsl, xslt, xsd, xaml
  • File extensions: .asp, .aspx, .csdl, .cshtml, .edmx, .jsp, .vbhtml, .wsdl, .xaml, .xml, .xsd, .xsl, .xslt, .html
• Sql family
  • Start with: -- <{name}>
  • End with: -- </{name}>
  • Languages: sql
  • File extensions: .sql
• Script family
  • Start with: # <{name}>
  • End with: # </{name}>
  • Languages: perl, powershell (alias: posh), python, r, ruby (alias: ru), shell (alias: sh, bash)
  • File extensions: .bash, .pl, .ps1, .py, .r, .ru, .ruby, .sh
• Special language
  • batchfile
    • Start with: rem <{name}>
    • End with: rem </{name}>
    • Languages: batchfile
    • File extensions: .bat .cmd
  • csharp
    • Start with: #region {name}
    • End with: #endregion
    • Languages: csharp (alias: cs)
    • File extensions: .cs .cshtml
  • erlang
    • Start with: % <{name}>
    • End with: % </{name}>
    • Languages: erlang
    • File extensions: .erl
  • haskell
    • Start with: -- <{name}>
    • End with: -- </{name}>
    • Languages: haskell
    • File extensions: .hs
  • matlab
    • Start with: % <{name}>
    • End with: % </{name}>
    • Languages: matlab
    • File extensions: .matlab
  • lisp
    • Start with: ; <{name}>
    • End with: ; </{name}>
    • Languages: lisp
    • File extensions: .lisp, .lsp
  • lua
    • Start with: -- <{name}>
    • End with: -- </{name}>
    • Languages: lua
    • File extensions: .lua
  • vb
    • Start with: #Region {name}
    • End with: #End Region
    • Languages: vb (alias: vbnet)
    • File extensions: .vb .vbhtml

Code Snippet for Jupyter Notebooks

Allows you to insert code from a code cell of a Jupyter Notebook. The source content in the specified code cell will expand.

Steps to use this:

1. In your Jupyter Notebook, add metadata to the code cell you will reference:

     "metadata": {
       "name": "{tagname}"
      }
   

2. In your .md file, use name to identify the cell.

   [!notebook-<language>[](<codepath>?name={tagname})]]
   

Code Snippet for Jupyter Notebooks Sample

For this Jupyter Notebook cell:

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "name": "import"
   },
   "outputs": [],
   "source": [
    "import azureml.core\n",
    "print(azureml.core.VERSION)"
   ]
  },

Use the markup:

[!notebook-python[](<codepath>?name="import")]]

to display the lines of code in the source part of the cell:

import azureml.core
print(azureml.core.VERSION)

Note (Warning/Tip/Important)

Using specific syntax inside block quote to indicate the following content is Note.

> [!NOTE]
> <note content>
> [!WARNING]
> <warning content>

The above content will be transformed to the following html:

<div class="NOTE">
  <h5>NOTE</h5>
  <p>note content</p>
</div>
<div class="WARNING">
  <h5>WARNING</h5>
  <p>WARNING content</p>
</div>

Here are all the supported note types with the styling of the default theme applied:

탭(Tabbed content)

Syntax

• Start a tab by a special markdown title (any level).
  • Title content should be a markdown link.
  • Link target is #tab/{tabid} or #tab/{tabid}/{condition}
• Continue by any other content.
• End by a markdown hr.

Example

# [.NET 6](#tab/dotnet6)

내용 준비중입니다...

# [.NET 5](#tab/dotnet5)

내용 준비중입니다...

***

# [C#](#tab/csharp-2024)

내용 준비중입니다...

# [C](#tab/c-2024)

내용 준비중입니다...

# [Java](#tab/java-2024)

내용 준비중입니다...

# [Python](#tab/python-2024)

내용 준비중입니다...

***

# [C#](#tab/csharp2023)

내용 준비중입니다...

# [C](#tab/c2023)

내용 준비중입니다...

# [Java](#tab/java2023)

내용 준비중입니다...

# [Python](#tab/python2023)

내용 준비중입니다...

# [JavaScript](#tab/javascript2023)

내용 준비중입니다...

# [C++](#tab/cpp2023)

내용 준비중입니다...

# [Go](#tab/go2023)

내용 준비중입니다...

# [Rust](#tab/rust2023)

내용 준비중입니다...

# [TS](#tab/ts2023)

내용 준비중입니다...

# [KT](#tab/kotlin2023)

내용 준비중입니다...

***

Tab group 1:

# [Tab Text 1](#tab/tabid-1)

Tab content-1-1.

# [Tab Text 2](#tab/tabid-2)

Tab content-2-1.

***

Tab group 2:

# [Tab Text A](#tab/tabid-a)

Tab content-a-1.

# [Tab Text B](#tab/tabid-b)

Tab content-b-1.

***

Tab group 3:

# [Tab Text 1](#tab/tabid-1)

Tab content-1-2.

# [Tab Text 2](#tab/tabid-2)

Tab content-2-2.

***

Tab group 4:

# [Tab Text A](#tab/tabid-a)

Tab content-a-2.

# [Tab Text B](#tab/tabid-b)

Tab content-b-2.

***

The result will be:

Tab group 1:

Tab group 2:

Tab group 3:

Tab group 4:

Behavior

Tab groups with a same set of id are linkable in one page.

In example, tab group 1, 3 have same id set: tabid-1, tabid-2, tab group 2, 4 have same id set: tabid-a, tabid-b.

So tab group 1, 3 are linked, tab group 2, 4 are linked. When tab tabid-1 in tab group 1 is clicked, tab tabid-1 in tab group 3 will be selected in same time. But tab group 2, 4 do not have any changed.

Condition

Condition is the tab id of other table groups.

e.g.:

Tab Group 1:

# [**Tab Text 1**](#tab/tabid-1)

Tab content-1.

# [**Tab Text 2**](#tab/tabid-2)

Tab content-2.

***

Tab Group 2:

# [Tab Text A](#tab/tabid-a/tabid-1)

Tab content-a for 1.

# [Tab Text A](#tab/tabid-a/tabid-2)

Tab content-a for 2.

# [Tab Text B](#tab/tabid-b/tabid-1)

Tab content-b for 1.

# [Tab Text B](#tab/tabid-b/tabid-2)

Tab content-b for 2.

***

Result:

Tab Group 1:

Tab Group 2:

When select tabid-1 in tab group 1, you can get content-a or content-b for 1 in group 2.
When select tabid-2 in tab group 1, you can get content-a or content-b for 2 in group 2.

Video

Allows you to add videos to your topics.

Syntax:

> [!Video embed_link]

Example:

> [!Video https://www.youtube.com/embed/TAaG0nUUy6A]

Result:

Differences introduced by DFM syntax

YAML header

In GFM, YAML header must start at the very beginning of the Markdown file. In DFM, YAML header contains more powerful meanings. Refer to Yaml Header for details.

...some text...

---
a: b
---

In GFM, it would be rendered as <hr>a: b<hr>.
In DFM, it would be rendered as a YAML header.

If you want to get <hr> in html in DFM, use:

- - -
***
* * *

or change content to make it not in YAML format:

---
a\: b
---

Text after block extension

Some block extension in DFM cannot be recognized in GFM. In GFM, it would be treated as a part of paragraph. Then, following content would be treated as a part of paragraph.

For example:

> [!NOTE]
>     This is code.

In GFM, it will be rendered as a paragraph with content [!NOTE] This is code. in blockquote.
In DFM, it will be rendered as a code in note.