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 Microsoft Learn usa o OPS (Open Publishing Services), que dá suporte ao markdown compatível com CommonMark analisado por meio do mecanismo de análise Markdig . Essa variante de markdown é compatível principalmente com o GitHub Flavored Markdown (GFM), já que a maioria dos documentos são armazenados no GitHub e podem ser editados lá. Mais funcionalidades são adicionadas pelas extensões de Markdown.

Importante

Todos os links devem ser protegidos (https e não http) quando o destino tiver suporte para eles (a grande maioria tem).

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

Há dois tipos de hiperlinks com suporte no sistema de publicação: Links de 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 .yml arquivo e .md , em que o .yml arquivo contém metadados e o .md contém o conteúdo. Nesse caso, vincule-se ao .yml arquivo:

    [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 docset:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Docset diferente:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Para um link de indicador que direciona a 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 do indicador da URL. Para localizar a URL, passe o mouse sobre a linha de 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 Do Learn Markdown 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 do indicador. 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 âncora 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 elas são validadas em tempo de build. 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

Você pode usar a extensão Markdown do Learn para VS Code (parte do Learn Authoring Pack) para inserir links XRref do .NET que são exibidos no Navegador de API do .NET.

Verifique se a API à qual você deseja vincular está publicada no Microsoft Learn digitando todo ou algum de seus nomes completos no navegador de API do .NET ou na caixa de pesquisa UWP do Windows . Se você não vir nenhum resultado exibido, 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 pode 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.

Avisos de build XRef e builds incrementais

Um build incremental só cria arquivos que foram alterados ou afetados por uma alteração. Se você visse um aviso de build sobre um link XREF inválido, mas o link fosse realmente válido, isso poderia ocorrer porque build era incremental. O arquivo que causou o aviso não foi alterado; assim, ele não foi criado e avisos passados foram reproduzidos. O aviso desaparecerá quando o arquivo for alterado ou se você disparar um build completo (você pode iniciar um build completo em ops.microsoft.com). Essa é uma desvantagem de build incrementais, porque o DocFX não pode detectar uma atualização de dados dentro do serviço XREF.

Determinar a UID

A UID geralmente é o nome de classe ou de membro totalmente qualificado. Há pelo menos duas maneiras de determinar a UID:

  • Clique com o botão direito do mouse na página do Microsoft Learn para um tipo ou membro, selecione Exibir origem e copie o valor do conteúdo para ms.assetid:

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

  • Use o site de preenchimento automático acrescentando todo o nome do tipo ou uma parte dele à URL. Por exemplo, inserir https://xref.docs.microsoft.com/autocomplete?text=Writeline na barra de endereços do navegador exibe todos os tipos e métodos que contêm Writeline no nome, juntamente com a UID.

Verificar a UID

Para testar se você tem a UID correta, substitua System.String na seguinte URL pela UID e cole-a na barra de endereços de um navegador:

https://xref.docs.microsoft.com/query?uid=System.String

Dica

A UID na URL diferencia maiúsculas de minúsculas e, se você estiver verificando uma UID de sobrecarga de método, não inclua espaços entre os tipos de parâmetro.

Se você está vendo algo semelhante ao seguinte, você tem a UID correta:

[{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,...xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"},{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,netframework-4.6,netframework-4.6.1,...,xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"}]

Se você apenas vê [] exibido na página, você tem a UID incorreta.

Percentual de codificação de URLs

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

Caractere Codificação HTML
` %60
# %23
* %2A

Confira uma lista completa de códigos percentuais.

Exemplos de codificação:

  • System.Threading.Tasks.Task`1 é codificado como System.Threading.Tasks.Task%601 (confira a seção sobre tipos genéricos)

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

  • System.Object.Equals* é codificado como System.Object.Equals%2A

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

Para vincular a um tipo genérico como List<T>>, codifique o caractere de acento grave ` como %60, conforme mostrado no seguinte exemplo:

<xref:System.Collections.Generic.List%601>

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%2A?displayProperty=nameWithType> sem tipos de parâmetro específicos. O caractere de asterisco é codificado como %2A. Por exemplo:

<xref:System.Object.Equals%2a?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 do Learn Authoring Pack para Visual Studio Code ajuda você a inserir links e indicadores relativos corretamente sem o tédio de descobrir 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 ser baseados 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 acessarão 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 a um blog do MVP, por exemplo, em uma seção de “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é Termos de Uso de todas as páginas do microsoft.com.