Como usar o Markdown para escrever DocsHow to use Markdown for writing Docs

Os artigos do docs.microsoft.com são escritos em uma linguagem de marcação leve chamada Markdown, que é fácil de ler e fácil de aprender.Docs.microsoft.com articles are written in a lightweight markup language called Markdown, which is both easy to read and easy to learn. Por isso, tornou-se rapidamente um padrão do setor.Because of this, it has quickly become an industry standard.

Como o conteúdo do Docs é armazenado no GitHub, ele pode usar um superconjunto de Markdown chamado GFM (GitHub Flavored Markdown), que fornece mais funcionalidades para necessidades de formatação comuns.Because Docs content is stored in GitHub, it can use a superset of Markdown called GitHub Flavored Markdown (GFM), which provides additional functionality for common formatting needs. Além disso, o OPS (Open Publishing Services) implementa o Analisador de Markdown Markdig.Additionally, Open Publishing Services (OPS) implements Markdig Markdown Parser. O Markdig é altamente compatível com o GFM (GitHub Flavored Markdown), agregando funcionalidades para habilitar recursos específicos do Docs.Markdig is highly compatible with GitHub Flavored Markdown (GFM), adding functionality to enable Docs-specific features.

  • O Markdig é um processador de Markdown extensível, em conformidade com CommonMark potente e rápido para .NET.Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET.
  • https://github.com/lunet-io/markdig
  • Melhor suporte da comunidadeBetter community support
  • Melhor suporte de padrõesBetter standards support

Noções básicas de markdownMarkdown basics

TítulosHeadings

