Skip to main content

​
Overview

The Astro Portfolio v3 project follows a clean, organized structure that separates concerns and makes the codebase easy to navigate. This guide will walk you through each major directory and explain its purpose.

​
Root Directory Structure

astro-portfolio-v3/
├── src/                    # Source code
├── public/                 # Static assets
├── .github/               # GitHub workflows and configurations
├── .vscode/               # VS Code settings
├── astro.config.mjs       # Astro configuration
├── tsconfig.json          # TypeScript configuration
├── package.json           # Dependencies and scripts
├── wrangler.jsonc         # Cloudflare deployment config
└── components.json        # UI components configuration
The project is configured for server-side rendering (SSR) with Cloudflare as the adapter, as defined in astro.config.mjs:15-16.

​
Source Directory (src/)

The src/ directory contains all the application code and is organized into logical subdirectories: 
src/
├── assets/            # Images, fonts, and other assets
├── components/        # Reusable Astro components
├── content/          # Content collections (blog, projects, etc.)
├── data/             # JSON data files
├── layouts/          # Page layout templates
├── lib/              # Utility libraries
├── pages/            # File-based routing pages
├── styles/           # Global styles and CSS
├── utils/            # Helper functions
├── config.ts         # Site configuration
└── content.config.ts # Content collections schema

​
Components Directory

The components are organized by category for better maintainability:
Located in src/components/home/:
  • About.astro - About section component
  • Blogs.astro - Blog listing component
  • HeroImage.astro - Hero section image
  • HeroText.astro - Hero section text
  • Projects.astro - Projects showcase
  • WorkExperience.astro - Work experience timeline
See the Components page for detailed documentation.

​
Content Directory

Content is organized using Astro’s Content Collections API: 
src/content/
├── about/           # About page content
├── advisory/        # Advisory services content
├── blog/           # Blog posts (Markdown)
├── experience/     # Work experience entries
├── operatingNotes/ # Operating notes
├── projects/       # Project portfolio items
└── sponsors/       # Sponsors information
Learn more about Content Collections.

​
Data Directory

JSON files for structured data that doesn’t need frontmatter: 
src/data/
├── socials.json        # Social media links
├── books.json          # Reading list
├── tech-stack.json     # Technology stack
└── desktop-setup.json  # Desktop setup items

​
Pages Directory

File-based routing powered by Astro: 
src/pages/
├── index.astro          # Homepage
├── contact.astro        # Contact page
├── projects.astro       # Projects listing
├── api/                 # API routes
│   └── newsletter.ts    # Newsletter subscription endpoint
└── blog/
    ├── index.astro      # Blog listing
    └── [slug]/
        └── index.astro  # Blog post template
The [slug] directory uses dynamic routing to generate individual blog post pages from the content collections.

​
Public Directory

Static assets that are served directly without processing: 
public/
├── favicon.svg          # Site favicon
├── opengraph.png       # Social media preview image
├── site.webmanifest    # PWA manifest
└── projects/           # Project images
Files in the public/ directory are served at the root path and can be referenced directly (e.g., /favicon.svg).

​
Configuration Files

astro.config.mjs

Main Astro configuration including i18n, integrations, and deployment settings.See: ~/workspace/source/astro.config.mjs

content.config.ts

Defines schemas for all content collections using Zod for type safety.See: ~/workspace/source/src/content.config.ts

config.ts

Site-wide configuration like name, description, and social links.See: ~/workspace/source/src/config.ts

tsconfig.json

TypeScript compiler options and path aliases.See: ~/workspace/source/tsconfig.json

​
Key Design Patterns

​
Path Aliases

The project uses TypeScript path aliases for cleaner imports: 
import { ThemeSwitcher } from '@/components/shared';
import { siteConfig } from '@/config';
import { getLangFromUrl } from '@/utils/i18n';
The @/ alias maps to the src/ directory, configured in tsconfig.json.

​
Component Organization

Components are grouped by their purpose:
  • home/ - Homepage-specific sections
  • navs/ - Navigation and footer
  • shared/ - Reusable across multiple pages
  • ui/ - Base UI elements and icons
This structure makes it easy to locate components and understand their scope.

​
Content First

The project embraces Astro’s content-focused approach:
  1. Content is stored in type-safe collections
  2. Schemas ensure data integrity
  3. Static generation for optimal performance

​
Next Steps

Components

Learn about the component architecture and how to use existing components

Content Collections

Understand how to add and manage content using Astro’s Content Collections API

i18n Setup

Explore the internationalization system and how to add translations

Theming

Discover how the theme system works and how to customize it

Build docs developers (and LLMs) love

Get started for freeTalk to us