Cómo está organizado este portafolio con Astro y Markdown
Publicado el
El recorrido de un documento Markdown hasta sus tarjetas y su página estática: colecciones, módulos por funcionalidad y límites de publicación.
Un portafolio necesita presentar proyectos, explicar decisiones y permitir que su autor actualice el contenido. En este proyecto, esas necesidades se resuelven con archivos Markdown, páginas estáticas de Astro y componentes organizados por funcionalidad. Este artículo recorre la implementación del propio sitio: qué responsabilidad tiene cada pieza y qué límites conserva.
El punto de partida es concreto: cambiar la descripción de un proyecto debe actualizar su tarjeta y su caso de estudio sin editar el mismo texto en dos lugares. La estructura del repositorio y el contrato de contenido están diseñados alrededor de ese recorrido.
Contenido
- Dónde vive cada responsabilidad
- De Markdown a una tarjeta
- Una página para dos perspectivas
- Visibilidad editorial y privacidad
- Qué se ejecuta en el navegador
- Cómo comprobar un cambio
Dónde vive cada responsabilidad
La implementación actual distribuye sus piezas principales así:
src/
├── content/
│ ├── projects/ # Un Markdown por proyecto
│ ├── blog/ # Un Markdown por artículo
│ └── resume/cv.md # Fuente del CV
├── content.config.ts # Esquemas y carga de colecciones
├── pages/ # Rutas y conexión con el contenido
├── features/
│ ├── home/
│ ├── projects/
│ ├── blog/
│ ├── resume/
│ └── contact/
└── shared/ # Layouts, estilos y utilidades compartidasLas carpetas de features/ agrupan componentes que pertenecen a una capacidad del sitio. Por ejemplo, ProjectCard.astro y ProjectDetail.astro viven junto al catálogo de proyectos. La cabecera, el pie y los layouts se comparten entre rutas y viven en shared/.
La página «Sobre mí» sigue siendo una ruta editorial sencilla. No necesita una carpeta adicional mientras no tenga componentes o lógica que separar. La estructura describe responsabilidades existentes y puede crecer cuando aparezca una necesidad concreta.
| Pieza | Responsabilidad en este sitio |
|---|---|
| Markdown | Título, resumen, metadatos y cuerpo editorial |
| Content Collections | Validar y cargar los documentos |
| Ruta Astro | Consultar entradas visibles, ordenarlas y conectar la vista |
| Componente | Presentar los datos recibidos |
| Layout compartido | Mantener estructura HTML, navegación y estilos comunes |
De Markdown a una tarjeta
Cada proyecto tiene un archivo en src/content/projects/. Su frontmatter contiene datos como title, summary, status, technologies, featured y visibility. El cuerpo desarrolla el caso de estudio. El esquema de src/content.config.ts comprueba los metadatos: un título vacío falla y un proyecto destacado necesita una portada con texto alternativo.
La selección se realiza antes de presentar las tarjetas. En la ruta de inicio, getVisibleEntries('projects') obtiene las entradas que corresponden al entorno actual. Después se seleccionan los destacados y se ordenan por order, usando el identificador como desempate.
El componente recibe los datos necesarios. Su contrato reutiliza tipos de la colección mediante CollectionEntry y Pick, en lugar de mantener otra definición independiente de los mismos campos.
Esto permite seguir una modificación editorial completa:
- Se cambia
summaryen el Markdown del proyecto. - El build vuelve a cargar y validar la entrada.
- La tarjeta recibe el nuevo resumen desde la colección.
- El detalle usa esa misma entrada para presentar su cabecera y su cuerpo.
La portada se elige mediante cover y coverAlt. Las imágenes dentro del caso de estudio se escriben explícitamente en el Markdown. El sitio conserva ese orden: no recorre la carpeta para inventar una galería ni agrega automáticamente archivos que el autor no haya referenciado.
El catálogo de proyectos permite ver el resultado de este recorrido.
Una página para dos perspectivas
Un caso de estudio tiene lectores con preguntas distintas. Una persona puede querer saber qué problema resuelve el producto; otra, cómo se construyó.
En este sitio, las dos perspectivas pertenecen al mismo documento y a la misma URL. Cada Markdown de proyecto incluye los encabezados «Visión general» y «Detalle técnico». La ruta usa render() de Astro y comprueba que ambos existan antes de generar la página.
La navegación enlaza sus encabezados mediante anclas. El HTML contiene las dos secciones completas, de modo que se pueden leer y recorrer sin JavaScript. No hace falta cargar una segunda página ni ocultar una perspectiva detrás de una pestaña.
Los casos de KallosMD y RestoChain usan esta estructura. El contenido editorial sigue en sus respectivos Markdown; el componente compartido se encarga de presentarlo.
Visibilidad editorial y privacidad
El estado del software y la visibilidad de su documentación responden a preguntas diferentes. Un proyecto puede seguir en desarrollo y tener un caso de estudio público. Por eso status describe el proyecto y visibility controla dónde aparece su contenido.
Proyectos y artículos usan tres valores:
visibility |
Servidor de desarrollo | Build público |
|---|---|---|
public |
Visible | Incluido |
development |
Visible con aviso | Excluido |
hidden |
Excluido | Excluido |
La condición compartida en src/shared/content.ts es pequeña:
return visibility === 'public' ||
(visibility === 'development' && isDevelopment);Inicio, índices y generación de rutas usan este filtro antes de seleccionar o renderizar entradas. Así, excluir un artículo afecta tanto a su tarjeta como a su página de detalle.
Hay un límite importante: este filtro controla el HTML generado, no el acceso a los archivos del repositorio. Además, cualquier recurso colocado en public/ se copia al sitio aunque su artículo tenga visibility: hidden. Una captura privada no se protege ocultando su tarjeta. La revisión de privacidad debe ocurrir antes de guardar esos recursos allí.
Qué se ejecuta en el navegador
El procesamiento editorial ocurre al compilar: se leen los documentos, se validan sus metadatos y se producen las páginas estáticas. La lectura del blog y de los casos de estudio no depende de una API de contenido en el navegador.
El JavaScript propio de la interfaz se concentra en interacciones pequeñas, como el menú móvil y el botón de tema. La implementación actual utiliza JavaScript nativo para esas tareas. El tema empieza oscuro y permite guardar una elección manual entre claro y oscuro.
El CV también se renderiza desde Markdown. Su PDF es un archivo revisado por separado: modificar el Markdown no actualiza automáticamente la descarga. Mantener ambos alineados forma parte del trabajo editorial.
Cómo comprobar un cambio
Los comandos del repositorio separan varias comprobaciones:
npm run check
npm run test:content
npm run test:pages
npm run test:theme
npm run test:navigation
npm run buildEl chequeo de Astro revisa tipos y diagnósticos. Las pruebas de contenido ejercitan los esquemas con entradas válidas e inválidas. Las pruebas de páginas construyen sitios temporales para comprobar rutas, visibilidad, imágenes y navegación HTML. Las pruebas de tema y menú ejecutan los scripts con las APIs mínimas de navegador que necesitan.
Esas comprobaciones ayudan a detectar regresiones, pero no prueban por sí solas la legibilidad, el tacto o el comportamiento de un teléfono real. La revisión visual debe incluir contenido largo, ambos temas, teclado y tamaños estrechos. El despliegue requiere además comprobar enlaces y rutas en el hosting elegido.
El coste de esta arquitectura también es explícito: editar un Markdown exige recompilar y publicar de nuevo; el PDF requiere mantenimiento manual; y las validaciones de archivos no demuestran que una captura sea auténtica o tenga permiso de publicación. Son límites manejables para un portafolio estático, siempre que el flujo editorial los tenga presentes.