Compartir a través de

Plantilla de Markdown y metadatos para documentos de .NET

Esta plantilla 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 nuevo archivo, rellene los metadatos como se especifica a continuación y establezca el encabezado H1 anterior en el título del artículo.

Metadatos

El bloque de metadatos necesario se encuentra 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 tener un espacio entre los dos puntos (:) y el valor de un elemento de metadatos.
  • Los dos puntos en un valor (por ejemplo, un título) rompen el analizador de metadatos. En este caso, rodea el título con comillas dobles (por ejemplo, title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • title: aparece en los resultados del motor de búsqueda. El título no debe ser idéntico al título del encabezado H1 y debe contener 60 caracteres o menos.
  • description: resume el contenido del artículo. Normalmente se muestra en la página de resultados de búsqueda, pero no se usa para la clasificación de búsqueda. Su longitud debe tener entre 115 y 145 caracteres, incluidos los espacios.
  • author: el campo author debe contener el nombre de usuario de GitHub del autor.
  • ms.date: fecha de la última actualización significativa. Actualícelo en los artículos existentes si ha revisado y actualizado todo el artículo. Las correcciones pequeñas, como errores tipográficos o similares, no garantizan una actualización.

Otros metadatos se adjuntan a cada artículo, pero normalmente se aplican la mayoría de los valores de metadatos en el nivel de carpeta, especificados en docfx.json.

Markdown básico, GFM y caracteres especiales

Puede aprender los conceptos básicos de Markdown, GitHub Flavored Markdown (GFM) y extensiones específicas de OPS en el artículo de referencia de Markdown.

Markdown usa caracteres especiales como *, 'y # para dar formato. Si desea incluir uno de estos caracteres en el contenido, debe hacer una de estas dos cosas:

  • Coloque una barra diagonal inversa antes del carácter especial para "escapar" (por ejemplo, \* para un *).
  • Use el código de entidad HTML para el carácter (por ejemplo, * para un *).

Nombres de archivo

Los nombres de archivo usan las siguientes reglas:

  • Contener solo letras minúsculas, números y guiones.
  • Sin espacios ni caracteres de puntuación. Use los guiones para separar palabras y números en el nombre de archivo.
  • Use verbos de acción específicos, como desarrollar, comprar, compilar, solucionar problemas. Sin palabras con la terminación "-ing".
  • No use palabras pequeñas: no incluya a, y, el, en, o, etc.
  • Debe estar en Markdown y usar la extensión de archivo .md.
  • Mantenga los nombres de archivo razonablemente cortos. Forman parte de la dirección URL de los artículos.

Headings

Use mayúsculas de estilo de frase. Siempre escribe con mayúscula la primera palabra de un encabezado.

Aplicar estilos a texto

Italics
Usar para archivos, carpetas, rutas de acceso (para elementos largos, colóquelos en líneas separadas), términos nuevos.

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

Code
Use para código insertado, palabras clave de lenguaje, nombres de paquetes NuGet, comandos de línea de comandos, nombres de tabla de base de datos y columnas, y direcciones URL en las que no desea que se pueda hacer clic.

Consulte el artículo general sobre vínculos para obtener información sobre anclajes, vínculos internos, vínculos a otros documentos, códigos incluidos y vínculos externos.

El equipo de documentos 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 vínculos porque los vínculos relativos se resuelven en el origen en GitHub. Sin embargo, siempre que vinculemos a un archivo de un repositorio dependiente, usamos el ~/ carácter para proporcionar la ruta de acceso. Dado que los archivos del repositorio dependiente se encuentran en una ubicación diferente en GitHub, los vínculos no se resolverán correctamente con vínculos relativos independientemente de cómo se hayan escrito.
  • La especificación del lenguaje C# y la especificación del lenguaje Visual Basic se incluyen en los documentos de .NET mediante la inclusión del origen de los repositorios de lenguaje. Las fuentes 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 y para VB, es ~/_vblang/spec, como en el ejemplo siguiente:

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

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

  1. Vínculo automático: <xref:UID> o <xref:UID?displayProperty=nameWithType>

    El displayProperty parámetro de consulta genera un texto de enlace totalmente calificado. De forma predeterminada, el texto del vínculo muestra solo el nombre del miembro o del tipo.

  2. Vínculo de Markdown: [link text](xref:UID)

    Use cuando desee 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 clase String

Para obtener más información sobre el uso de esta notación, vea Uso de referencia cruzada.

Algunos UID contienen los caracteres especiales ', # o *, el valor UID debe estar codificado en HTML como %60, %23 y %2A respectivamente. A veces se verán paréntesis codificados, pero no es necesario.

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

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

Para vincular a una sobrecarga de método específica, debe incluir el nombre de tipo completo de cada uno de 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)> se vincula al método DateTime.ToString(String,IFormatProvider).

Para vincular a un tipo genérico, como System.Collections.Generic.List<T>, use 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 manera de incluir código es incluir fragmentos de código de un ejemplo de trabajo. Cree el ejemplo siguiendo las instrucciones del artículo de contribución a .NET . Incluir fragmentos de código de programas completos garantiza que todo el código se ejecute a través de nuestro sistema de integración continua (CI). Sin embargo, si necesita mostrar algo que causa errores en tiempo de compilación o tiempo de ejecución, puede usar bloques de código insertados.

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 <iframe> elemento .

> [!VIDEO <youtube_video_link>]

Por ejemplo:

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

extensiones de learn.microsoft

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

Listas marcadas

Hay un estilo personalizado disponible para 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:

  • Creación de una aplicación de .NET Core
  • Cómo agregar una referencia al paquete Microsoft.XmlSerializer.Generator
  • Cómo editar myApp.csproj para agregar dependencias
  • Cómo agregar una clase y un XmlSerializer
  • Compilación y ejecución de la aplicación

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

Buttons

Enlaces de botones

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

Esto se representa como:

vínculos de botón

Puede ver un ejemplo de botones en acción en los documentos de Visual Studio.

Pasos a paso

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

Puede ver un ejemplo de paso a paso en acción en la Guía de C#.

  • Last updated on