Convierte Issues GitHub a Markdown Automáticamente

Varias herramientas permiten convertir issues de GitHub a Markdown modificando solo la URL de la issue, sin instalar nada. gh2md, issue2md y servicios web como repo-to-markdown ofrecen este atajo para quien quiera exportar un issue completo con comentarios a un archivo .md que podés llevar a cualquier lado.

¿Por qué convertir GitHub issues a Markdown?

Ponele que trabajás en un proyecto en GitHub, pero el cliente quiere toda la documentación en Markdown en su servidor propio (o en Obsidian, o en una base de conocimiento). O capaz estás migrando issues a otro sistema y necesitás un backup legible. O simplemente querés que tu issue sea una página web, un post de blog, o un documento que podas compartir sin que el receptor tenga que entrar a GitHub.

Eso es lo que resuelve convertir issues a Markdown: sacás toda la información de una issue (título, descripción, comentarios, metadata) en un archivo .md limpio que podés meter en cualquier lado. (No es magia, pero zafa mucho.)

Los casos de uso más reales son estos:

• Documentación offline: tenés todos tus issues documentados en tu máquina, sin depender de GitHub
• Compartir con no-desarrolladores: le pasás un .md a quien no tiene acceso a GitHub y lo lee en cualquier editor
• Integración con IA: metés el Markdown en Claude o GPT para análisis, resumen o generación de respuestas
• Backup duradero: issues convertidas a Markdown resisten el paso del tiempo. GitHub puede cambiar, pero .md es forever
• Workflow editorial: las issues se convierten en posts de blog, newsletter, o documentación sin pasos manuales
• Migración neutral: si cambias de plataforma (GitLab, Gitea), Markdown es el formato que viaja limpio

Herramientas disponibles: comparativa rápida

Las principales herramientas para convertir issues son un puñado, y cada una apunta a un caso de uso diferente.

gh2md es la opción CLI más popular. La instalas con brew install gh2md (macOS) o scoop install gh2md (Windows), le pasas un token de GitHub API, y genera un Markdown por issue o un archivo consolidado. Funciona en batch.

issue2md (según el repo oficial) funciona cambiando la URL. No requiere instalación ni token. Vos copias la URL de tu issue y listo.

repo-to-markdown es un servicio web que convierte repos completos a Markdown, incluyendo issues si las seleccionas. Sin instalación, sin token requerido (aunque opcional).

GitHub Actions — Issue to Markdown es una acción que se dispara automáticamente cuando agregás un label a una issue, genera el Markdown y lo commitea al repo. Tema relacionado: ejecutar agentes locales sin conectarse a APIs.

export-github-issues (escrito en Rust según el repositorio) es parecido a gh2md pero más moderno. Instalable con cargo install export-github-issues.

Método URL: convertir issues cambiando solo la URL

Fijate que si lo que querés es rápido y sin instalación, este es el camino más directo.

Ponele que tenés una issue acá:

https://github.com/tu-usuario/tu-proyecto/issues/42

Con issue2md, copias esa URL, vas a https://issue2md.com/, pegás la URL y te descargá el issue como Markdown. Listo. Sin pasos de más, sin token, sin terminal.

O si preferís hacerlo todo en la URL, repo-to-markdown permite esto:

https://repo-to-markdown.com/?path=https://github.com/tu-usuario/tu-proyecto/issues/42

Y accedés el Markdown directamente desde ahí.

El tema es que esto funciona bien para una issue o un puñado, pero si necesitás convertir 50 issues de un proyecto, te duele hacer click 50 veces. Ahí entran las herramientas de línea de comandos.

Alternativas CLI: gh2md y otras herramientas de línea de comandos

Si necesitás procesar issues en volumen, la línea de comandos es tu amiga.

gh2md es el más popular. La instalás, agregás tu token de GitHub API, y corrés algo así:

gh2md -o owner/repo -t tu-token

Eso te descarga TODAS las issues del repo como Markdown. También podés filtrar por milestone, label, estado, autor. La salida es un archivo por issue o un consolidado, según cómo lo configures. El token lo generás en https://github.com/settings/tokens con permisos `repo` (para repos privados) o `public_repo` (solo públicos).

export-github-issues es similar pero escrito en Rust, lo cual significa más rápido. Instalás con cargo install export-github-issues y llamás:

export-github-issues --repo owner/repo --token tu-token --output ./issues/

Eso te genera un archivo Markdown por cada issue en la carpeta ./issues/. (Ojo: el token vive en tu máquina, no lo subas al repo público.)

Automatización con GitHub Actions

Si querés que esto sea automático (digamos, cada vez que alguien agrega una issue con el label “documentar”, se genera el Markdown automáticamente), usás GitHub Actions. Cubrimos ese tema en detalle en privacidad y seguridad en GitHub.

En tu repo, creás un archivo .github/workflows/export-issue.yml así:

name: Export Issue to Markdown
on:
  issues:
    types: [labeled]
jobs:
  export:
    if: github.event.label.name == 'documentar'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: mattduck/gh2md-action@v1
        with:
          issue-number: ${{ github.event.issue.number }}
          output-path: ./docs/
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - uses: actions/upload-artifact@v3
        with:
          name: issue-markdown
          path: ./docs/

