Partilhar via

Utilizar ligações na documentação

  • Artigo

Este artigo descreve como usar hiperlinks de páginas hospedadas 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 usa Open Publishing Services (OPS), que oferece suporte a Markdown compatível com CommonMark analisado por meio do mecanismo de análise Markdig . Este sabor de Markdown é principalmente compatível com o GitHub Flavored Markdown (GFM), já que a maioria dos documentos são armazenados no GitHub e podem ser editados lá. São adicionadas mais funcionalidades através das extensões do Markdown.

Importante

Todos os links devem ser seguros (https vs http) sempre que o alvo o suportar.

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 use "clique aqui" como texto do link. 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

Há dois tipos de hiperlinks suportados pelo sistema de publicação: URLs e links de arquivos.

Um link de URL pode ser um caminho de URL relativo à raiz de , ou um URL absoluto que inclui a sintaxe completa de https://learn.microsoft.comURL (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 localidades em URLs para propriedades da Microsoft (por exemplo, remova /en-us da 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 em um .yml e .md arquivo, onde o .yml arquivo contém metadados e o .md contém o conteúdo. Nesse caso, link para o .yml arquivo:

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

Gorjeta

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
  • Diferentes docset:
    • 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 encontrar o URL, passe o mouse sobre a linha de título 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 Learn Markdown também tem ferramentas para ajudar a criar links.

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.

Os links XRef são a maneira recomendada de vincular a APIs, porque 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 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.

Gorjeta

A extensão API Reference Link Helper para VS Code torna super fácil inserir links Xref da API do .NET em arquivos Markdown e XML.

Verifique se a API à qual você deseja vincular está publicada no Microsoft Learn digitando todo ou parte de seu nome completo no navegador da API .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.

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> é exibido como String

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

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

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 membros, o texto do link é exibido 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> resolve corretamente, mas <xref:system.object> não resolve.

Determinar o UID

Por norma, o UID é a classe totalmente qualificada ou o nome do membro. Para determinar o UID, clique com o botão direito do mouse na página Microsoft Learn de um tipo ou membro, selecione Exibir fonte e copie o valor de conteúdo para ms.assetid.

ms.assetid na origem para a página Web

Codificação em percentagem de URLs

Os caracteres especiais no UID precisam ser codificados em porcentagem da seguinte maneira:

Caráter Codificação HTML
* *

Exemplo de codificação:

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

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

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*?displayProperty=nameWithType> sem tipos específicos de parâmetros. Por exemplo:

<xref:System.Object.Equals*?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)

Gorjeta

A extensão Learn Authoring Pack para Visual Studio Code ajuda você a inserir links relativos e marcadores 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 pretender 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: pedir 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.
  • Avaliações de atualização: verifique se as informações de terceiros ainda estão atualizadas, corretas e relevantes e se o link não foi alterado.
  • Fora do local: confirme que os utilizadores estão conscientes 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 Desenvolvedor do Android, que você pode baixar no site do Android Studio."
  • Próximas etapas: Não há problema em adicionar um link para, digamos, um blog MVP em uma seção "Próximas etapas". Novamente, confirme que os utilizadores estão conscientes de que estão a sair do site.
  • Legal: Estamos cobertos legalmente em Links para Sites de Terceiros no rodapé dos Termos de Uso em cada página microsoft.com.