Ler em inglês

Compartilhar via

Usar links na documentação

  • Artigo

Este artigo descreve como usar hiperlinks de páginas hospedadas no Microsoft Learn. É fácil adicionar links em markdown com poucas variações de convenções. Os links direcionam os usuários para o conteúdo na mesma página, em páginas vizinhas ou em sites e URLs externos.

O back-end do site do Microsoft Learn usa o OPS (Open Publishing Services), que é compatível com o Markdown em conformidade com CommonMark analisado pelo mecanismo de análise Markdig. Essa variante de Markdown é compatível principalmente com o GitHub Flavored Markdown (GFM), já que a maioria dos documentos é armazenada no GitHub e pode ser editada lá. Mais funcionalidades são adicionadas pelas extensões de Markdown.

Importante

Todos os links devem ser seguros (https vs http) sempre que o destino der suporte a isso.

Texto do link

As palavras que você inclui no texto do link devem ser amigáveis. Em outras palavras, devem ser palavras normais em português ou o título da página que o link abre.

Importante

Não use "clique aqui" como texto do link. É ruim para a otimização do mecanismo de pesquisa e não descreve adequadamente o destino.

Correto:

  • For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

  • For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Incorreto:

  • For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

  • For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Links de um artigo para outro

Existem dois tipos de hiperlinks compatíveis com o sistema de publicação: URLs e links de arquivo.

Um link de URL pode ser um caminho de URL relativo à raiz de https://learn.microsoft.com ou uma URL absoluta que inclui a sintaxe de URL completa (por exemplo, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Use links de URL ao vincular o conteúdo fora do conjunto de documentos atual ou entre a referência gerada automaticamente e os artigos conceituais dentro do conjunto de documentos.
  • A maneira mais simples de criar um link relativo é copiar a URL do navegador e, em seguida, remover https://learn.microsoft.com/en-us do valor que você colar no markdown.
  • Não inclua localidades em URLs para as propriedades da Microsoft (por exemplo, remova /en-us da URL).

Um link de arquivo é usado para vincular de um artigo a outro dentro do conjunto de documentos.

  • Todos os caminhos de arquivo usam caracteres de barra (/) em vez de caracteres de barra invertida.

  • Um artigo é vinculado a outro artigo no mesmo diretório:

    [link text](article-name.md)

  • Um artigo é vinculado a um artigo no diretório pai do diretório atual:

    [link text](../article-name.md)

  • Um artigo é vinculado a um artigo no subdiretório do diretório atual:

    [link text](directory/article-name.md)

  • Um artigo é vinculado a um artigo em um subdiretório do diretório pai do diretório atual:

    [link text](../directory/article-name.md)

  • Alguns artigos consistem em um arquivo .yml e .md, em que o arquivo .yml contém metadados e o .md tem o conteúdo. Nesse caso, link para o arquivo .yml:

    [link text](../directory/article-name.yml) (não [link text](../directory/article-name-content.md))

Observação

Nenhum dos exemplos anteriores usa ~/ como parte do link. Para vincular a um caminho absoluto que começa na raiz do repositório, inicie o link com /. A inclusão de ~/ gera links inválidos ao navegar pelos repositórios de origem no GitHub. Iniciar o caminho com / resolve este problema corretamente.

O conteúdo publicado no Microsoft Learn tem a seguinte estrutura de URL:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Exemplos:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> – identifica o idioma do artigo (exemplo: en-us ou de-de)
  • <product-service> – o nome do produto ou serviço (exemplo: powershell, dotnet ou azure)
  • [<feature-service>] – (opcional) o nome do recurso ou subserviço do produto (exemplo: csharp ou balanceador de carga)
  • [<subfolder>] – (opcional) o nome de uma subpasta em um recurso
  • <topic> – o nome do arquivo de artigo para o tópico (exemplo: load-balancer-overview ou visão geral)
  • [?view=\<view-name>] – (opcional) o nome da exibição usado pelo seletor de versão para o conteúdo que tem várias versões disponíveis (exemplo: azps-3.5.0)

Dica

