Share via

Utilizar ligações na documentação

  • Artigo

Este artigo descreve como utilizar hiperligações de páginas alojadas no Microsoft Learn. As ligações são fáceis de adicionar em markdown com algumas convenções variáveis. As ligações direcionam os utilizadores para conteúdos na mesma página, outras páginas vizinhas ou sites e URLs externos.

O back-end do Microsoft Learn utiliza o Open Publishing Services (OPS), que suporta markdown compatível com CommonMark analisado através do motor de análise Markdig . Esta variante de markdown é em grande parte compatível com o GitHub Flavored Markdown (GFM), uma vez que a maioria dos documentos é armazenada no GitHub e pode ser editada no mesmo. São adicionadas mais funcionalidades através das extensões do Markdown.

Importante

Todas as ligações têm de ser seguras (https vs http) sempre que o destino o suportar (sendo que a grande maioria deve fazê-lo).

Texto da ligação

As palavras que inclui no texto da ligação devem ser amigáveis. Por outras palavras, devem ser utilizados termos normais em português ou o título da página para o qual está a criar a ligação.

Importante

Não utilize "clique aqui" como texto de ligação. Não é útil para otimização do motor de busca e não descreve adequadamente o texto de 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).

Ligações de um artigo para outro

Existem dois tipos de hiperligações suportadas pelo sistema de publicação: Os URLs e as ligações a ficheiros.

Uma ligação de URL pode ser um caminho de URL relativo à raiz de https://learn.microsoft.com, ou um URL absoluto que inclua a sintaxe completa do URL (por exemplo, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Utilize ligações URL ao ligar a conteúdos fora do conjunto de documentos atual ou entre uma referência gerada automaticamente e artigos conceptuais dentro do conjunto de documentos.
  • A forma mais simples de criar uma ligação relativa é copiar o URL do seu browser e, em seguida, remover https://learn.microsoft.com/en-us do valor que colou no markdown.
  • Não inclua regiões em URLs para propriedades da Microsoft (por exemplo, remover /en-us do URL).

Uma ligação a ficheiro é utilizada para ligar de um artigo para outro dentro do conjunto de documentos.

  • Todos os caminhos de ficheiro utilizam carateres de barra (/) em vez de carateres de barra invertida.

  • Um artigo liga a outro artigo no mesmo diretório:

    [link text](article-name.md)

  • Um artigo liga a um artigo no diretório principal do diretório atual:

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

  • Um artigo liga a um artigo num subdiretório do diretório atual:

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

  • Um artigo liga a um artigo num subdiretório do diretório principal do diretório atual:

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

  • Alguns artigos consistem num .yml ficheiro e .md , em que o .yml ficheiro contém metadados e contém .md o conteúdo. Nesse caso, ligue ao .yml ficheiro:

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

Nota

Nenhum dos exemplos anteriores utiliza ~/ como parte da ligação. Para ligar a um caminho absoluto que tem início na raiz do repositório, comece a ligação com /. Incluir ~/ produz ligações inválidas ao navegar nos repositórios de código fonte no GitHub. Se começar o caminho com /, a ligação funcionará 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 da funcionalidade ou subserviço do produto (exemplo: csharp ou balanceador de carga)
  • [<subfolder>] – (opcional) o nome de uma subpasta dentro de uma funcionalidade
  • <topic> – o nome do ficheiro do artigo para o tópico (exemplo: descrição geral do balanceador de carga ou descrição geral)
  • [?view=\<view-name>] – (opcional) o nome da vista utilizado pelo seletor de versão para conteúdos que tenham múltiplas 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 ligar um marcador a um cabeçalho no ficheiro atual, utilize um símbolo de cardinal, seguido das palavras em minúsculas do cabeçalho. Remova a pontuação do cabeçalho e substitua os espaços por travessões:

