How midudev/minimalist-portfolio-json works
Project Type and Purpose
• This is a static, component-based portfolio/CV website built with Astro and TypeScript.
• Its source of truth is a JSON resume (cv.json) following the JSON Resume schema.
• It compiles to plain HTML/CSS/JS (static site) with a small client-side keyboard-shortcut component (Ninja Keys).
File Structure Analysis
• Top level
• astro.config.mjs, tsconfig.json – Astro + TypeScript configs
• package.json / pnpm-lock.yaml – dependencies & scripts (dev, build, preview)
• public/ – static assets served as-is
• src/pages/ – the single entry point index.astro
• src/layouts/Layout.astro – global wrapper
• src/components/ – generic UI pieces plus sections under components/sections/* (Hero, About, Experience, etc.)
• src/cv.d.ts, cv.json – typed JSON content that drives rendering
Key README Insights
• Uses Astro as a static-site framework.
• TypeScript for typing across components & JSON schema.
• Ninja Keys for a client-side keyboard menu.
• Build/Dev commands: pnpm dev, pnpm build, pnpm preview.
Main Architecture Components
a. Developer Machine (pnpm, Corepack)
b. Astro Build System
• Reads astro.config.mjs + TypeScript config
• Loads src/pages/index.astro + Layout + Components
• Parses cv.json via typed declarations (cv.d.ts)
• Applies templating to output static HTML/CSS/JS in dist/
c. Public Assets (public/)
• favicon, images (logo.png, portada.png), any other static files
d. Client-Side JavaScript
• Bundle with Ninja Keys (keyboard shortcuts)
• Minimal interactivity injected into the static page
e. Hosting / CDN
• Serves the contents of dist/ to end users; no dynamic server logic
Relationships & Data Flow
(1) Developer runs pnpm dev or pnpm build
→ (2) Astro reads config + TypeScript schemas
→ (3) Astro pulls in cv.json data → passes data into each Section component
→ (4) Components render HTML fragments
→ (5) Layout wraps them into a full page
→ (6) Static HTML/CSS/JS emitted to dist/
→ (7) In browser, Ninja Keys JS activates keyboard menu
→ (8) Browser displays final page
Architectural Patterns & Principles
• Static Site Generation (SSG): All HTML rendered at build time.
• Component Composition: Atomic & section-level Astro components for reusability.
• Strong Typing: JSON data typed with .d.ts files ensures data correctness.
• Separation of Concerns:
• Data (cv.json) vs. Presentation (Astro components)
• Static assets (public/) vs. source code (src/)
Technologies & Frameworks
• Astro – SSG framework
• TypeScript – static typing
• Ninja Keys – client-side keyboard menu
• pnpm/Corepack – package management
• JSON Resume schema – data structure for CV