Documentar es una de las tareas que más cuesta a los programadores, pero Markdown lo simplifica de forma notable. Este lenguaje de marcado permite crear portadas atractivas para tu perfil de GitHub, agregar badges con estadísticas de actividad y presentar tu información profesional de manera clara. A continuación se explica paso a paso cómo lograrlo.

¿Cómo crear el repositorio especial para tu portada de GitHub?

Para que tu perfil de GitHub muestre una portada personalizada, necesitas crear un repositorio cuyo nombre sea exactamente igual a tu nombre de usuario [0:52]. Este es el detalle más importante de todo el proceso. Cuando lo haces correctamente, GitHub despliega una leyenda confirmando que se trata de un repositorio especial cuyo archivo README aparecerá en tu perfil público [1:08].

Los pasos para configurarlo son:

• Ir a la sección de repositorios y crear uno nuevo.
• Escribir tu nombre de usuario como nombre del repositorio.
• Marcarlo como público.
• Activar la opción de agregar el archivo README.
• Crear el repositorio.

Una vez creado, puedes clonarlo en tu máquina local usando git clone con la URL que obtienes del botón code [1:52]. Si estás en un perfil nuevo, puedes usar HTTPS, aunque la mejor práctica de seguridad es configurar SSH [2:02].

¿Qué contenido puedes agregar al README de tu perfil?

Al abrir el archivo README en Visual Studio Code, encontrarás un header y comentarios con sugerencias que puedes eliminar [2:25]. Dentro de los recursos de la clase se comparte un texto base que puedes personalizar.

El contenido típico incluye:

• Emojis descriptivos entre dos puntos, como íconos de computadora o lápiz.
• Una breve descripción profesional, por ejemplo: ingeniero de software, generador de contenido.
• Títulos con tres signos numerales (###) para organizar secciones como vías de contacto [3:09].

Visual Studio Code permite previsualizar los cambios de Markdown en tiempo real presionando el ícono de Open Preview en la parte superior derecha [2:58]. Aunque VSCode no renderiza todos los emojis, estos sí se despliegan correctamente dentro de GitHub.

¿Qué son los badges y cómo agregarlos a tu perfil?

Los badges o medallas son pequeños recuadros visuales que muestran información dinámica sobre tu perfil o repositorios [3:36]. Se generan a partir del sitio shields.io/badges, donde encontrarás una amplia variedad de categorías disponibles [3:50].

Para agregar un badge en Markdown se usa la sintaxis de enlace con imagen: entre corchetes el texto alternativo y entre paréntesis la URL del badge. Por ejemplo, puedes crear uno de tipo Website ingresando la URL de tu sitio web en shields.io y ejecutando la generación [4:08].

¿Cómo mostrar tu actividad de commits con un badge?

Una opción muy útil es el badge de GitHub Commit Activity, disponible en la categoría Activity de shields.io [4:27]. Este badge muestra cuántos commits has realizado en un repositorio específico durante un periodo determinado:

• W (weekly): actividad semanal.
• M (monthly): actividad mensual.
• Y (yearly): actividad anual.
• T (total): actividad total.

Una vez generado, seleccionas el formato Markdown, copias el código y lo pegas en tu README [5:15]. Puedes repetir esto con varios repositorios para mostrar tu desempeño. Si algún repositorio no tiene actividad relevante, simplemente eliminas esa línea y el badge desaparece [5:50].

¿Qué extensiones de VSCode facilitan escribir Markdown?

Para trabajar de forma más cómoda con Markdown, puedes instalar extensiones desde el panel de extensiones de VSCode [6:03]. Una recomendación es Markdown Lint, que ofrece tips en tiempo real sobre buenas prácticas del lenguaje, como evitar líneas múltiples en blanco [6:18].

Cuando termines de editar tu portada, el flujo de publicación es sencillo:

• git status para verificar los cambios.
• git add . para agregar todos los archivos.
• git commit -m "portada actualizada" para confirmar.
• git push para subir los cambios a GitHub [6:38].

Al actualizar tu perfil en el navegador, verás los badges y la descripción con emojis reflejados de inmediato [6:52].

Un consejo valioso para aprender más Markdown es visitar repositorios con buena documentación, como el de Azure OpenAI, y seleccionar la opción raw en su archivo README [7:17]. Esto te muestra el código Markdown en crudo, permitiéndote entender cómo se construyen imágenes, enlaces, títulos y badges. Cuanto más explores portadas de otros perfiles y documentación de proyectos, más experiencia ganarás con este lenguaje.

Comparte tu portada personalizada en los comentarios para que todos puedan conocer tu perfil de GitHub.