UD02 · Taller 5 — Documentar con Markdown¶
Entregable de la unidad
Cuenta en el 40 % de actividades del RA2, como preparación de la actividad entregable: la memoria de Robocode se escribe y documenta más rápido si dominas Markdown, y es el lenguaje en el que están escritos estos mismos apuntes.
Objetivo: aprender la sintaxis de Markdown lo bastante a fondo como para documentar cualquier proyecto — texto, listas, tablas, enlaces, imágenes y código — y escribir un documento propio de principio a fin.
Qué es y para qué sirve
Markdown es un lenguaje de marcado ligero creado en 2004 por John Gruber para convertir texto plano en HTML de forma sencilla y legible incluso sin procesar. Se usa hoy en foros (Stack Overflow), gestores de tareas (Trello), documentación técnica (GitHub, estos apuntes) y apps de notas — es transportable: el mismo .md se lee y edita en cualquier plataforma sin depender de un procesador de textos propietario. Editores habituales: Typora, VS Code (con previsualización integrada) o directamente el editor web de GitHub.
Fase 1 — Texto básico: párrafos, énfasis y encabezados¶
Un párrafo nuevo se crea con una línea en blanco entre dos bloques de texto — Markdown, como HTML, colapsa las líneas en blanco dobles en una sola. Para forzar un salto de línea dentro del mismo párrafo, termina la línea con dos espacios.
1 2 3 4 | |
Los encabezados usan # — uno por nivel, del # (H1) al ###### (H6):
1 2 3 | |
Fase 2 — Listas, tablas, enlaces e imágenes¶
Listas ordenadas (1.), no ordenadas (-, * o +, sin mezclar dentro de la misma lista) y de tareas:
1 2 3 4 5 6 7 8 | |
Tablas, con | para columnas y --- para separar el encabezado:
1 2 3 | |
Enlaces e imágenes comparten sintaxis; la imagen añade ! delante:
1 2 | |
Fase 3 — Código, citas y separadores¶
Para código en línea, una comilla invertida a cada lado: `código`. Para un bloque, tres comillas invertidas con el nombre del lenguaje:
1 2 3 | |
Las citas empiezan por >:
1 | |
En estos apuntes, las citas > no se usan para notas
Es una convención de este curso: toda nota, aviso o definición destacada va en una admonición (!!! tip, !!! note, !!! warning...), como las de esta misma página — no en una cita >. Reserva > para citar literalmente a alguien, como en el ejemplo de Lao Tsé.
Una línea horizontal de separación se crea con tres guiones en su propia línea: ---.
Diagramas: flow/sequence frente a Mermaid
Algunos editores de Markdown (Typora entre ellos) admiten bloques ```flow o ```sequence para diagramas de flujo y de secuencia con su propia sintaxis. El sitio de esta asignatura no los renderiza: usa Mermaid (```mermaid), que sí verás en la teoría de cada unidad. Si trabajas en Typora para tus propios apuntes puedes usar cualquiera de los dos; para lo que entregues en este curso, usa Mermaid.
Fase 4 — Practica: documento sobre ti mismo¶
Con tu editor favorito, crea un documento Markdown que:
- Tenga un título y, si tu editor lo soporta, un índice (
[TOC]). - Incluya 4 encabezados principales — por ejemplo Datos, Currículum, Aficiones y Otros datos de interés (no hace falta que sea información real; puedes inventarla).
- Use al menos: negrita, cursiva, una lista ordenada, una lista no ordenada, un enlace, una imagen, una cita y un bloque de código.
- Opcional, para nota extra: un diagrama Mermaid con los pasos de una mañana de sábado.
Exporta el resultado a PDF (la mayoría de editores Markdown lo hacen con un clic, o usa pandoc documento.md -o documento.pdf).
Entrega del Taller 5¶
| Fase | Evidencia mínima |
|---|---|
| 1-3 | El documento .md usa correctamente encabezados, énfasis, listas, tabla, enlace, imagen, cita y bloque de código |
| 4 | El documento tiene 4 encabezados principales con contenido propio |
| Extra | Diagrama Mermaid incluido (no obligatorio) |
Sube a Moodle el documento .md original y su exportación a .pdf.
Soluciones
No aplica: es un documento de creación libre, se comenta en clase con ejemplos del alumnado.