MarkdownCV

MarkdownCV es un workspace para construir, editar y exportar un CV profesional desde Markdown, con una interfaz web en Streamlit y una salida pensada para PDF ATS-friendly.

Requerimientos y como satisfacerlos

Para que el proyecto funcione correctamente, necesitas cumplir estos puntos:

1. Python 3.10 o superior.
2. Un instalador real de Python en Windows, o el lanzador py -3.
3. wkhtmltopdf instalado en el equipo.
4. Un entorno donde PowerShell pueda ejecutar scripts locales.

El script run_app.ps1 resuelve gran parte de esto por ti:

• Crea .venv si no existe.
• Actualiza pip dentro del entorno virtual.
• Verifica si faltan dependencias en requirements.txt.
• Busca wkhtmltopdf en este orden: variable de entorno WKHTMLTOPDF_PATH, ruta por defecto de Windows, y finalmente PATH.
• Si lo encuentra, registra WKHTMLTOPDF_PATH como variable de usuario y luego levanta Streamlit.

Si wkhtmltopdf no esta en el PATH, define la variable antes de arrancar la app:

$env:WKHTMLTOPDF_PATH = "C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe"

Si necesitas ejecutar el script con instalacion forzada o sin reinstalar dependencias, run_app.ps1 acepta estos switches:

.\run_app.ps1 -ForceInstall
.\run_app.ps1 -SkipInstall

Como levantar la app con el .bat

La forma mas simple en Windows es usar run_app.bat. Ese lanzador evita pelearte con la politica de ejecucion de PowerShell y delega todo en run_app.ps1.

run_app.bat

Detras de escena, el .bat ejecuta el script de PowerShell con ExecutionPolicy Bypass solo para esa sesion, por lo que el flujo queda limpio y repetible sin tocar la configuracion global del sistema.

Como levantarla desde la terminal si lo anterior falla

Si prefieres manejarlo manualmente, el flujo tradicional sigue siendo totalmente valido.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
streamlit run app.py

Si PowerShell bloquea la activacion del entorno virtual, puedes usar una sesion puntual con bypass:

powershell -NoProfile -ExecutionPolicy Bypass -File .\run_app.ps1

En cualquier modo, la app suele quedar disponible en:

http://localhost:8501

Como usar la aplicacion

La interfaz esta organizada como un flujo guiado por paginas en la barra lateral. La idea es que puedas cargar un CV en Markdown, ajustarlo visualmente, completar datos de contacto y generar el PDF final sin salir del navegador.

1. Welcome

En esta primera pantalla cargas tu archivo .md.

• Al subir un Markdown, la app guarda una version de trabajo en cvs/ con el mismo nombre base.
• Si el archivo cambia, la sesion limpia el estado de generacion previa para evitar exportar una version desactualizada.
• La navegacion a la siguiente etapa queda habilitada solo cuando ya hay contenido cargado.

2. Edit Markdown

Aqui editas el contenido con un editor estilo IDE, usando ACE integrado en Streamlit.

• El editor trabaja sobre el Markdown cargado inicialmente.
• El estado de cambios se marca como Unsaved changes mientras el contenido editado difiere del contenido base.
• Al guardar, el Markdown se persiste en cvs/<nombre>.md.
• El guardado mantiene saltos de linea estables en Windows para evitar problemas de EOL duplicados.

3. Contact & Social

Esta seccion concentra los datos de identidad y enlaces sociales que alimentan la plantilla final.

• Puedes editar telefono y email.
• Puedes ajustar GitHub y LinkedIn, tanto la URL como el texto visible.
• La app intenta inferir el username desde la URL si el campo de texto esta vacio.
• El titulo principal del CV se selecciona desde una lista configurable.
• Tambien puedes administrar titulos desde la propia UI: agregar, editar y eliminar opciones.

4. Preview & Generate

Esta es la etapa final antes de exportar.

• La app renderiza una vista previa HTML embebida.
• Al generar el PDF, el documento anterior se archiva en archive/ con sufijo incremental.
• El PDF nuevo se guarda junto al Markdown en cvs/<nombre>.pdf.
• Si el archivo existe y se genero en la sesion actual, puedes abrirlo desde la propia app.

Features principales

• Editor Markdown web con experiencia de escritura tipo editor de codigo.
• Vista previa HTML en tiempo real para revisar el resultado final antes de exportar.
• Generacion de PDF con pdfkit y wkhtmltopdf.
• Archivado automatico de PDFs previos para no perder versiones anteriores.
• Persistencia de borradores Markdown en cvs/.
• Configuracion editable de contacto, GitHub, LinkedIn y titulo profesional.
• Gestion de titulos desde la UI, sin tocar archivos a mano.
• Deteccion automatica de wkhtmltopdf en entornos Windows.

Explicacion del repositorio

El repositorio esta organizado para separar la interfaz, la generacion de salida y los datos editables del CV.

• app.py: aplicacion principal de Streamlit. Orquesta la carga del Markdown, la edicion, la configuracion de datos y la exportacion del PDF.
• run_app.ps1: bootstrap moderno para Windows. Crea o reutiliza .venv, valida dependencias, resuelve wkhtmltopdf y arranca la app.
• run_app.bat: lanzador simple para usuarios que prefieren doble clic o comandos basicos en Windows.
• generate_pdf.py: utilidad CLI para convertir un Markdown a PDF fuera de la interfaz web.
• data.yaml: datos personales, contacto, enlaces y titulo activo del CV.
• title_options.yaml: catalogo de titulos disponibles para el selector de la app.
• template.html: plantilla HTML que define la presentacion final del CV exportado.
• cvs/: espacio de trabajo para Markdown editado y PDFs generados.
• archive/: historico de PDFs previos, protegido para conservar versiones anteriores.
• requirements.txt: dependencias Python necesarias para la app y la exportacion.

Flujo recomendado

1. Abre run_app.bat o ejecuta run_app.ps1.
2. Sube tu CV en Markdown.
3. Ajusta el contenido en el editor.
4. Completa contacto, enlaces y titulo profesional.
5. Revisa la vista previa HTML.
6. Genera el PDF final y revisa la version archivada si ya existia una anterior.

Notas tecnicas

• La app intenta resolver wkhtmltopdf en este orden: WKHTMLTOPDF_PATH, ruta por defecto de Windows y PATH.
• En Windows, el alias de Microsoft Store para python no es suficiente para este proyecto; conviene usar una instalacion real o py -3.
• Si abres el proyecto desde cero en otra maquina, el primer arranque puede tardar un poco mientras se crea el entorno virtual y se instalan dependencias.