Procedimientos recomendados de Markdown

En este artículo se proporcionan instrucciones específicas para usar Markdown en nuestra documentación. No es un tutorial para Markdown. Si necesita un tutorial para Markdown, consulte esta hoja de referencia rápida de Markdown.

La canalización de compilación que compila nuestra documentación usa markdig para procesar los documentos de Markdown. Markdig analiza los documentos en función de las reglas de la última especificación de CommonMark . OPS sigue la especificación CommonMark y agrega algunas extensiones para características específicas de la plataforma, como tablas y alertas.

La especificación CommonMark es más estricta sobre la construcción de algunos elementos Markdown. Preste mucha atención a los detalles proporcionados en este documento.

Usamos la extensión markdownlint en VS Code para aplicar nuestras reglas de formato y estilo. Esta extensión se instala como parte del Learn Authoring Pack.

Líneas, espacios y pestañas en blanco

Las líneas en blanco también indican el final de un bloque en Markdown.

• Coloque un solo espacio en blanco entre bloques Markdown de diferentes tipos; por ejemplo, entre un párrafo y una lista o un encabezado.
• No use más de una línea en blanco. Varias líneas en blanco se representan como una sola línea en blanco en HTML, por lo que las líneas en blanco adicionales son innecesarias.
• No use colocar varias líneas en blanco consecutivas en un bloque de código, las líneas en blanco consecutivas interrumpen el bloque de código.

El espaciado es significativo en Markdown.

• Quite espacios adicionales al final de las líneas. Los espacios finales pueden cambiar el modo en que se representa Markdown.
• Use siempre espacios en lugar de pestañas (pestañas duras).

Títulos y encabezados

