Compartir a través de

Uso de vínculos en la documentación

  • Artículo

En este artículo se describe cómo se usan los 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 mediante el motor de análisis 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 ser seguros (https vs http) siempre que el destino lo admita.

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: 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 archivo .yml y .md, donde el archivo .yml contiene metadatos y .md contiene el contenido. En ese caso, vincule al archivo .yml:

    [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 dirección 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 documentación:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Otro conjunto de documentación:
    • 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 título 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 Markdown de Learn también tiene herramientas que facilitan la creación de 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 facilitan la personalización del texto del vínculo. Además, se validan en tiempo de compilación y, si la dirección URL a la referencia de API cambiara, el vínculo seguiría funcionando. 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

La extensión del asistente de vínculo de referencia de API para VS Code facilita la inserción de vínculos Xref de API de .NET en archivos Markdown y XML.

Para comprobar si la API a la que quiere crear el vínculo está publicada en Microsoft Learn, escriba parte o todo el nombre completo en el Explorador de API de .NET o en el cuadro de búsqueda de Windows UWP. Si no se muestra ningún resultado, el tipo todavía no está en Microsoft Learn.

Puede usar una de las sintaxis siguientes:

  • Vínculos automáticos:

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

    De manera predeterminada, el texto de vínculo solo muestra el nombre de miembro o de 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.

Determinación del UID

Normalmente, el UID equivale al nombre de clase o miembro completo. Para determinar el UID, haga clic con el botón derecho en la página Microsoft Learn de un tipo o miembro, seleccione Ver código fuente y, después, copie el valor content de ms.assetid.

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

Codificación de porcentaje de las direcciones URL

Los caracteres especiales del UID se deben codificar por porcentaje de esta forma:

Carácter Codificación HTML
* *

Ejemplo de codificación:

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

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

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*?displayProperty=nameWithType> sin tipos de parámetros específicos. Por ejemplo:

<xref:System.Object.Equals*?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 Paquete de creación de Learn para Visual Studio Code facilita la inserción correcta de vínculos relativos y marcadores sin la tediosa tarea de tener que determinar 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: solicitar 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 actualizaciones: asegúrese de que la información de terceros está 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 comprenden las herramientas para desarrolladores 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.
  • 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.