Cada vez que agregás el label “documentar” a una issue, el workflow se dispara, genera el Markdown, y lo commitea al repo (o lo guarda como artifact). Esto es especialmente útil si tenés un blog basado en issues o si tu workflow editorial es “issue → review → Markdown → publicar”. Automático, sin fricciones.

Integración con flujos de desarrollo y documentación

Una vez que tenés tus issues como Markdown, ¿qué hacés con eso? Lo interesante viene acá.

Bases de conocimiento: metés los Markdown en Obsidian, Notion, o una wiki interna. Tus issues de desarrollo se convierten en documentación viva, buscable, offline.

Blogs y newsletters: convertís issues en posts de blog. Tu issue “Cómo implementamos X” se convierte a Markdown, le agregás metadata YAML (título, fecha, tags), y lo pusheás a tu blog. Subís, escribís, documentás, publicás, todo en un flujo. Te puede servir nuestra cobertura de herramientas modernas para automatización.

Integración con IA: metés el Markdown en Claude, ChatGPT, o Gemini. Podés pedirle que resuma la issue, genere FAQ a partir de los comentarios, traduzca, o lo que sea. El Markdown es el formato que todos los modelos procesan bien.

Control de cambios: si versionás tu documentación, tener issues como Markdown means que cada versión de tu doc tiene su issue asociada. Trazabilidad histórica, auditoría, nada perdido.

Errores comunes y solución de problemas

Issues privadas sin token: Si intentás convertir una issue privada sin pasar un token de GitHub API, te va a fallar con 404. Solución: generá un token en https://github.com/settings/tokens con permisos repo, y pasalo a la herramienta (flag --token o variable de entorno GITHUB_TOKEN).

Límites de API: Si convertís muchas issues de una vez, podés topar el límite de 60 requests por hora (GitHub API). Solución: authenticá con token (sube a 5000/hora) o espaciá los requests con delay entre ellos.

Comentarios anidados mal formateados: Algunos conversores no preservan la indentación de replies. El Markdown termina siendo un blob lineal, difícil de seguir. Solución: revisá la salida después de convertir, o usá un conversor que soporte nested comments (gh2md lo hace bien).

Caracteres especiales y emojis rotos: Símbolos raros, emojis, o caracteres especiales a veces se exportan mal según el encoding. Solución: asegurate que el archivo .md esté encoded en UTF-8. La mayoría de conversores lo hacen bien, pero si tenés problemas, abrí el archivo con VS Code y verificá.

Links rotos en el Markdown: URLs relativas de GitHub (ej: [link](#section)) quedan rotas una vez exportadas fuera de GitHub. Solución: usá un conversor que traduzca links relativos a URLs absolutas, o revisá y arreglá los links después. Complementá con alternativas a GitHub para control de versiones.

Preguntas Frecuentes

¿Cómo convertir una sola issue sin instalar nada?

Usá issue2md.com o repo-to-markdown.com. Copiá la URL de tu issue de GitHub, pegala en el sitio web, y descargá el Markdown. Sin instalación, sin token, sin comando.

¿Cuál es la diferencia entre gh2md e issue2md?

gh2md es una herramienta CLI que instalás localmente y que procesa en batch. issue2md es un servicio web rápido para convertir issues individualmente. gh2md es para procesar volumen, issue2md para cuando necesitás rápido y simple. Si necesitás convertir 100 issues, gh2md. Si necesitás convertir una, issue2md.

¿Puedo convertir issues con comentarios incluidos?

Sí. La mayoría de conversores (gh2md, issue2md, export-github-issues) incluyen comentarios por defecto. El Markdown generado preserva la estructura: título, descripción, y después cada comentario como bloque indentado o separado por línea.

¿Necesito un token de GitHub para exportar issues públicas?

No es obligatorio. Para repos públicos podés exportar sin token (limitado a 60 requests/hora). Pero si pasás un token, subís a 5000 requests/hora, así que es recomendado si vás a procesar muchas.

¿Qué formato de Markdown genera? ¿GFM, CommonMark, o qué?

Generalmente GFM (GitHub Flavored Markdown) o un subset compatible según la herramienta. Significa tablas, listas, code blocks, y links funcionan bien. No features exóticas, solo lo estándar que funciona en cualquier renderizador.

Conclusión

Convertir issues de GitHub a Markdown es útil si tu workflow involucra documentación, backup, compartición, o integración con otros sistemas. Tenés opciones para todos los niveles: desde “change the URL” si necesitás rápido, hasta CLI si necesitás batch, hasta GitHub Actions si querés automatizado.

Lo importante es que no estás atrapado en GitHub, subís, lo probás en local, funciona bárbaro, lo mandás a producción y de repente todo se rompe. No, en serio: una issue convertida a Markdown es un archivo, portable, legible, interoperable. Podés moverlo a donde sea — blog, wiki, base de conocimiento, modelo de IA — sin perder información.

Si alguna vez pensaste “che, necesito esta issue en otro lado”, ya sabés que hay herramientas para hacerlo en 2 minutos sin complicarse.

Fuentes

• gh2md — convertir issues de GitHub a Markdown en CLI
• issue2md — convertir issues por URL sin instalación
• repo-to-markdown — servicio web para convertir repos y issues
• GitHub Actions — Issue to Markdown (automatización en workflows)
• GitHub Docs — Escribir en GitHub (Markdown y sintaxis)