Escribir y verificar un README de GitHub con vista previa Markdown
El archivo README.md es la primera impresión de cualquier repositorio de GitHub. Un README bien formateado con tablas, badges, bloques de código e instrucciones claras aumenta significativamente la adopción de la librería o herramienta. La Vista Previa Markdown de WikiPlus usa la misma especificación GitHub Flavored Markdown que GitHub, lo que significa que lo que ves en la herramienta es exactamente lo que verán los visitantes del repositorio. Escribe, verifica y corrige sin necesidad de hacer commit y push solo para ver cómo queda.
Elementos de un buen README y cómo verificarlos
Un README efectivo para un proyecto open source incluye: un título claro con descripción de una línea, badges de estado (CI, cobertura, versión), una sección de instalación con bloques de código, una sección de uso básico con ejemplos, documentación de la API o de la configuración principal, instrucciones de contribución y la licencia. Cada uno de estos elementos tiene características Markdown específicas que deben renderizarse correctamente: los bloques de código deben tener resaltado de sintaxis, las tablas deben alinearse bien, los badges en formato imagen-enlace deben mostrar la imagen correctamente. Verificar todos estos elementos en la vista previa antes de publicar evita tener que hacer commits de corrección de formato que ensucian el historial del repositorio.
Resaltado de sintaxis en bloques de código
Para activar el resaltado de sintaxis en un bloque de código Markdown, añade el nombre del lenguaje justo después de los tres backticks de apertura: '```python', '```javascript', '```bash'. La Vista Previa de WikiPlus soporta más de 150 lenguajes, incluyendo todos los principales como Python, JavaScript, TypeScript, Rust, Go, Java, C++, SQL, Bash, YAML, TOML, JSON y Dockerfile. El resaltado ayuda a los lectores a entender los ejemplos de código más rápido y hace que el README se vea más profesional. Verifica siempre que el nombre del lenguaje que usas es exactamente el reconocido por el parser para evitar que el bloque aparezca sin resaltado en GitHub.
Crear tablas en Markdown para READMEs de APIs
Las tablas en Markdown usan pipes como separadores de columnas y guiones como separadores del encabezado. La alineación de columnas se controla con dos puntos en la fila de guiones: '---' para izquierda, ':---:' para centrado y '---:' para derecha. Son especialmente útiles en READMEs de APIs para documentar parámetros, tipos de datos y descripciones en formato tabular. La Vista Previa muestra las tablas renderizadas con el formato de GitHub, lo que permite verificar que el ancho de las columnas y la alineación del texto son correctos antes de publicar. Las tablas complejas con muchas columnas pueden ser difíciles de mantener en texto plano; para esos casos, algunos desarrolladores prefieren usar HTML directamente dentro del Markdown.
Listas de tareas y badges para repositorios activos
Las listas de tareas en GFM usan la sintaxis '- [ ]' para ítems pendientes y '- [x]' para ítems completados, y se renderizan como casillas de verificación interactivas en GitHub. Son útiles para secciones de 'Roadmap' o 'Contributing' que muestran el estado de las funcionalidades planificadas. Los badges de shields.io son imágenes en miniatura que muestran el estado del CI, la cobertura de tests, la versión publicada en npm o la licencia. En Markdown, se crean como imágenes envueltas en un enlace: '[](url-enlace)'. La Vista Previa renderiza estos badges como imágenes desde la URL externa, siempre que tengas conexión a internet cuando previsualizas.
Preguntas frecuentes
- ¿La vista previa renderiza exactamente igual que GitHub?
- Muy cerca. Implementa la misma especificación CommonMark + GFM que usa GitHub. Las diferencias menores pueden aparecer en el ancho de columnas de tablas, ya que GitHub ajusta el ancho de las columnas al contenido de cada celda y el renderizado del navegador puede diferir ligeramente. Verifica especialmente las tablas y el alineado de columnas directamente en GitHub después de hacer push para detectar cualquier diferencia residual.
- ¿Puedo usar HTML dentro del Markdown?
- Sí. CommonMark permite bloques HTML arbitrarios dentro del Markdown y la Vista Previa los pasa tal como están, lo que es el comportamiento conforme al estándar. Esto significa que cualquier HTML que incluyas en el fuente Markdown se renderizará en la vista previa exactamente como lo escribiste, incluyendo etiquetas de vídeo, alineaciones especiales o detalles summary. Recuerda que el HTML crudo en README de GitHub tiene algunas restricciones de seguridad adicionales que GitHub aplica sobre el estándar CommonMark.
- ¿La herramienta guarda mi contenido entre sesiones?
- No, la herramienta no persiste el contenido entre sesiones de navegador. Si cierras la pestaña o recargas la página, el texto del editor se pierde. Para guardar el trabajo en progreso, copia el contenido Markdown del editor a un archivo local o a tu editor de código habitual antes de cerrar la pestaña.