Use solo encabezados ATX (estilo#, en lugar de encabezados de estilo = o -).

• No se exceda en el uso de mayúsculas (solo nombres propios y la primera letra de un título o encabezado en mayúscula)
• Incluir un solo espacio entre el # y la primera letra del encabezado.
• Coloque encabezados con una sola línea en blanco alrededor.
• No use más de un H1 por documento
  • Debe ser el primer encabezado
  • Debe coincidir con el título del artículo.
• Incrementar los niveles de encabezado en uno: no omitir los niveles
• Limitar la profundidad a H3 o H4
• Evitar el uso de negrita u otro marcado en encabezados

Limitar la longitud de línea a 100 caracteres

Para artículos conceptuales y referencia de cmdlets, limite las líneas a 100 caracteres. En about_ el caso de los artículos, limite la longitud de línea a 79 caracteres. Limitar la longitud de línea mejora la legibilidad de diferencias git e historial. También facilita a otros escritores realizar contribuciones.

Utiliza la extensión Reflow Markdown en VS Code para ajustar los párrafos a la longitud de línea especificada.

Algunos tipos de contenido no se pueden reorganizar fácilmente. Por ejemplo, el código dentro de los bloques de código también puede ser difícil de volver a distribuir, dependiendo del contenido y del lenguaje de código. No se puede volver a generar una tabla. En estos casos, use su mejor criterio para mantener el contenido lo más cerca posible del límite de 100 caracteres.

Énfasis

Para dar énfasis, Markdown admite negrita y cursiva. Markdown le permite usar * o _ para marcar el énfasis. Sin embargo, para ser coherente y mostrar la intención:

• Uso ** para negrita
• Usa _ para cursiva

Seguir este patrón facilita a otros usuarios comprender la intención del marcado cuando hay una combinación de negrita y cursiva en un documento.

Listas

Si la lista tiene varias oraciones o párrafos, considere la posibilidad de usar un encabezado de subnivel en lugar de una lista.

Rodee las listas con una sola línea en blanco.

Listas sin ordenar

• No finalice los elementos de lista con un punto a menos que contengan varias oraciones.
• Use el carácter de guion (-) para las viñetas de elemento de lista para evitar confusión con el formato de énfasis que usa el asterisco (*).
• Para incluir un párrafo u otros elementos bajo un elemento de viñeta, inserte un salto de línea y alinee la sangría con el primer carácter después de la viñeta.

Por ejemplo:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Se trata de una lista que contiene elementos secundarios bajo un elemento de viñeta.

• Primer elemento de viñeta

  Oración que explica la primera viñeta.

  • Elemento de viñeta secundario

    Oración que explica la primera subviñeta.

• Segundo elemento de viñeta

• Tercer elemento de viñeta

Listas ordenadas

• Todos los elementos de una lista numerada deben usar el número 1. en lugar de incrementar cada elemento.
  • La representación de Markdown incrementa automáticamente el valor.
  • Esto facilita la reordenación de los elementos y normaliza la sangría del contenido subordinado.
• Para incluir un párrafo u otros elementos bajo un elemento numerado, alinee la sangría con el primer carácter después del número de elemento.

Por ejemplo:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

El markdown resultante se representa de la siguiente manera:

1. Para el primer elemento, inserte un solo espacio después de 1. Las oraciones largas deben ajustarse a la línea siguiente y deben alinearse con el primer carácter después del marcador de lista numerada.

   Para incluir un segundo elemento, inserte un salto de línea después del primero y alinee las indentaciones. La sangría del segundo elemento debe alinearse con el primer carácter después del marcador de lista numerada.

2. El siguiente elemento numerado comienza aquí.

Imágenes

La sintaxis para incluir una imagen es:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Donde alt text es una breve descripción de la imagen y <folderPath> es una ruta de acceso relativa a la imagen.

• Se requiere texto alternativo para admitir lectores de pantalla para las personas con discapacidad visual.
• Las imágenes deben almacenarse en una media/<article-name> carpeta dentro de la carpeta que contiene el artículo.
  • Cree una carpeta que coincida con el nombre de archivo del artículo en la media carpeta . Copie las imágenes de ese artículo en esa nueva carpeta.
• No comparta imágenes entre artículos.
  • Si varios artículos usan una imagen, cada carpeta debe tener una copia de esa imagen.
  • Esto impide que un cambio en una imagen de un artículo afecte a otro artículo.

Se admiten los siguientes tipos de archivo de imagen: *.png, *.gif, *.jpeg, , *.jpg, *.svg

Extensión Markdown: cuadros de alerta

Learn Authoring Pack contiene herramientas que admiten características exclusivas de nuestro sistema de publicación. Las alertas son una extensión de Markdown para crear comillas de bloque que se representan con colores e iconos que resaltan la importancia del contenido. Se admiten los siguientes tipos de alertas:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Estas alertas tienen este aspecto en Microsoft Learn:

Bloque de notas

Nota:

Información que el usuario debe detectar, incluso cuando esté echando una ojeada.

Bloque de sugerencias

Sugerencia

Información opcional para ayudar a un usuario a tener más éxito.

Bloque importante

Importante

Información esencial necesaria para el éxito del usuario.

Bloque de precauciones

Precaución

Consecuencias potenciales negativas de una acción.

Bloque de advertencia

Advertencia

Consecuencias peligrosas de una acción.

Extensión Markdown: tablas

Una tabla es una disposición de los datos con filas y columnas que constan de:

• Una sola fila de encabezado
• Fila delimitador que separa el encabezado de los datos
• Cero o más filas de datos

Cada fila consta de celdas que contienen texto arbitrario separado por canalizaciones (|). También se recomienda una tubería inicial y final para mayor claridad. Los espacios entre canalizaciones y contenido de celda se recortan. Los elementos de nivel de bloque no se pueden insertar en una tabla. Todo el contenido de una fila debe estar en una sola línea.

La fila delimitador consta de celdas cuyo único contenido son guiones (-) y, opcionalmente, dos puntos iniciales o finales (:), o ambos, para indicar la alineación izquierda, derecha o central, respectivamente.

En el caso de las tablas pequeñas, considere la posibilidad de usar una lista en su lugar. Las listas son:

• Más fácil de mantener y leer
• Puede reestructurarse para ajustarse al límite de 100 caracteres.
• Más accesible para los usuarios que usan lectores de pantalla para obtener ayuda visual

Para obtener más información, consulte la sección Tablas de la referencia de Markdown para Microsoft Learn.

Hipervínculos

• Los hipervínculos deben usar la sintaxis [friendlyname](url-or-path)de Markdown .

• El sistema de publicación admite tres tipos de vínculos:

  • Vínculos de dirección URL
  • Vínculos de archivo
  • Vínculos entre referencias

• Todas las direcciones URL a sitios web externos deben usar HTTPS a menos que no sea válido para el sitio de destino.

• Los vínculos deben tener un nombre descriptivo, normalmente el título del artículo vinculado.

• Evite usar acentos graves, negrita ni otro tipo de marcado dentro de los corchetes de un hipervínculo.

• Las URLs simples pueden usarse cuando se documenta un URI específico, pero deben incluirse entre comillas invertidas. Por ejemplo:

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• Use referencias de vínculo donde se permita. Las referencias de vínculo dentro de párrafos hacen que los párrafos sean más legibles.

  Las referencias de vínculo dividen un vínculo de Markdown en dos partes:

  • referencia de vínculo: [friendlyname][id]
  • la definición del vínculo: [id]: url-or-path

Vínculos de tipo URL

• Los vínculos URL a otros artículos de learn.microsoft.com deben usar rutas de acceso relativas al sitio. La manera más sencilla de crear un vínculo relativo al sitio es copiar la dirección URL del explorador y, a continuación, 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 (quitar /en-us de la dirección URL) ni los vínculos de Wikipedia.
• Quite los parámetros de consulta innecesarios de la dirección URL. Ejemplos que se deben quitar:
  • ?view=powershell-5.1 : se usa para vincular a una versión específica de PowerShell.
  • ?redirectedfrom=MSDN : se ha agregado a la dirección URL cuando se le redirige desde un artículo antiguo a su nueva ubicación.
• Si necesita vincular a una versión específica de un documento, debe agregar el &preserve-view=true parámetro a la cadena de consulta. Por ejemplo: ?view=powershell-5.1&preserve-view=true
• En los sitios de Microsoft, los vínculos URL no contienen extensiones de archivo (por ejemplo, no .md)

Vínculos de tipo de archivo

• Un vínculo de archivo se usa para vincular desde un artículo de referencia a otro, o desde un artículo conceptual a otro en el mismo conjunto de documentos.
  • Si necesita vincular un artículo conceptual a un artículo de referencia, debe usar un vínculo URL.
  • Si necesita vincular a un artículo de otro conjunto de documentos o entre repositorios, debe usar un vínculo de dirección URL.
• Use rutas de archivo relativas (por ejemplo: ../folder/file.md)
• Todas las rutas de acceso de archivo usan caracteres de barra diagonal (/).
• Incluir la extensión de archivo (por ejemplo, .md)

Vínculos entre referencias

Los vínculos entre referencias son una característica especial compatible con el sistema de publicación. Puede usar vínculos de referencia cruzada en artículos conceptuales para vincular a la API de .NET o a la referencia de cmdlet.

• Para obtener vínculos a la referencia de la API de .NET, consulte Uso de vínculos en la documentación de la Guía central de colaboradores.

• Los vínculos a la referencia de cmdlet tienen el formato siguiente: xref:<module-name>.<cmdlet-name>. Por ejemplo, para vincular el cmdlet Get-Content en el módulo Microsoft.PowerShell.Management.

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Vinculación profunda

La vinculación profunda se permite tanto en la dirección URL como en los vínculos de archivo.

• El texto del delimitador debe estar en minúsculas.
• Agregue el delimitador al final de la ruta de acceso de destino. Por ejemplo:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Para obtener más información, consulte Uso de vínculos en la documentación.

Intervalos de código

Los intervalos de código se usan para fragmentos de código insertados dentro de un párrafo. Usa una sola comilla invertida para indicar una sección de código. Por ejemplo:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Este ejemplo se representa como:

Los nombres de cmdlet de PowerShell usan la nomenclatura de convención Verb-Noun.

Bloques de código

Los bloques de código se usan para ejemplos de comandos, ejemplos de código de varias líneas, lenguajes de consulta y salidas. Hay dos maneras de indicar que una sección de texto en un archivo de artículo es un bloque de código: encerrándolo con comillas invertidas triples (```) o por medio de sangría.

Nunca use sangría porque es demasiado fácil de equivocarse y puede ser difícil que otro escritor comprenda su intención cuando necesite editar el artículo.

Los bloques de código cercados pueden incluir una etiqueta opcional que indica la sintaxis del lenguaje contenida en el bloque. La plataforma de publicación admite una lista de etiquetas de idioma. La etiqueta de idioma se usa para proporcionar resaltado de sintaxis cuando el artículo se representa en la página web. La etiqueta de idioma no distingue mayúsculas de minúsculas, pero debe usar minúsculas excepto en algunos casos especiales.

• Las barreras de código sin etiquetas se pueden usar para bloques de sintaxis u otros tipos de contenido en los que no se requiere el resaltado de sintaxis.
• Al mostrar la salida de un comando, use un bloque de código etiquetado con el indicador de idioma Output. El cuadro renderizado está etiquetado como Salida y no tiene resaltado de sintaxis.
• Si la salida está en un idioma admitido específico, use la etiqueta de idioma adecuada. Por ejemplo, muchos comandos generan JSON, por lo que usan la json etiqueta .
• Si usa una etiqueta de idioma no compatible, el bloque de código se representará sin resaltado de sintaxis. La etiqueta de idioma se convierte en la etiqueta del cuadro de código representado en la página web. Capitalice la etiqueta para que la etiqueta esté en mayúsculas en la página web.

Pasos siguientes

guía de estilo de PowerShell