Na maioria dos casos, os artigos no mesmo conjunto de documentos têm o mesmo fragmento de URL <product-service>. Por exemplo:

  • Mesmo conjunto de documentos:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Conjunto de documentos diferente:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Para um link com indicador que faz o direcionamento para um título no arquivo atual, use um símbolo de hash seguido pelas palavras minúsculas do título. Remova a pontuação do título e substitua espaços por traços:

[Managed Disks](#managed-disks)

Para vincular a um título de indicador em outro artigo, use o link relativo ao arquivo ou relativo ao site além de um símbolo de hash, seguido pelas palavras do título. Remova a pontuação do título e substitua espaços por traços:

[Managed Disks](../../linux/overview.md#managed-disks)

Você também pode copiar o link com indicador da URL. Para localizar a URL, passe o mouse sobre a linha do título no Microsoft Learn. Você verá um ícone de link ser exibido:

Ícone de link no título do artigo

Clique no ícone de link e copie o texto de âncora do indicador da URL (ou seja, a parte após o hash).

Observação

A extensão Markdown do Learn também tem ferramentas para ajudar a criar links.

Adicionar links do tipo âncora explícitos que usam a marca HTML <a> não é obrigatório nem recomendado, exceto nas páginas de hub e de aterrissagem. Em vez disso, use os indicadores gerados automaticamente conforme descrito nos links com indicadores. Para páginas de hub e de aterrissagem, declare as âncoras desta forma:

## <a id="anchortext" />Header text

ou

## <a name="anchortext" />Header text

E o seguinte para vincular à âncora:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Observação

O texto de ancoragem deve estar sempre em minúsculas e não conter espaços.

Os links XRef são a maneira recomendada de vincular a APIs, pois facilitam a personalização do texto do link. Além disso, eles são validados no momento da compilação e, se a URL para a referência da API for alterada, o link ainda funcionará. Para vincular as páginas de referência de API geradas automaticamente no conjunto de documentos atual ou em outros conjuntos de documentos, use links XRef com a UID (ID exclusiva) do tipo ou membro.

Dica

A extensão Auxiliar de Link de Referência de API para VS Code facilita muito a inserção de links Xref da API do .NET em arquivos Markdown e XML.

Verifique se a API que você deseja vincular está no Microsoft Learn digitando todo ou parte do nome completo dela na caixa de pesquisa do navegador de API do .NET ou da Windows UWP. Se você não está vendo nenhum resultado, o tipo ainda não está no Microsoft Learn.

Você pode usar uma das seguintes sintaxes:

  • Links automáticos:

    <xref:UID>
<xref:UID?displayProperty=nameWithType>

    Por padrão, o texto do link mostra apenas o nome do membro ou do tipo. O parâmetro de consulta displayProperty=nameWithType opcional produz texto de link totalmente qualificado, ou seja, namespace.type para tipos e type.member para membros de tipo, incluindo membros de tipo de enumeração.

  • Links de estilo markdown:

    [link text](xref:UID)

    use links de estilo markdown para XRef quando desejar personalizar o texto do link exibido.

Exemplos:

  • <xref:System.String> é exibido como String

  • <xref:System.String?displayProperty=nameWithType> é exibido como System.String

  • [String class](xref:System.String) é exibido como String class.

O parâmetro de consulta displayProperty=fullName funciona da mesma maneira que displayProperty=nameWithType para classes. Ou seja, o texto do link se torna namespace.classname. No entanto, para membros, o texto do link é exibido como namespace.classname.membername, o que poderia ser indesejável.

Observação

UIDs diferenciam maiúsculas de minúsculas. Por exemplo, <xref:System.Object> é resolvido corretamente, mas <xref:system.object> não.

Determinar a UID

A UID geralmente é o nome de classe ou de membro totalmente qualificado. Clique com o botão direito do mouse na página do Microsoft Learn para um tipo ou membro, selecione Exibir origem e, em seguida, copie o valor conteúdo para ms.assetid.

ms.assetid na origem para a página da Web

Percentual de codificação de URLs

Os caracteres especiais na UID precisam ser codificados em percentual da seguinte maneira:

Caracter Codificação HTML
* *

Exemplo de codificação:

  • System.Exception.#ctor é codificado como System.Exception.%23ctor

Tipos genéricos

Os tipos genéricos são aqueles como System.Collections.Generic.List<T>. Se você navegar até esse tipo no navegador de API do .NET e examinar a URL dele, verá que <T> é escrito como -1 na URL, que realmente representa `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Métodos

Para vincular a um método, você pode vincular à página geral do método adicionando um asterisco (*) após o nome do método ou a uma sobrecarga específica. Por exemplo, use a página geral quando desejar vincular ao método <xref:System.Object.Equals*?displayProperty=nameWithType> sem tipos de parâmetro específicos. Por exemplo:

<xref:System.Object.Equals*?displayProperty=nameWithType> é vinculado a Object.Equals

Para vincular a uma sobrecarga específica, adicione parênteses após o nome do método e inclua o nome completo do tipo de cada parâmetro. Não coloque um caractere de espaço entre os nomes de tipo ou o link não funcionará. Por exemplo:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> é vinculado a Object.Equals(Object, Object)

Como os arquivos de inclusão estão localizados em outro diretório, você deve usar caminhos relativos mais longos. Para vincular a um artigo de um arquivo de inclusão, use este formato:

[link text](../articles/folder/article-name.md)

Dica

A extensão Pacote de Criação do Learn para Visual Studio Code ajuda a inserir links e indicadores relativos corretamente sem o tédio de ter que adivinhar os caminhos.

Um seletor é um componente da navegação que aparece em artigos de documentação como uma lista suspensa. Quando um leitor seleciona um valor na lista suspensa, o navegador abre o artigo selecionado. Normalmente, a lista do seletor contém links para artigos com relação próxima, por exemplo, com o mesmo tema em diversas linguagens de programação ou uma série de artigos com relação próxima.

Se você tiver seletores inseridos em uma inclusão, use a seguinte estrutura de link:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Você pode usar os links em estilo de referência para facilitar a leitura do conteúdo de origem. Os links em estilo de referência substituem a sintaxe do link embutido por uma sintaxe simplificada que permite mover as URLs longas para o final do artigo. Veja o exemplo do Daring Fireball:

Texto embutido:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Referências de link ao final do artigo:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Lembre-se de incluir o espaço após os dois-pontos, antes do link. Ao vincular com outros artigos técnicos, se você se esquecer de incluir o espaço, o link quebrará no artigo publicado.

Para vincular a uma página em outra propriedade da Microsoft (como uma página de preço, uma página de SLA ou qualquer coisa que não seja um artigo de documentação), use uma URL absoluta, mas omita a localidade. O objetivo aqui é que os links funcionem no GitHub e no site renderizado:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

A melhor experiência de usuário reduz ao máximo o envio do usuário para outro site. Portanto, os links para sites de terceiros, dos quais precisamos às vezes, devem se basear nestas informações:

  • Responsabilidade: vincule ao conteúdo de terceiros quando as informações que você deseja compartilhar forem de terceiros. Por exemplo, não é papel da Microsoft informar às pessoas como usar as ferramentas para desenvolvedores do Android. Isso é responsabilidade do Google. Se precisarmos, podemos explicar como usar as ferramentas de desenvolvedor do Android com o Azure, mas o Google deve instruir como usar suas ferramentas.
  • Aprovação do PM: solicite que a Microsoft aprove o conteúdo de terceiros. Ao vincular, estamos afirmando nossa confiança nesse conteúdo e nossas obrigações caso a pessoa siga as instruções.
  • Análises de atualização: verifique se as informações de terceiros ainda estão atualizadas e corretas, se são relevantes e se o link não mudou.
  • Externo: informe aos usuários que eles vão acessar outro site. Se o contexto não deixar isso claro, adicione uma frase de esclarecimento. Por exemplo: "Os pré-requisitos incluem as Ferramentas para Desenvolvedores do Android, que podem ser baixadas no site do Android Studio".
  • Próximas etapas: você pode adicionar um link para, por exemplo, um blog de MVP em uma seção "Próximas etapas". Mas, novamente, tenha certeza de que os usuários entenderão que estão saindo do site.
  • Jurídico: estamos cobertos juridicamente em Links para sites de terceiros no rodapé dos Termos de Uso de todas as páginas do microsoft.com.