Para criar um título, use uma marca de hash (#), da seguinte forma:To create a heading, you use a hash mark (#), as follows:

    # This is heading 1
    ## This is heading 2
    ### This is heading 3
    #### This is heading 4

Texto em negrito e em itálicoBold and italic text

Para formatar o texto como negrito, coloque dois asteriscos de cada lado do texto:To format text as bold, you enclose it in two asterisks:

    This text is **bold**.

Para formatar o texto como itálico, coloque um único asterisco de cada lado do texto:To format text as italic, you enclose it in a single asterisk:

    This text is *italic*.

Para formatar o texto como negrito e itálico, coloque três asteriscos de cada lado do texto:To format text as both bold and italic, you enclose it in three asterisks:

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

ListasLists

Lista não ordenadaUnordered list

Para formatar uma lista não ordenada/com marcador, use asteriscos ou traços.To format an unordered/bulleted list, you can use either asterisks or dashes. Por exemplo, o Markdown a seguir:For example, the following Markdown:

- List item 1
- List item 2
- List item 3

será renderizado como:will be rendered as:

  • Item de lista 1List item 1
  • Item de lista 2List item 2
  • Item de lista 3List item 3

Para aninhar uma lista em outra lista, recue os itens de lista filha.To nest a list within another list, indent the child list items. Por exemplo, o Markdown a seguir:For example, the following Markdown:

- List item 1
  - List item A
  - List item B
- List item 2

será renderizado como:will be rendered as:

  • Item de lista 1List item 1
    • Item de lista AList item A
    • Item de lista BList item B
  • Item de lista 2List item 2

Lista ordenadaOrdered list

Para formatar uma lista ordenada/gradual, use números correspondentes.To format an ordered/stepwise list, you use corresponding numbers. Por exemplo, o Markdown a seguir:For example, the following Markdown:

1. First instruction
2. Second instruction
3. Third instruction

será renderizado como:will be rendered as:

  1. Primeira instruçãoFirst instruction
  2. Segunda instruçãoSecond instruction
  3. Terceira instruçãoThird instruction

Para aninhar uma lista em outra lista, recue os itens de lista filha.To nest a list within another list, indent the child list items. Por exemplo, o Markdown a seguir:For example, the following Markdown:

1. First instruction
    1. Sub-instruction
    2. Sub-instruction
2. Second instruction

será renderizado como:will be rendered as:

  1. Primeira instruçãoFirst instruction
    1. SubinstruçãoSub-instruction
    2. SubinstruçãoSub-instruction
  2. Segunda instruçãoSecond instruction

TabelasTables

As tabelas não fazem parte da especificação principal do Markdown, mas são compatíveis com o GFM.Tables are not part of the core Markdown specification, but GFM supports them. Você pode criar tabelas usando os caracteres barra vertical (|) e hífen (-).You can create tables by using the pipe (|) and hyphen (-) characters. Os hifens criam o cabeçalho de cada coluna e as barras verticais separam cada coluna.Hyphens create each column's header, while pipes separate each column. Inclua uma linha em branco antes da sua tabela para que a renderização ocorra corretamente.Include a blank line before your table so it's rendered correctly.

Por exemplo, o Markdown a seguir:For example, the following Markdown:

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

será renderizado como:will be rendered as:

DiversãoFun ComWith TabelasTables
coluna alinhada à esquerdaleft-aligned column coluna alinhada à direitaright-aligned column coluna centralizadacentered column
$100$100 $100$100 $100$100
$10$10 $10$10 $10$10
$1$1 $1$1 $1$1

Para saber mais sobre como criar tabelas, consulte:For more information on creating tables, see:

A sintaxe do Markdown para um link embutido é composta pela parte [link text], que é o texto que receberá o hiperlink, seguida pela parte (file-name.md), que é a URL ou o nome do arquivo de destino do link:The Markdown syntax for an inline link consists of the [link text] portion, which is the text that will be hyperlinked, followed by the (file-name.md) portion, which is the URL or file name that's being linked to:

[link text](file-name.md)

Para saber mais sobre vinculação, confira:For more information on linking, see:

  • O guia de sintaxe do Markdown para obter detalhes sobre o suporte à vinculação de base do Markdown.The Markdown syntax guide for details on Markdown's base linking support.
  • A seção Links deste guia para obter detalhes sobre a sintaxe de vinculação adicional que o Markdig fornece.The Links section of this guide for details on additional linking syntax that Markdig provides.

Trechos de códigoCode snippets

O Markdown é compatível com o posicionamento de trechos de código, seja embutido em uma sentença, seja como um bloco "isolado" e separado entre as sentenças.Markdown supports the placement of code snippets both inline in a sentence and as a separate "fenced" block between sentences. Para obter detalhes, consulte:For details, see:

Os blocos de código isolados representam uma maneira fácil de habilitar o destaque de sintaxe para seus trechos de código.Fenced code blocks are an easy way to enable syntax highlighting for your code snippets. O formato geral dos blocos de código isolados é:The general format for fenced code blocks is:

```alias
...
your code goes in here
...
```

O alias após os três caracteres de acento grave (`) iniciais define o destaque de sintaxe a ser usado.The alias after the initial three backtick (`) characters defines the syntax highlighting to be used. Veja a seguir uma lista de linguagens de programação normalmente usadas no conteúdo do Docs e no rótulo correspondente:The following is a list of commonly used programming languages in Docs content and the matching label:

Essas linguagens têm o suporte de nome amigável e a maioria tem realce de linguagem.These languages have friendly name support and most have language highlighting.

NomeName Rótulo de MarkdownMarkdown Label
Console do .NET.NET Console dotnetclidotnetcli
ASP.NET (C#)ASP.NET (C#) aspx-csharpaspx-csharp
ASP.NET (VB)ASP.NET (VB) aspx-vbaspx-vb
AzCopyAzCopy azcopyazcopy
CLI do AzureAzure CLI azurecliazurecli
Azure PowerShellAzure PowerShell azurepowershellazurepowershell
C++C++ cppcpp
C++/CXC++/CX cppcxcppcx
C++/WinRTC++/WinRT cppwinrtcppwinrt
C#C# csharpcsharp
CSHTMLCSHTML cshtmlcshtml
DAXDAX daxdax
F#F# fsharpfsharp
GoGo gogo
HTMLHTML htmlhtml
HTTPHTTP httphttp
JavaJava javajava
JavaScriptJavaScript javascriptjavascript
JSONJSON jsonjson
MarkdownMarkdown mdmd
NodeJSNodeJS nodejsnodejs
Objective-CObjective-C objcobjc
ODataOData odataodata
PHPPHP phpphp
Power Apps FormulaPower Apps Formula powerappsflpowerappsfl
PowerShellPowerShell powershellpowershell
PythonPython pythonpython
Q#Q# qsharpqsharp
RubyRuby rubyruby
SQLSQL sqlsql
SwiftSwift swiftswift
TypeScriptTypeScript typescripttypescript
VBVB vbvb
VSTS CLIVSTS CLI vstsclivstscli
XAMLXAML xamlxaml
XMLXML xmlxml

Exemplo: C#Example: C#

MarkdownMarkdown

```csharp
// Hello1.cs
public class Hello1
{
    public static void Main()
    {
        System.Console.WriteLine("Hello, World!");
    }
}
```

RenderizaçãoRender

// Hello1.cs
public class Hello1
{
    public static void Main()
    {
        System.Console.WriteLine("Hello, World!");
    }
}

Exemplo: SQLExample: SQL

MarkdownMarkdown

```sql
CREATE TABLE T1 (
  c1 int PRIMARY KEY,
  c2 varchar(50) SPARSE NULL
);
```

RenderizaçãoRender

CREATE TABLE T1 (
  c1 int PRIMARY KEY,
  c2 varchar(50) SPARSE NULL
);

Extensões de Markdown personalizada do OPSOPS custom Markdown extensions

Observação

O OPS (Open Publishing Services) implementa um Analisador de Markdown Markdig, que é altamente compatível com o GFM (GitHub Flavored Markdown).Open Publishing Services (OPS) implements a Markdig Parser for Markdown, which is highly compatible with GitHub Flavored Markdown (GFM). O Markdig adiciona algumas funcionalidades por meio de extensões de Markdown.Markdig adds some functionality through Markdown extensions. Portanto, alguns artigos selecionados no Guia de Criação do OPS completo foram incluídos neste guia para referência.As such, selected articles from the full OPS Authoring Guide are included in this guide for reference. (Por exemplo, veja "extensões de Markdown e Markdig" e "Trechos de código" no sumário.)(For example, see "Markdig and Markdown extensions" and "Code snippets" in the table of contents.)

Os artigos do Docs usam o GFM para a maior parte da formatação do artigo, como parágrafos, links, listas e cabeçalhos.Docs articles use GFM for most article formatting, such as paragraphs, links, lists, and headings. Para uma formatação mais avançada, os artigos podem usar recursos do Markdig, como:For richer formatting, articles can use Markdig features such as:

  • Blocos de notaNote blocks
  • InclusõesIncludes
  • SeletoresSelectors
  • Vídeos incorporadosEmbedded videos
  • Trechos/amostras de códigoCode snippets/samples

Para obter a lista completa, veja "extensões de Markdown e Markdig" e "Trechos de código" no sumário.For the complete list, refer to "Markdig and Markdown extensions" and "Code snippets" in the table of contents.

Blocos de notaNote blocks

Você pode escolher entre quatro tipos de blocos de notas para chamar atenção para um conteúdo específico:You can choose from four types of note blocks to draw attention to specific content:

  • OBSERVAÇÃONOTE
  • AVISOWARNING
  • DICATIP
  • IMPORTANTEIMPORTANT

Em geral, os blocos de notas devem ser usados com moderação porque eles podem atrapalhar.In general, note blocks should be used sparingly because they can be disruptive. Embora eles também deem suporte para blocos de código, imagens, listas e links, tente manter seus blocos de nota simples e diretos.Although they also support code blocks, images, lists, and links, try to keep your note blocks simple and straightforward.

InclusõesIncludes

Quando você tiver um texto ou arquivos de imagem reutilizáveis que precisem ser incluídos nos arquivos do artigo, use uma referência ao arquivo de "inclusão" por meio do recurso de inclusão de arquivo do Markdig.When you have reusable text or image files that need to be included in article files, you can use a reference to the "include" file via the Markdig file include feature. Esse recurso instrui o OPS a incluir o arquivo no arquivo do artigo no tempo de build, para que ele faça parte do artigo publicado.This feature instructs OPS to include the file in your article file at build time, making it part of your published article. Três tipos de inclusões estão disponíveis para ajudá-lo a reutilizar o conteúdo:Three types of includes are available to help you reuse content:

  • Embutido: reutilize um trecho de texto comum embutido dentro de outra frase.Inline: Reuse a common text snippet inline with within another sentence.
  • Bloco: reutilize um arquivo Markdown inteiro como um bloco aninhado dentro de uma seção de um artigo.Block: Reuse an entire Markdown file as a block, nested within a section of an article.
  • Imagem: é como a inclusão de imagem padrão é implementada no Docs.Image: This is how standard image inclusion is implemented in Docs.

A inclusão de um embutido ou de um bloco é apenas um arquivo Markdown (.md) simples.An inline or block include is just a simple Markdown (.md) file. Ele pode conter qualquer Markdown válido.It can contain any valid Markdown. Todos os arquivos Markdown de inclusão devem ser colocados em um subdiretório /includes comum, na raiz do repositório.All include Markdown files should be placed in a common /includes subdirectory, in the root of the repository. Quando o artigo é publicado, o arquivo incluído fica perfeitamente integrado.When the article is published, the included file is seamlessly integrated into it.

Aqui estão os requisitos e as considerações para inclusões:Here are requirements and considerations for includes:

  • Use inclusões sempre que precisar que o mesmo texto apareça em vários artigos.Use includes whenever you need the same text to appear in multiple articles.
  • Use inclusões em bloco para quantidades consideráveis de conteúdo, como um ou dois parágrafos, um procedimento compartilhado ou uma seção compartilhada.Use block includes for significant amounts of content--a paragraph or two, a shared procedure, or a shared section. Não use-os para nada menor do que uma sentença.Do not use them for anything smaller than a sentence.
  • As inclusões não serão renderizadas no modo de exibição renderizado do GitHub do seu artigo, pois elas dependem de extensões do Markdig.Includes won't be rendered in the GitHub rendered view of your article, because they rely on Markdig extensions. Elas serão renderizadas somente após a publicação.They'll be rendered only after publication.
  • Verifique se todo o texto em uma inclusão está escrito em sentenças ou frases completas que não dependem do texto anterior ou seguinte no artigo que faz referência à inclusão.Ensure that all the text in an include is written in complete sentences or phrases that do not depend on preceding text or following text in the article that references the include. Se você ignorar essa orientação, criará uma cadeia de caracteres não traduzível no artigo que quebrará a experiência localizada.Ignoring this guidance creates an untranslatable string in the article that breaks the localized experience.
  • Não incorpore inclusões dentro de outras inclusões.Don't embed includes within other includes. Não há suporte para isso.They are not supported.
  • Coloque os arquivos de mídia em uma pasta de mídia específica para o subdiretório de inclusão, por exemplo, a pasta <repo>/includes/media.Place media files in a media folder that's specific to the include subdirectory--for instance, the <repo>/includes/media folder. O diretório de mídia não deve conter imagens em sua raiz.The media directory should not contain any images in its root. Se a inclusão não tiver imagens, não será necessário ter um diretório de mídia correspondente.If the include does not have images, a corresponding media directory is not required.
  • Assim como ocorre com os artigos regulares, não compartilhe a mídia entre arquivos de inclusão.As with regular articles, don't share media between include files. Use um arquivo separado com um nome exclusivo para cada inclusão e artigo.Use a separate file with a unique name for each include and article. Armazene o arquivo de mídia na pasta de mídia associada à inclusão.Store the media file in the media folder that's associated with the include.
  • Não use uma inclusão como único conteúdo de um artigo.Don't use an include as the only content of an article. As inclusões servem como complemento ao conteúdo do restante do artigo.Includes are meant to be supplemental to the content in the rest of the article.

SeletoresSelectors

Use seletores em artigos técnicos ao criar vários tipos do mesmo artigo, a fim de solucionar diferenças de implementação entre tecnologias e plataformas.Use selectors in technical articles when you author multiple flavors of the same article, to address differences in implementation across technologies or platforms. Normalmente, isso é mais aplicável ao nosso conteúdo de plataforma móvel para desenvolvedores.This is typically most applicable to our mobile platform content for developers. No momento, há dois tipos diferentes de seletores no Markdig, um seletor único e um seletor múltiplo.There are currently two different types of selectors in Markdig, a single selector and a multi-selector.

Como o mesmo Markdown seletor vai para cada artigo na seleção, recomendamos posicionar o seletor do artigo em uma inclusão.Because the same selector Markdown goes in each article in the selection, we recommend placing the selector for your article in an include. Em seguida, você poderá referenciar essa inclusão em todos os artigos que usarem o mesmo seletor.Then you can reference that include in all your articles that use the same selector.

Trechos de códigoCode snippets

O Markdig também é compatível com a inclusão avançada de código em um artigo por meio de sua extensão de trecho de código.Markdig supports advanced inclusion of code in an article, via its code snippet extension. Ela fornece renderização avançada que aproveita os recursos do GFM, como seleção de linguagem de programação e coloração de sintaxe, além de recursos incríveis como:It provides advanced rendering that builds on GFM features such as programming language selection and syntax coloring, plus nice features such as:

  • Inclusão de amostras/trechos de código centralizados de um repositório externo.Inclusion of centralized code samples/snippets from an external repository.
  • Interface do usuário com guias para mostrar várias versões de amostras de código em linguagens diferentes.Tabbed UI to show multiple versions of code samples in different languages.

Armadilhas e solução de problemasGotchas and troubleshooting

Texto AltAlt text

Textos Alt que contenham caracteres sublinhado não serão renderizados adequadamente.Alt text that contains underscores won't be rendered properly. Por exemplo, em vez de usar isto:For example, instead of using this:

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

Insira um escape para os sublinhados desta forma:Escape the underscores like this:

![ADextension\_2FA\_Configure\_Step4] (./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Apóstrofes e aspasApostrophes and quotation marks

Se você copiar do Word para um editor de Markdown, o texto poderá conter apóstrofes ou aspas "inteligentes" (inglesas).If you copy from Word into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation marks. Eles precisam ser codificados ou alterados para apóstrofos ou aspas simples.These need to be encoded or changed to basic apostrophes or quotation marks. Caso contrário, quando o arquivo for publicado poderão ocorrer erros como: It’sOtherwise, you end up with things like this when the file is published: It’s

Estas são as codificações para as versões "inteligentes" dessas marcas de pontuação:Here are the encodings for the "smart" versions of these punctuation marks:

  • Aspas à esquerda (de abertura): &#8220;Left (opening) quotation mark: &#8220;
  • Aspas à direita (de fechamento): &#8221;Right (closing) quotation mark: &#8221;
  • Aspas simples à direita (de fechamento) ou apóstrofe: &#8217;Right (closing) single quotation mark or apostrophe: &#8217;
  • Aspas simples à esquerda (de abertura) (raramente usadas): &#8216;Left (opening) single quotation mark (rarely used): &#8216;

Colchetes angularesAngle brackets

Se você usar colchetes angulares no texto (não no código) no arquivo, por exemplo, para indicar um espaço reservado, será necessário codificar manualmente os colchetes angulares.If you use angle brackets in text (not code) in your file--for example, to denote a placeholder--you need to manually encode the angle brackets. Caso contrário, o Markdown entenderá que eles são uma marca HTML.Otherwise, Markdown thinks that they're intended to be an HTML tag.

Por exemplo, codifique <script name> como &lt;script name&gt;For example, encode <script name> as &lt;script name&gt;

Consulte tambémSee also

Recursos do MarkdownMarkdown resources