UTILIDADES Y HERRAMIENTAS

Markdown: sintaxis básica

Una ficha de consulta rápida con la sintaxis Markdown más utilizada para README, documentación técnica y contenido estructurado.

FUNDAMENTOS

Qué es Markdown

Markdown es una sintaxis de marcado ligero que permite estructurar documentos utilizando texto plano y unos pocos caracteres especiales.

Se utiliza habitualmente en archivos README, documentación de proyectos, repositorios de código, notas técnicas y plataformas de publicación. 

# Mi proyecto

Descripción breve del proyecto.

## Instalación

1. Descarga el proyecto.
2. Instala las dependencias.
3. Ejecuta la aplicación.

Una de sus principales ventajas es que el documento sigue siendo legible como texto plano incluso antes de ser procesado.

ESTRUCTURA

Encabezados

Los encabezados se crean colocando almohadillas al principio de una línea. El número de almohadillas determina el nivel del encabezado. 

# Título principal
## Sección
### Subsección
#### Nivel 4
##### Nivel 5
###### Nivel 6

Los niveles deben representar la jerarquía real del documento. No conviene elegirlos únicamente por el tamaño visual que produce cada plataforma.

TEXTO

Párrafos y saltos

Los párrafos se escriben como texto normal y se separan habitualmente mediante una línea en blanco. 

Este es el primer párrafo.

Este es el segundo párrafo.

Separar correctamente los bloques ayuda a que el documento sea legible tanto en el archivo Markdown como después de procesarlo.

FORMATO

Negrita y cursiva

Los asteriscos permiten aplicar énfasis a fragmentos de texto. 

*texto en cursiva*

**texto en negrita**

***negrita y cursiva***

También existen formas equivalentes basadas en guiones bajos. Mantener una misma convención en todo el documento facilita la lectura del código fuente.

LISTAS

Listas no ordenadas

Los guiones pueden utilizarse para crear listas cuyos elementos no necesitan seguir un orden determinado. 

- Linux
- Windows
- macOS

También pueden anidarse elementos utilizando indentación. 

- Desarrollo
  - Python
  - JavaScript
- Sistemas
  - Linux
  - Windows

Conviene mantener una indentación consistente para evitar interpretaciones diferentes entre procesadores.

LISTAS

Listas ordenadas

Cuando el orden de los elementos es relevante pueden utilizarse números seguidos de un punto. 

1. Descargar el proyecto
2. Instalar las dependencias
3. Configurar la aplicación
4. Ejecutar el proyecto

Este tipo de lista resulta especialmente útil para procedimientos, instrucciones y secuencias de pasos.

ENLACES

Enlaces

Un enlace combina un texto descriptivo entre corchetes con la dirección de destino entre paréntesis. 

