Uso de vínculos en la documentación

  • Artículo

En este artículo se describe cómo usar hipervínculos de páginas hospedadas en Microsoft Learn. Es fácil agregar vínculos en Markdown con una serie de convenciones. Los vínculos señalan contenido de la misma página, de páginas vecinas o de sitios o direcciones URL externos.

El back-end de Microsoft Learn usa Open Publishing Services (OPS), que admite markdown compatible con CommonMark analizado a través del motor de análisis de Markdig . Este tipo de Markdown es compatible principalmente con GitHub Flavored Markdown (GFM), ya que la mayoría de los documentos se almacenan en GitHub y se pueden editar ahí. Se agrega funcionalidad adicional mediante extensiones de Markdown.

Importante

Todos los vínculos deben estar protegidos (https frente a http) siempre que el destino lo admita (lo que la inmensa mayoría debería hacer).

Texto del vínculo

Las palabras que incluya en el texto del vínculo deben ser descriptivas. Es decir, deben ser palabras normales en español o el título de la página a la que remite el vínculo.

Importante

No use "haga clic aquí" como texto de vínculo. No se trata de un texto conveniente para la optimización del motor de búsqueda ni describe correctamente el destino.

Correcto:

  • 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.

Incorrecto:

  • 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).

Vínculos de un artículo a otro

El sistema de publicación admite dos tipos de hipervínculos: direcciones URL y vínculos de archivos.

Un vínculo de dirección URL puede ser una ruta de acceso de URL relativa a la raíz de https://learn.microsoft.com, o bien una dirección URL absoluta que incluye la sintaxis de URL completa (por ejemplo, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Use vínculos de URL al vincular a contenido externo al conjunto de documentación actual o entre artículos de referencia generados automáticamente y conceptuales dentro del conjunto de documentación.
  • La forma más sencilla de crear un vínculo relativo consiste en copiar la dirección URL desde el explorador y, después, quitar https://learn.microsoft.com/en-us del valor que pegue en Markdown.
  • No incluya configuraciones regionales en las direcciones URL de las propiedades de Microsoft (por ejemplo, /en-us de la dirección URL).

Un vínculo de archivo se usa para vincular de un artículo a otro dentro del conjunto de documentación.

  • En todas las rutas de acceso de archivo se usan caracteres de barra diagonal (/) en lugar de caracteres de barra diagonal inversa.

  • Un artículo se vincula a otro en el mismo directorio:

    [link text](article-name.md)

  • Un artículo se vincula a otro en el directorio principal del directorio actual:

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

  • Un artículo se vincula a otro en un subdirectorio del directorio actual:

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

  • Un artículo se vincula a otro en un subdirectorio del directorio principal del directorio actual:

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

  • Algunos artículos constan de un .yml archivo y .md , donde el .yml archivo contiene metadatos y contiene .md el contenido. En ese caso, vincule al .yml archivo:

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

Nota

En ninguno de los ejemplos anteriores se usa ~/ como parte del vínculo. Para establecer un vínculo a una ruta de acceso absoluta que comienza en la raíz del repositorio, inicie el vínculo con /. El hecho de incluir ~/ produce vínculos no válidos al navegar por los repositorios de origen en GitHub. Si se inicia la ruta de acceso con /, se resolverá correctamente.

El contenido publicado en Microsoft Learn tiene la siguiente estructura de direcciones URL:

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

Ejemplos:

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

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale>: identifica el idioma del artículo (ejemplo: en-us o de-de)
  • <product-service>: el nombre del producto o servicio (ejemplo: powershell, dotnet o azure)
  • [<feature-service>]: (opcional) el nombre de la característica o subservicio del producto (ejemplo: csharp o load-balancer)
  • [<subfolder>]: (opcional) el nombre de una subcarpeta dentro de una característica
  • <topic>: el nombre del archivo de artículo para el tema (ejemplo: load-balancer-overview u overview)
  • [?view=\<view-name>]: (opcional) el nombre de la vista que usa el selector de versión para el contenido que tiene varias versiones disponibles (ejemplo: azps-3.5.0)

Sugerencia

En la mayoría de los casos, los artículos del mismo conjunto de documentación tienen el mismo fragmento de dirección URL <product-service>. Por ejemplo:

  • Mismo 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 un vínculo de marcador a un título del archivo actual, use un símbolo de almohadilla seguido de las palabras del título en minúscula. Quite los signos de puntuación del título y reemplace los espacios por guiones:

[Managed Disks](#managed-disks)

Para vincular a un título de marcador de otro artículo, use el vínculo relativo al archivo o al sitio junto a un símbolo de almohadilla, seguido de las palabras del título. Quite los signos de puntuación del título y reemplace los espacios por guiones:

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

También puede copiar el vínculo de marcador de la dirección URL. Para buscar la dirección URL, mantenga el mouse sobre la línea de encabezado en Microsoft Learn. Debería aparecer un icono de vínculo:

Icono de vínculo en el título del artículo

Haga clic en el icono de vínculo y, después, copie el texto del delimitador del marcador de la dirección URL (es decir, el elemento después de la almohadilla).

Nota

La extensión Learn Markdown también tiene herramientas para ayudar a crear vínculos.

No es necesario ni se recomienda agregar vínculos delimitadores explícitos con la etiqueta <a> de HTML, excepto en páginas centrales o de aterrizaje. En su lugar, use los marcadores generados automáticamente como se describe en vínculos de marcador. Para las páginas centrales o de aterrizaje, declare los delimitadores de esta forma:

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

o

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

Y lo siguiente para vincular al delimitador:

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

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

Nota

El texto del delimitador siempre debe estar en minúsculas y no contener espacios.

Los vínculos XRef son la manera recomendada de vincular a las API, ya que se validan en tiempo de compilación. Para vincular a páginas de referencia de API generadas automáticamente del conjunto de documentación actual o de otros, use vínculos XRef con el identificador único (UID) del tipo o miembro.

Sugerencia

Puede usar la extensión Learn Markdown para VS Code (parte del paquete de creación de Learn) para insertar vínculos XRref de .NET que aparecen en el explorador de API de .NET.

Comprueba si la API a la que quieres vincular se publica en Microsoft Learn escribiendo todo o parte de su nombre completo en el explorador de API de .NET o en el cuadro de búsqueda para UWP de Windows . Si no ve ningún resultado mostrado, el tipo aún no está en Microsoft Learn.

Puede usar una de las sintaxis siguientes:

  • Vínculos automáticos:

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

    De forma predeterminada, el texto del vínculo muestra solo el nombre de miembro o tipo. El parámetro de consulta displayProperty=nameWithType opcional genera texto de vínculo completo, es decir, espacio_de_nombres.tipo para los tipos y tipo.miembro para los miembros de tipo, incluidos los de enumeración.

  • Vínculos de estilo de Markdown:

    [link text](xref:UID)

    Use los vínculos de estilo de Markdown para XRef cuando quiera personalizar el texto del vínculo que se muestra.

Ejemplos:

  • <xref:System.String> se muestra como String

  • <xref:System.String?displayProperty=nameWithType> se muestra como System.String

  • [Clase de cadena](xref:System.String) se muestra como Clase de cadena.

El parámetro de consulta displayProperty=fullName funciona de la misma manera que displayProperty=nameWithType para las clases. Es decir, el texto del vínculo se convierte en espacio_de_nombres.nombre_de_clase. Pero, para los miembros, el texto del vínculo se muestra como espacio_de_nombres.nombre_de_clase.nombre_de_miembro, lo que puede no ser lo deseado.

Nota

Los UID distinguen mayúsculas de minúsculas. Por ejemplo, <xref:System.Object> se resuelve correctamente, pero <xref:system.object> no.

Advertencias de compilación de XRef y compilaciones incrementales

Una compilación incremental solo compila los archivos que han cambiado o se han visto afectados por un cambio. Si ve una advertencia de compilación sobre un vínculo de XREF no válido, pero el vínculo realmente es válido, puede deberse a que la compilación ha sido incremental. El archivo que genera la advertencia no ha cambiado, por lo que no se ha compilado y se han reproducido advertencias anteriores. La advertencia desaparecerá cuando el archivo cambie o se desencadene una compilación completa (puede iniciar una compilación completa en ops.microsoft.com). Este es un inconveniente para las compilaciones incrementales, porque DocFX no puede detectar una actualización de datos dentro del servicio XREF.

Determinación del UID

Normalmente, el UID equivale al nombre de clase o miembro completo. Hay al menos dos maneras de determinar el UID:

  • Haga clic con el botón derecho en la página de Microsoft Learn para un tipo o miembro, seleccione Ver origen y, a continuación, copie el valor de contenido de ms.assetid:

    ms.assetid en el código fuente de una página web

  • Use el sitio de autocompletar y anexe parte o todo el nombre del tipo a la dirección URL. Por ejemplo, si escribe https://xref.docs.microsoft.com/autocomplete?text=Writeline en la barra de direcciones del explorador, se muestran todos los tipos y métodos que contienen Writeline en el nombre, junto con su UID.

Comprobación del UID

Para probar si tiene el UID correcto, reemplace System.String en la siguiente dirección URL por el UID y, después, péguelo en la barra de direcciones de un explorador:

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

Sugerencia

El UID de la dirección URL distingue mayúsculas de minúsculas, y si va a comprobar un UID de una sobrecarga de método, no incluya espacios entre los tipos de parámetro.

Si ve algo parecido a lo siguiente, tiene el UID correcto:

[{"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"}]

Si solo ve [] en la página, tiene un UID incorrecto.

Codificación de porcentaje de las direcciones URL

Los caracteres especiales del UID se deben codificar en HTML de esta forma:

Carácter Codificación HTML
` %60
# %23
* %2A

Vea una lista completa de los códigos de porcentaje.

Ejemplos de codificación:

  • System.Threading.Tasks.Task`1 se codifica como System.Threading.Tasks.Task%601 (vea la sección sobre tipos genéricos)

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

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

Tipos genéricos

Los tipos genéricos son tipos como System.Collections.Generic.List<T>. Si busca este tipo en el Explorador de API de .NET y examina su dirección URL, verá que <T> se escribe como -1, lo que realmente representa `1:

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

Para vincular a un tipo genérico como List<T>, codifique el carácter de acento grave ` como %60, como se muestra en el ejemplo siguiente:

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

Métodos

Para vincular a un método, puede vincular a la página del método general si agrega un asterisco (*) después del nombre del método, o bien hacerlo a una sobrecarga concreta. Por ejemplo, use la página general cuando quiera vincular al método <xref:System.Object.Equals%2A?displayProperty=nameWithType> sin tipos de parámetros específicos. El carácter de asterisco se codifica como %2A. Por ejemplo:

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

Para vincular a una sobrecarga específica, agregue paréntesis después del nombre del método e incluya el nombre de tipo completo de cada parámetro. No coloque un carácter de espacio entre los nombres de tipo o el vínculo no funcionará. Por ejemplo:

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

Como los archivos de inclusión están ubicados en otro directorio, debe usar rutas de acceso relativas más largas. Para vincular un artículo desde un archivo de inclusión, use este formato:

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

Sugerencia

La extensión Learn Authoring Pack para Visual Studio Code le ayuda a insertar vínculos y marcadores relativos correctamente sin el tedium de averiguar las rutas de acceso.

Un selector es un componente de navegación que aparece en un artículo de documentación como una lista desplegable. Cuando un lector selecciona un valor en esa lista, el explorador abre el artículo seleccionado. Habitualmente, el selector contiene vínculos a artículos estrechamente relacionados; por ejemplo, un mismo tema en varios lenguajes de programación o bien una serie de artículos estrechamente relacionados.

Si tiene selectores insertados en un archivo de inclusión, use esta estructura de vínculos:

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

Puede usar vínculos con estilo de referencia para que el contenido de origen resulte más fácil de leer. Estos vínculos reemplazan la sintaxis del vínculo insertado por sintaxis simplificada que permite mover las direcciones URL largas al final del artículo. Este es un ejemplo de Daring Fireball:

Texto insertado:

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

Referencias de vínculos al final del artículo:

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

Asegúrese de incluir el espacio después de los dos puntos, antes del vínculo. Cuando inserta un vínculo a otro artículo técnico, si se olvida de incluir el espacio, el vínculo se romperá en el artículo publicado.

Para vincular a una página que no sea propiedad de Microsoft (como una página de precios, una página del Acuerdo de Nivel de Servicio o cualquier otra página que no se corresponda con un artículo de documentación), use una dirección URL absoluta, pero omita la configuración regional. El objetivo en este caso es que los vínculos funcionen en GitHub y en el sitio representado.

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

La mejor experiencia del usuario minimiza el redireccionamiento de los usuarios a otro sitio. Por tanto, base todos los vínculos a sitios de terceros, que a veces necesitamos incluir, en esta información:

  • Responsabilidad: vínculo a contenido de terceros cuando va a compartir la información del tercero. Por ejemplo, no es responsabilidad de Microsoft informar sobre cómo se usan las herramientas para desarrolladores de Android, sino que le corresponde a Google. Si resulta necesario, se puede explicar cómo usar las herramientas para desarrolladores de Android con Azure, pero Google informará sobre el procedimiento para usar sus herramientas.
  • Aprobación de PM: solicite la aprobación de Microsoft en contenido de terceros. Al insertar un vínculo a dicho contenido, es un indicativo de la confianza depositada en él y de la obligación asumida en caso de que los usuarios sigan las instrucciones.
  • Revisiones de actualización: asegúrese de que la información de terceros sigue actualizada, es correcta y pertinente, y de que el vínculo no ha cambiado.
  • Fuera del sitio: asegúrese de que los usuarios tienen constancia de que van a visitar otro sitio. Si el contexto no lo deja claro, agregue una frase aplicable. Por ejemplo: "Los requisitos previos incluyen las Herramientas de desarrollo de Android, que puede descargar en el sitio de Android Studio".
  • Pasos siguientes: es buena idea agregar un vínculo, por ejemplo, a un blog de MVP en una sección de "Pasos siguientes". Una vez más, debe asegurarse de que los usuarios saben que van a abandonar el sitio.
  • Información legal: estamos cubiertos legalmente por la sección Vínculos a sitios web de terceros de los Términos de uso, cuyo vínculo se encuentra en el pie de página de todas las páginas de microsoft.com.