Metadatos y plantilla de Markdown para la documentación de .NET

Artículo
08/10/2023

Esta plantilla de dotnet/docs contiene ejemplos de sintaxis de Markdown e instrucciones sobre cómo establecer los metadatos.

Al crear un archivo Markdown, copie la plantilla incluida en un archivo nuevo, completar los metadatos como se especifica a continuación y establecer el encabezado H1 anterior en el título del artículo.

Metadatos

El bloque de metadatos necesario está en el siguiente bloque de metadatos de ejemplo:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

Debe haber un espacio entre los dos puntos (:) y el valor de un elemento de metadatos.
En un valor (por ejemplo en un título) los dos puntos interrumpen al analizador de metadatos. En este caso, incluya el título entre comillas dobles (por ejemplo, title: "Writing .NET Core console apps: An advanced step-by-step guide").
Título: aparece en los resultados de los motores de búsqueda. El título no debe ser idéntico al del encabezado H1, y debe contener 60 caracteres o menos.
Descripción: resume el contenido del artículo. Se suele mostrar en la página de resultados de la búsqueda, pero no se usa para la clasificación de la búsqueda. La longitud debe ser de 115-145 caracteres (espacios incluidos).
Autor: el campo del autor debe contener el nombre de usuario de GitHub del autor.
ms.date: se trata de la fecha de la última actualización importante. Actualice este valor en los artículos existentes si ha revisado y actualizado el artículo completo. Las correcciones menores, como los errores tipográficos y similares, no merecen una actualización.

A los artículos se anexan otros metadatos, pero por lo general la mayoría se aplican en el nivel de carpeta, y se especifican en docfx.json.

Markdown básico, GFM y caracteres especiales

Puede obtener información sobre los conceptos básicos de Markdown, GitHub Flavored Markdown (GFM) y extensiones específicas de OPS en el artículo Referencia de Markdown.

En Markdown se usan caracteres especiales como *, ` y # para el formato. Si quiere incluir uno de estos caracteres en el contenido, debe realizar una de estas dos cosas:

Colocar una barra diagonal inversa delante del carácter especial para aplicarle el "escape" (por ejemplo, \* para *).
Usar el código de entidad HTML para el carácter (por ejemplo, * para *).

Nombres de archivo

En los nombres de archivo se usan las reglas siguientes:

Solo pueden contener letras minúsculas, números y guiones.
No pueden contener espacios ni caracteres de puntuación. Use guiones para separar palabras y números en el nombre de archivo.
Use verbos de acción que sean específicos, como "desarrollar", "comprar", "compilar" o "solucionar problemas". No use gerundios.
No use palabras cortas ni incluya "un", "y", "el", "en", "o", etc.
Deben estar en Markdown y usar la extensión de archivo .md.
Use nombres de archivo relativamente cortos. Forman parte de la dirección URL de los artículos.

Encabezados

Use mayúsculas de estilo de frase. Siempre debe poner en mayúscula la primera palabra de un título.

Estilo de texto

Cursiva
Se usa para archivos, carpetas, rutas de acceso (para elementos largos, divididos en su propia línea), términos nuevos.

Negrita
Se usa para los elementos de la interfaz de usuario.

Code
Se usa para código insertado, palabras clave del lenguaje, nombres de paquetes NuGet, comandos de la línea de comandos, nombres de tablas y columnas de bases de datos y direcciones URL en las que no quiera que se pueda hacer clic.

Vínculos

Vea el artículo general sobre Vínculos para obtener información sobre delimitadores, vínculos internos, vínculos a otros documentos, archivos de inclusión de código y vínculos externos.

El equipo de documentación de .NET usa las convenciones siguientes:

En la mayoría de los casos, se usan los vínculos relativos y se desaconseja el uso de ~/ en los vínculos, ya que los vínculos relativos se resuelven en el origen en GitHub. Pero siempre que se vincula a un archivo en un repositorio dependiente, se usará el carácter ~/ para proporcionar la ruta de acceso. Como los archivos del repositorio dependiente están en otra ubicación de GitHub, los vínculos no se resolverán de forma correcta con vínculos relativos con independencia de cómo se hayan escrito.
La especificación de los lenguajes C# y Visual Basic se incluye en la documentación de .NET mediante la inclusión del origen de los repositorios de lenguaje. Los orígenes de Markdown se administran en los repositorios csharplang y vblang.

Los vínculos a la especificación deben apuntar a los directorios de origen en los que se incluyen esas especificaciones. Para C#, es ~/_csharplang/spec and for VB, it's ~/_vblang/spec, como en el ejemplo siguiente:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Vínculos a las API

El sistema de compilación tiene algunas extensiones que nos permiten vincular a las API de .NET sin tener que usar vínculos externos. Se usa una de las sintaxis siguientes:

Vinculación automática: <xref:UID> o <xref:UID?displayProperty=nameWithType>

El parámetro de consulta displayProperty produce un texto de vínculo completo. De forma predeterminada, el texto del vínculo muestra solo el nombre de miembro o tipo.
Vínculo de Markdown: [link text](xref:UID)

Se utiliza cuando se desea personalizar el texto del vínculo mostrado.

Ejemplos:

<xref:System.String> se representa como String
<xref:System.String?displayProperty=nameWithType> se representa como System.String
[String class](xref:System.String) se representa como String class

Para obtener más información acerca de cómo utilizar esta notación, consulte Using cross reference (Uso de referencia cruzada).

Cuando algunos UID contienen los caracteres especiales `, # o *, el valor de UID se debe codificar en HTML como %60, %23 y %2A, respectivamente. En ocasiones verá paréntesis codificados, pero no es un requisito.