[CommonMark](https://commonmark.org/)

Es preferible utilizar textos de enlace que indiquen claramente el contenido o destino en lugar de expresiones genéricas.

IMÁGENES

Imágenes

La sintaxis para insertar una imagen es similar a la de los enlaces, pero comienza con un signo de exclamación. 

![Texto alternativo](imagen.png)

También puede utilizarse una ruta relativa dentro del proyecto. 

![Diagrama de arquitectura](docs/arquitectura.png)

El texto alternativo debe describir de forma útil el contenido o la función de la imagen.

CITAS

Citas en bloque

El carácter > al principio de una línea permite representar una cita. 

> La documentación también forma parte del proyecto.

Una cita puede contener varias líneas o párrafos. 

> Primera parte de la cita.
>
> Segundo párrafo de la cita.

CÓDIGO

Código en línea

Las comillas invertidas permiten diferenciar comandos, nombres de archivos, variables o pequeños fragmentos de código dentro de un párrafo. 

Ejecuta `git status` para comprobar el estado del repositorio.

En el documento procesado, git status aparecerá diferenciado del resto del texto.

CÓDIGO

Bloques de código

Los bloques delimitados permiten representar código o comandos de varias líneas sin que Markdown interprete su contenido como texto normal. 

```text
git status
git add .
git commit -m "Actualizar documentación"
```

Muchas implementaciones permiten indicar el lenguaje después de las comillas iniciales para aplicar resaltado de sintaxis. 

```python
def saludar(nombre):
    return f"Hola, {nombre}"
```

El resaltado depende de la plataforma que procese el documento.

ESTRUCTURA

Separadores temáticos

Una secuencia de guiones puede utilizarse para representar una separación temática entre partes de un documento. 

---

Los separadores son útiles para marcar transiciones, aunque no deben sustituir una jerarquía adecuada de encabezados.

SINTAXIS

Mostrar caracteres especiales

Algunos caracteres tienen significado especial en Markdown. Cuando sea necesario mostrarlos literalmente puede utilizarse una barra invertida. 

\*Este texto muestra los asteriscos\*

El comportamiento depende del carácter y del contexto en el que aparece.

EXTENSIONES

Tablas

Muchas plataformas incorporan una extensión para representar tablas mediante barras verticales y una fila de separación. 

| Archivo | Formato |
| --- | --- |
| README.md | Markdown |
| config.json | JSON |
| index.html | HTML |

Las tablas no forman parte de la sintaxis básica de CommonMark. Su disponibilidad depende de la implementación utilizada.

EXTENSIONES

Listas de tareas

Algunas plataformas permiten representar tareas pendientes y completadas mediante una extensión de las listas. 

- [x] Crear estructura
- [x] Revisar documentación
- [ ] Publicar cambios

Esta sintaxis es habitual en plataformas de desarrollo, pero no debe asumirse que todos los procesadores Markdown la interpretan.

DOCUMENTACIÓN

Markdown en un README

Un README suele utilizar Markdown para explicar qué hace un proyecto, qué necesita y cómo puede utilizarse. 

# Mi proyecto

Aplicación de ejemplo.

## Requisitos

- Git
- Python 3

## Instalación

Clona el repositorio e instala las dependencias.

## Uso

Ejecuta la aplicación con:

`python app.py`

## Documentación

Consulta la documentación del proyecto.

No existe una estructura obligatoria para todos los README. Las secciones deben responder a las necesidades reales del proyecto y de las personas que van a utilizarlo.

EJEMPLO

Ejemplo de documento

Un documento sencillo puede combinar encabezados, texto, listas, enlaces y código. 

# Guía de instalación

Esta guía explica cómo preparar el proyecto.

## Requisitos

- Git
- Python 3
- pip

## Instalación

1. Clona el repositorio.
2. Accede al directorio.
3. Instala las dependencias.

Ejecuta:

`pip install -r requirements.txt`

## Más información

Consulta la [documentación](https://example.com/docs).

La sintaxis permanece suficientemente clara incluso antes de que una herramienta la convierta a HTML u otro formato.

ERRORES FRECUENTES

Qué conviene evitar

  • Utilizar encabezados únicamente por su tamaño visual en lugar de respetar la jerarquía del documento.
  • Mezclar estilos de formato sin una convención coherente.
  • Utilizar una indentación inconsistente en listas anidadas.
  • Abrir un bloque de código y olvidar el delimitador de cierre.
  • Utilizar extensiones como tablas o listas de tareas sin comprobar que la plataforma de destino las admite.
  • Escribir enlaces o rutas de imágenes sin comprobar el destino.
  • Utilizar HTML innecesariamente cuando la sintaxis Markdown ya permite representar el contenido.
  • Pensar únicamente en el resultado renderizado y descuidar la legibilidad del propio archivo Markdown.

RESUMEN

Referencia rápida

# Título                Encabezado principal
## Sección              Encabezado de segundo nivel
*texto*                 Cursiva
**texto**               Negrita
- elemento              Lista no ordenada
1. elemento             Lista ordenada
[texto](URL)            Enlace
![alt](imagen.png)      Imagen
> texto                 Cita
`código`                Código en línea
---                     Separador temático

Esta lista resume las construcciones más habituales. Las extensiones adicionales deben comprobarse en la documentación de la plataforma utilizada.

CRITERIO PROFESIONAL

Buenas prácticas

  • Mantén una jerarquía coherente de encabezados.
  • Separa los párrafos y bloques para facilitar la lectura del archivo original.
  • Utiliza textos descriptivos en enlaces e imágenes.
  • Usa código en línea para elementos breves y bloques para ejemplos de varias líneas.
  • Mantén una indentación consistente en las listas.
  • Comprueba qué extensiones admite la plataforma de destino.
  • Evita sintaxis innecesariamente compleja cuando una construcción sencilla expresa correctamente el contenido.

Un buen documento Markdown debe resultar claro tanto en su versión procesada como al abrir directamente el archivo de texto.

SIGUE CONSULTANDO

Recursos relacionados

PARA AMPLIAR

Documentación de referencia

Documentación primaria y referencias reconocidas para ampliar esta ficha y consultar la sintaxis con mayor detalle.