Cómo generar un README
- Rellena el nombre del proyecto, un eslogan de una línea opcional, y una breve descripción.
- Añade las insignias que quieras, elige un tipo (etiqueta/mensaje/color personalizados, licencia, versión de npm, estado de build, o estrellas/forks de GitHub), rellena sus datos, y se añade a la parte superior de tu README como una insignia real y viva de shields.io.
- Pega tus instrucciones de Instalación y Uso (texto plano o Markdown, incluyendo bloques de código), elige una Licencia, y añade una nota de Contribución si quieres.
- Observa cómo se actualiza la vista previa en vivo mientras escribes, y luego haz clic en Copy Markdown o Download README.md.
Por qué un constructor de README guiado
Todo proyecto real necesita un README, y la mayoría de los README comparten la misma estructura básica, un título, una breve descripción, algunas insignias, cómo instalarlo, cómo usarlo, bajo qué licencia está, cómo contribuir. Escribir esa estructura a mano cada vez (acertando con la sintaxis de la URL de la insignia, recordando el texto exacto de la licencia SPDX, ajustando los niveles de encabezado) es exactamente el tipo de tarea pequeña y repetitiva que merece la pena automatizar. Rellena un formulario, observa cómo se construye solo un README real y correctamente formateado mientras lo haces, y luego cópialo o descárgalo.
URLs de insignias reales y verificadas, no adivinadas
Las insignias son una de las partes más delicadas de escribir un README a mano: las convenciones de URL de shields.io (las reglas de escape de las insignias estáticas, la ruta correcta para una versión de npm frente a un contador de estrellas de GitHub frente a una insignia de estado de build) son fáciles de acertar mal por poco. Esta herramienta construye la URL de cada tipo de insignia siguiendo las convenciones documentadas oficialmente por shields.io, una insignia estática (/badge/etiqueta-mensaje-color), una insignia de versión de npm (/npm/v/<paquete>), una insignia de estado de build de GitHub Actions (/github/actions/workflow/status/<owner>/<repo>/<archivo-de-workflow>), e insignias de estrellas/forks de GitHub (/github/stars/<owner>/<repo>, /github/forks/<owner>/<repo>), así que la insignia simplemente funciona al pegarla en tu README real.
Una vista previa en vivo, con el mismo renderizador Markdown de este sitio
En lugar de escribir un segundo analizador de Markdown solo para el panel de vista previa, esta herramienta reutiliza exactamente el mismo motor de Markdown a HTML que hay detrás del Convertidor de Markdown a HTML, soporte de GitHub Flavored Markdown (tablas, tachado, listas de tareas, bloques de código) y el mismo paso de saneado con DOMPurify, así que el panel de vista previa es siempre igual de preciso (e igual de seguro) que ese convertidor ya establecido.
Licencias, y la que no es una licencia
Se ofrecen cuatro licencias reales, cada una con su identificador SPDX correcto: MIT, Apache 2.0, GPL 3.0 y BSD 3-Clause. Esos identificadores importan porque las herramientas los leen, y una abreviatura inventada falla en silencio.
La quinta opción es ninguna, es decir todos los derechos reservados. Deliberadamente no se trata como una licencia: no produce ninguna sección de licencia y ningún identificador, en lugar de fabricar uno. Ese es el comportamiento honesto para un proyecto que aún no ha elegido, y es un recordatorio visible de que la decisión sigue pendiente.
Seleccionar una licencia aquí escribe una sección en el README. No crea un archivo LICENSE, que es un documento aparte que tu repositorio sigue necesitando.
Encabezados en inglés, contenido en el tuyo
Los cuatro encabezados de sección son cadenas fijas en inglés. Es una decisión deliberada y no un descuido.
Installation, Usage, License y Contributing es lo que espera el ecosistema. GitHub, los registros de paquetes y los colaboradores que llegan desde cualquier parte del mundo buscan todos esas palabras, y un proyecto cuyo README las usa es más fácil de recorrer aunque todo lo que haya debajo esté escrito en otro idioma.
Para un proyecto en español esto es exactamente el reparto que conviene: los rótulos que sirven de señalización se quedan en el idioma que el ecosistema reconoce, y la prosa que de verdad explica el proyecto va en el tuyo. Todo lo que es genuinamente tuyo es texto libre. El nombre del proyecto, el lema, la descripción y los tres cuerpos de sección pueden escribirse en el idioma que use tu proyecto.
El resto del mobiliario del repositorio
El Generador de .gitignore produce el archivo de exclusiones para tu stack, que es el otro archivo que todo repositorio nuevo necesita el primer día.
Para tablas dentro del README, el Generador de Tablas Markdown construye la sintaxis de alineación para que no tengas que contar barras verticales. Convertir Markdown a HTML convierte el documento terminado si lo necesitas como página web, y Convertir Word a Markdown hace el camino inverso cuando la documentación ya existe en un procesador de textos. El Generador de Arte ASCII crea el cartel que algunos proyectos ponen arriba del todo.
Usos habituales
- Poner en marcha el README.md de un proyecto de código abierto totalmente nuevo en un par de minutos en lugar de copiar a mano una plantilla.
- Añadir una fila de insignias adecuada (versión de npm, estado de build, licencia) a un proyecto existente que nunca tuvo una.
- Estandarizar la estructura de los README en varios repositorios del mismo equipo.
- Combinarlo con el Generador de .gitignore al poner en marcha los archivos base de un repositorio totalmente nuevo.
- Construir una tabla de comparación u opciones para el propio cuerpo del README, mira el Generador de Tablas Markdown.
- ¿Ya tienes documentación en un documento de Word? Conviértela primero a Markdown con Word a Markdown, y luego pega las partes relevantes en los campos de Instalación/Uso/Contribución aquí.
