¿Qué es Markdown?
Markdown es un lenguaje de marcado que ofrece un enfoque sencillo para la edición de contenido al proteger a los creadores de contenido de la sobrecarga del HTML. Aunque HTML es ideal para representar el contenido exactamente como está previsto, ocupa una gran cantidad de espacio, y trabajar con él puede ser complicado, aun cuando sea en pequeñas dosis. Markdown ofrece un equilibrio perfecto entre la eficacia de HTML para la descripción del contenido y la facilidad de texto sin formato para editarlo.
En esta unidad, analizaremos la estructura y la sintaxis de Markdown. También se hablará de las características de GitHub-Flavored Markdown (GFM), que son extensiones de sintaxis que permiten integrar características de GitHub en el contenido.
Nota:
El propósito de esta unidad es dar una visión general de en qué consiste Markdown. Para una revisión más profunda, consulte los artículos Descripción de la sintaxis de Markdown y Especificación de Markdown con sabor a GitHub en la unidad Resumen de este módulo.
Enfatizar texto
La parte más importante de cualquier comunicación en GitHub suele ser el propio texto, pero ¿cómo se muestra que algunas partes del texto son más importantes que otras?
Usar la cursiva en el texto es tan fácil como poner el texto de destino entre asteriscos (*) o guiones bajos (_) únicos. Solo tiene que asegurarse de que cierra las marcas de énfasis con el mismo carácter que ha usado para abrirlas. Debe prestar atención en su forma de combinar el uso de asteriscos y guiones bajos. Estos son algunos ejemplos:
This is *italic* text.
This is also _italic_ text.
Esto es texto en cursiva. Esto también es texto en cursiva.
Cree texto en negrita usando dos asteriscos (**) o dos guiones bajos (__).
This is **bold** text.
This is also __bold__ text.
Esto es texto en negrita. Esto también es texto en negrita.
Se pueden usar distintos énfasis a la vez.
_This is **italic and bold** text_ using a single underscore for italic and double asterisks for bold.
__This is bold and *italic* text__ using double underscores for bold and single asterisks for italic.
Esto es texto en cursiva y negrita en el que se usa un guion bajo único para la cursiva y asteriscos dobles para la negrita. Esto es texto en cursiva en el que se usan guiones bajos dobles para la negrita y asteriscos únicos para la cursiva.
Para usar un asterisco literal, anteponga un carácter de escape; en GFM, es una barra diagonal inversa (\). Este ejemplo da como resultado que los guiones bajos y los asteriscos se muestren en la salida.
\_This is all \*\*plain\*\* text\_.
_Todo esto es texto **sin formato**_.
Declarar encabezados
HTML proporciona encabezados de contenido, como la etiqueta <h1>. En Markdown, esto se realiza a través del símbolo de almohadilla (#). Use una sola almohadilla por cada nivel de encabezado del 1 al 6.
###### This is H6 text
Este texto pertenece al nivel de encabezado 6.
Vínculo a imágenes y sitios
Los vínculos a sitios e imágenes usan una sintaxis parecida.
[Link to Microsoft Training](/training)
Crear listas
Se pueden definir listas ordenadas o sin ordenar. También se puede usar la sangría para definir elementos anidados.
- Las listas ordenadas comienzan con números.
- Las listas no desordenadas pueden usar asteriscos o guiones (
-).
Este es el Markdown de una lista ordenada:
1. First
1. Second
1. Third
Resultado:
- Primero
- Segundo
- Tercero
Este es el Markdown de una lista desordenada:
- First
- Nested
- Second
- Third
- Primeros
- Anidado
- Segundo
- Tercero
Compilación de tablas
Las tablas se pueden construir mediante una combinación de canalizaciones (|) para saltos de columna y guiones (-) para designar la fila anterior como encabezado.
First|Second
-|-
1|2
3|4
Primero Segundo 1 2 3 4
Poner texto entre comillas
Puede crear citas en bloque con el carácter "mayor que" (>).
> This is quoted text.
Esto es texto entrecomillado.
Rellenar los huecos con HTML en línea
Si encuentra un escenario HTML que no es compatible con Markdown, puede utilizar ese HTML en línea.
Here is a<br />line break
Esto es
un salto de línea.
Trabajo con código
Markdown proporciona un comportamiento predeterminado para trabajar con bloques de código en línea delimitados con el carácter de tilde aguda (`). Al decorar texto con este carácter, se representa como código.
This is `code`.
Esto es
code.
Si tiene un segmento de código que ocupa varias líneas, se pueden usar tres tildes agudas (```) antes y después para crear un bloque de código con barrera.
```markdown
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
Markdown de tipo GitHub amplía esta compatibilidad con el resaltado de sintaxis en los lenguajes más conocidos. Basta con especificar el lenguaje como parte de la primera secuencia de tildes.
```javascript
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
Problemas de vínculos cruzados y solicitudes de extracción
GFM admite varios formatos de códigos cortos para facilitar la vinculación a problemas y solicitudes de extracción. La forma más fácil de hacerlo es usar el formato #ID, como #3602. GitHub ajusta automáticamente los vínculos más largos a este formato si lo pega. También se pueden seguir más convenciones, por ejemplo, si estamos trabajando con otras herramientas o queremos especificar otros proyectos o ramas.
| Tipo de referencia | Referencia sin formato | Vínculo corto |
|---|---|---|
| Dirección URL de la solicitud de incorporación de cambios o el problema | https://github.com/desktop/desktop/pull/3602 |
#3602 |
# y número de la solicitud de incorporación de cambios o el problema |
#3602 | #3602 |
GH- y número de la solicitud de incorporación de cambios o el problema |
GH-3602 | GH-3602 |
Username/Repository# y número de la solicitud de incorporación de cambios o el problema |
desktop/desktop#3602 | desktop/desktop#3602 |
Para obtener más información, consulte el artículo URL y referencias vinculadas automáticamente en la unidad Resumen de este módulo.
Vincular confirmaciones específicas
Puede vincular a una confirmación pegando su id. o simplemente usando su algoritmo hash seguro (SHA).
| Tipo de referencia | Referencia sin formato | Vínculo corto |
|---|---|---|
| Dirección URL de confirmación | https://github.com/desktop/desktop/commit/ | |
| 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c | |
| SHA | 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c |
| User@SHA | desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop@8304e9c |
| Username/Repository@SHA | desktop/desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop/desktop@8304e9c |
Mencionar usuarios y equipos
Al escribir un símbolo @ seguido de un nombre de usuario de GitHub, se envía una notificación a esa persona sobre el comentario. Esto se denomina "@mention", ya que se está mencionando al individuo. @mention también se puede usar para mencionar a los equipos de una organización.
@githubteacher
Seguir listas de tareas
Puede crear listas de tareas dentro de problemas o solicitudes de incorporación de cambios, para lo cual usará la sintaxis siguiente. Esto puede ser útil para llevar un seguimiento del progreso cuando se usa en el cuerpo de un problema o una solicitud de incorporación de cambios.
- [x] First task
- [x] Second task
- [ ] Third task
Comandos de barra diagonal
Con los comandos de barra diagonal puedes ahorrar tiempo, ya que se reduce la cantidad de escritura necesaria para crear código Markdown complejo.
Los comandos de barra diagonal se pueden usar en cualquier campo de descripción o comentario en problemas, solicitudes de incorporación de cambios o discusiones donde este tipo de comando se pueda usar.
| Comando | Descripción |
|---|---|
/code |
Inserta un bloque de código Markdown. Tú eliges el lenguaje. |
/details |
Inserta un área de detalles contraíble. Tú eliges el título y el contenido. |
/saved-replies |
Inserta una respuesta guardada. Tú eliges una de las respuestas guardadas para tu cuenta de usuario. Si agrega %cursor% a su respuesta guardada, el comando de barra diagonal coloca el cursor en esa ubicación. |
/table |
Inserta una tabla de Markdown. Tú eliges el número de columnas y filas. |
/tasklist |
Inserta una lista de tareas. Este comando de barra diagonal sólo funciona en las descripciones de problemas. |
/template |
Muestra todas las plantillas del repositorio. Tú eliges la plantilla que se va a insertar. Este comando de barra diagonal funciona para plantillas de incidencias y una plantilla de solicitud de extracción. |