[Managed Disks](#managed-disks)

Para ligar a um cabeçalho de marcador noutro artigo, utilize a ligação relativa ao site ou relativa ao ficheiro, bem como um símbolo de cardinal, seguido das palavras do cabeçalho. Remova a pontuação do cabeçalho e substitua os espaços por travessões:

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

Também pode copiar a ligação de marcador a partir do URL. Para localizar o URL, paire o rato sobre a linha de cabeçalho no Microsoft Learn. Deverá ver aparecer um ícone de ligação:

Ícone de ligação no cabeçalho do artigo

Clique no ícone de ligação e, em seguida, copie o texto de âncora do marcador do URL (isto é, a parte após o hash).

Nota

A extensão Do Learn Markdown também tem ferramentas para ajudar a criar ligações.

A adição de ligações de âncora explícitas que utilizam a etiqueta de HTML <a> não é obrigatória nem recomendada, exceto em páginas de hubs e de destino. Em vez disso, utilize os marcadores gerados automaticamente como descrito em ligações de marcadores. Para páginas de hubs e de destino, declare âncoras da seguinte forma:

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

ou

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

E o seguinte para ligar à âncora:

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

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

Nota

o texto da âncora deve ser sempre em minúsculas e não conter espaços.

As ligações XRef são a forma recomendada de ligar às APIs, porque são validadas no momento da compilação. Para ligar a páginas de referência de API geradas automaticamente no conjunto de documentos atual ou noutros, utilize ligações XRef com o ID exclusivo (UID) do tipo ou membro.

Dica

Pode utilizar a extensão Learn Markdown para VS Code (parte do Pacote de Criação do Learn) para inserir ligações .NET XRref que são apresentadas no Browser de API .NET.

Verifique se a API à qual pretende ligar está publicada no Microsoft Learn ao escrever todo ou algum do respetivo nome completo no browser da API .NET ou na caixa de pesquisa do Windows UWP . Se não vir resultados apresentados, o tipo ainda não está no Microsoft Learn.

Pode utilizar uma das sintaxes seguintes:

  • Ligações automáticas:

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

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

  • Ligações de estilo markdown:

    [link text](xref:UID)

    Utilize as ligações de estilo Markdown para XRef quando quiser personalizar o texto da ligação que é apresentado.

Exemplos:

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

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

  • [Classe de cadeia](xref:System.String) é apresentada como Classe de cadeia.

O parâmetro de consulta displayProperty=fullName funciona da mesma forma que displayProperty=nameWithType para as classes. Ou seja, o texto da ligação torna-se namespace.classname. No entanto, para os membros, o texto da ligação é apresentado como namespace.classname.membername, o que pode ser indesejável.

Nota

Os UID são sensíveis a maiúsculas e minúsculas. Por exemplo, <xref:System.Object> funcionará corretamente, mas <xref:system.object> não.

Avisos de compilação de XRef e compilações incrementais

Uma compilação incremental só compila ficheiros que foram alterados ou foram afetados por uma alteração. Se vir um aviso de compilação sobre uma ligação XREF inválida, mas a ligação for válida, tal pode dever-se ao facto de a compilação ter sido incremental. O ficheiro que provocou o aviso não foi alterado, por isso não foi compilado e foram repetidos os avisos passados. O aviso irá desaparecer quando o ficheiro alterar ou se acionar uma compilação completa (pode iniciar uma compilação completa em ops.microsoft.com). Esta é uma desvantagem das compilações incrementais, porque o DocFX não consegue detetar uma atualização de dados dentro do serviço XREF.

Determinar o UID

O UID é normalmente a classe totalmente qualificada ou o nome do membro. Existem pelo menos duas maneiras de determinar o UID:

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

    ms.assetid na origem para a página Web

  • Utilize o site de preenchimento automático, ao anexar parte ou todo o nome do tipo ao URL. Por exemplo, a introdução de https://xref.docs.microsoft.com/autocomplete?text=Writeline na barra de endereço do seu browser apresenta todos os tipos e métodos que contêm Writeline no seu nome, juntamente com o seu UID.

Verificar o UID

Para testar se tem o UID correto, substitua System.String no seguinte URL pelo seu UID e, em seguida, cole-o na barra de endereço de um browser:

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

Dica

O UID no URL é sensível a maiúsculas e minúsculas. Além disso, se estiver a verificar um UID de sobrecarga de método, não inclua espaços entre os tipos de parâmetros.

Se vir algo como o seguinte, tem o UID correto:

[{"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 vir apenas [] apresentado na página, tem o UID errado.

Codificação em percentagem de URLs

Os carateres especiais no UID precisam de ter codificação HTML da seguinte forma:

Caráter Codificação HTML
` %60
# %23
* %2A

Veja uma lista completa de códigos de percentagem.

Exemplos de codificação:

  • System.Threading.Tasks.Task`1 codifica como System.Threading.Tasks.Task%601 (ver a secção sobre tipos genéricos)

  • System.Exception.#ctor codifica como System.Exception.%23ctor

  • System.Object.Equals* codifica como System.Object.Equals%2A

Tipos genéricos

Os tipos genéricos são tipos como System.Collections.Generic.List<T>. Se navegar para este tipo no browser da API .NET e observar o seu URL, verá que <T> está escrito como -1 no URL, que na verdade representa '1:

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

Para ligar a um tipo genérico, como Lista<T>, codifique o ` caráter de backtick como %60, conforme mostrado no exemplo seguinte:

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

Métodos

Para ligar a um método, pode ligar à página geral do método ao adicionar um asterisco (*) após o nome do método ou a uma sobrecarga específica. Por exemplo, utilize a página geral quando quiser ligar ao método <xref:System.Object.Equals%2A?displayProperty=nameWithType> sem tipos específicos de parâmetros. O caráter asterisco está codificado como %2A. Por exemplo:

<xref:System.Object.Equals%2a?displayProperty=nameWithType> liga a Object.Equals

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

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

Uma vez que os ficheiros de inclusão estão noutro diretório, deve utilizar caminhos relativos mais longos. Para ligar a um artigo a partir de um ficheiro de inclusão, utilize este formato:

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

Dica

A extensão Do Pacote de Criação do Learn para o Visual Studio Code ajuda-o a inserir ligações e marcadores relativos corretamente sem o tédio de descobrir caminhos.

Um seletor é um componente de navegação apresentado num artigo de documentação como uma lista pendente. Quando um leitor seleciona um valor na lista pendente, o browser apresenta o artigo selecionado. Normalmente, a lista do seletor contém ligações para artigos relacionados (por exemplo, o mesmo assunto em múltiplas linguagens ou uma série de artigos relacionados).

Se tiver seletores incorporados numa inclusão, utilize a seguinte estrutura de ligações:

> [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)

Pode utilizar as ligações de estilo de referência para tornar o conteúdo da origem mais fácil de ler. As ligações de estilo de referência substituem a sintaxe das ligações inline por uma sintaxe simplificada que lhe permite mover os URLs longos para o final do artigo. Veja a seguir o exemplo de Daring Fireball:

Texto inline:

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

Referências de ligações no final do artigo:

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

Certifique-se de que inclui o espaço após os dois pontos, antes da ligação. Quando liga a outros artigos técnicos, se se esquecer de incluir o espaço, a ligação no artigo publicado será inválida.

Para ligar a uma página noutra propriedade da Microsoft (como uma página de preços, uma página SLA ou outra página que não seja um artigo de documentação), utilize um URL absoluto, mas omita a região. O objetivo aqui é que as ligações funcionem tanto no GitHub como num site composto:

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

Para uma melhor experiência de utilizador, deverá minimizar-se o envio dos utilizadores para outro site. Desta forma, qualquer ligação para sites de terceiros, o que por vezes é necessário, deve basear-se nestas informações:

  • Responsabilidade: ligue a conteúdo de terceiros quando quiser partilhar as informações de terceiros. Por exemplo, não cabe à Microsoft indicar às pessoas como utilizar as ferramentas de programação do Android, essa função cabe à Google. Se precisarmos, podemos explicar como utilizar as ferramentas de programação do Android com o Azure, mas a Google é que deve explicar como utilizar as suas ferramentas.
  • Aprovação do PM: peça que a Microsoft aprove conteúdos de terceiros. Ao criar uma ligação para esse conteúdo, estamos a declarar a nossa confiança e a nossa obrigação caso as pessoas sigam as instruções.
  • Revisões atualizadas: confirme que as informações de terceiros continuam atualizadas, corretas e são relevantes e que a ligação não foi alterada.
  • Fora do local: informe os utilizadores de que vão para outro site. Se o conteúdo não tornar isso claro, acrescente uma expressão adequada. Por exemplo: "Os pré-requisitos incluem as Ferramentas de Programação do Android, que pode transferir no site Android Studio."
  • Passos seguintes: não há problema em adicionar uma ligação para, digamos, um blogue de um MVP na secção "Passos seguintes". Novamente, confirme que os utilizadores estão conscientes de que estão a sair do site.
  • Legal: estamos legalmente protegidos em Ligações para Sites de Terceiros no rodapé Termos de Utilização em cada página do microsoft.com.