Ejemplos:

System.Threading.Tasks.Task`1 se convierte en System.Threading.Tasks.Task%601
System.Exception.#ctor se convierte en System.Exception.%23ctor
System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) se convierte en System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Puede encontrar los UID de tipos, una lista de sobrecargas de miembros, o bien un miembro de sobrecarga concreto, en https://xref.learn.microsoft.com/autocomplete. La cadena de consulta ?text=*\<type-member-name>* identifica el tipo o miembro cuyos UID quiere ver. Por ejemplo, https://xref.learn.microsoft.com/autocomplete?text=string.format recupera las sobrecargas de String.Format. La herramienta busca el parámetro de consulta text proporcionado en cualquier parte del UID. Por ejemplo, puede buscar por nombre de miembro (ToString), nombre de miembro parcial (ToStri), nombre de miembro y tipo (Double.ToString), etc.

Si agrega * (o %2A) después del UID, el vínculo representará la página de sobrecarga y no una API específica. Por ejemplo, puede usarlo si quiere vincular a la página List<T>.BinarySearch Method de forma genérica en lugar de a una sobrecarga específica como List<T>.BinarySearch(T, IComparer<T>). También puede usar * para vincular a la página de un miembro cuando el miembro no está sobrecargado; esto evita tener que incluir la lista de parámetros en el UID.

Para vincular a una sobrecarga de método concreta, debe incluir el nombre de tipo completo de todos los parámetros del método. Por ejemplo, <xref:System.DateTime.ToString> vincula al método DateTime.ToString sin parámetros, mientras que <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> vincula al método DateTime.ToString(String,IFormatProvider).

Para vincular a un tipo genérico, como System.Collections.Generic.List<T>, se usa el carácter ` (%60) seguido del número de parámetros de tipo genérico. Por ejemplo, <xref:System.Nullable%601> vincula al tipo System.Nullable<T>, mientras que <xref:System.Func%602> vincula al delegado System.Func<T,TResult>.

Código

La mejor forma de incluir código consiste en incluir fragmentos de código de un ejemplo que funcione. Para crear el ejemplo, siga las instrucciones del artículo Contribuciones a .NET. La inclusión de fragmentos de código desde programas completos garantiza que todo el código se ejecuta a través de nuestro sistema de Integración continua (CI). Pero si tiene que mostrar algo que produce errores en tiempo de compilación o ejecución, puede usar bloques de código insertado.

Para obtener información sobre la sintaxis de Markdown para mostrar código en documentos, consulte Inclusión de código en documentos.

Imágenes

Imagen estática o GIF animado

![this is the alt text](../images/Logo_DotNet.png)

Imagen vinculada

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Vídeos

Puede insertar vídeos de YouTube en un archivo Markdown. Para obtener la dirección URL correcta del vídeo, haga clic con el botón derecho en el vídeo, seleccione Copiar código para insertar, y copie la dirección URL del elemento <iframe>.

> [!VIDEO <youtube_video_link>]

Por ejemplo:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

extensiones learn.microsoft

learn.microsoft proporciona algunas extensiones adicionales para GitHub Flavored Markdown.

Listas de comprobación probadas

Hay disponible un estilo personalizado para las listas. Puede representar listas con marcas de verificación verdes.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Esto se representa como:

Cómo crear una aplicación .NET Core
Cómo agregar una referencia al paquete Microsoft.XmlSerializer.Generator
Cómo editar el archivo MyApp.csproj para agregar dependencias
Cómo agregar una clase y un XmlSerializer
Cómo compilar y ejecutar la aplicación

Puede ver un ejemplo de listas de comprobación en acción en la documentación de .NET Core.

Botones

Vínculos de botón:

> [!div class="button"]
> [button links](dotnet-contribute.md)