A blazing-fast portfolio, blog, and digital garden built with modern web technologies.
- Overview
- Features
- Tech Stack
- Architecture
- Project Structure
- Getting Started
- Scripts Reference
- Deployment
- Contributing
- Documentation & Resources
- License
- Contact
A server-side rendered personal website that serves as a digital resume, project showcase, and writing platform. Built with Astro 5 using the Islands Architecture — static content ships zero JavaScript, while React 19 islands handle interactivity. Content is managed through Sitepins, a Git-based headless CMS with a visual editor, and the site is deployed on Vercel with ISR caching for near-instant page loads.
Pages: Home · Blog · Projects · About · Experience · Contact · Search · RSS · Wiki
|
Islands Architecture Astro handles static content with zero JS overhead. React 19 islands power interactive components with the React Compiler enabled for automatic optimization. |
Visual Content Editing Sitepins provides a Git-based visual editing experience with media management, role-based access control, and AI-assisted content generation — all version-controlled through Git. |
|
Content Collections MDX-based blog posts and project pages validated with Zod schemas. Supports drafts, archived status, featured flags, tags, and SEO metadata. |
Full-Text Search On-site content search powered by Fuse.js with fuzzy matching for fast, typo-tolerant results across all content. |
|
SEO & Performance Auto-generated sitemap, RSS feed, OpenGraph images, and structured metadata. Terser minification strips all console statements in production. Manual chunk splitting for optimal loading. |
Feature Flags JSON-driven toggles to enable/disable site sections and API endpoints without code changes. Managed through Sitepins or direct file editing. |
|
Responsive Design Mobile-first layout with a custom Tokyo Night-inspired color system, Poppins typography, and smooth Framer Motion animations. |
Developer Experience Bun for fast installs, Biome for linting and formatting, TypeScript strict mode, and path aliases for clean imports. |
Also includes: Web3Forms contact form · GDPR cookie consent · Mermaid diagram rendering · Shiki syntax highlighting (Tokyo Night) · API routes for articles, authors & projects · Vercel Speed Insights
| Layer | Technology | Docs |
|---|---|---|
| Framework | Astro 5 (SSR mode, ISR) | docs.astro.build |
| UI | React 19, Framer Motion, Lucide Icons | react.dev |
| Styling | Tailwind CSS, Typography plugin | tailwindcss.com/docs |
| CMS | Sitepins (Git-based headless CMS) | docs.sitepins.com |
| Content | MDX, Zod schemas | mdxjs.com/docs |
| Language | TypeScript (strict) | typescriptlang.org/docs |
| Runtime | Bun | bun.sh/docs |
| Linting | Biome (lint + format) | biomejs.dev/docs |
| Hosting | Vercel (ISR + Speed Insights) | vercel.com/docs |
| Syntax | Shiki (Tokyo Night theme) | shiki.style |
| Diagrams | Mermaid (client-side rendered) | mermaid.js.org |
┌─────────────────────────────────┐
│ Vercel (SSR + ISR) │
└──────────────┬──────────────────┘
│
┌──────────────▼──────────────────┐
│ Astro 5 Framework │
│ (Islands Architecture) │
└──┬────────────────────────┬─────┘
│ │
┌────────────▼────────┐ ┌────────────▼────────────┐
│ Astro Components │ │ React 19 Islands │
│ (Static, 0 JS) │ │ (Interactive, Hydrated)│
└─────────────────────┘ └─────────────────────────┘
│ │
┌────────────▼────────────────────────▼─────┐
│ Content Collections (MDX) │
│ blog/ (posts) · projects/ (portfolio) │
└──────────────┬────────────────────────────┘
│
┌──────────────▼──────────────────┐
│ Sitepins (Git-based CMS) │
│ Visual Editor · Media Mgmt │
└─────────────────────────────────┘
Astro-Portfolio-Blog/
├── public/ # Static assets (favicons, images, fonts)
├── src/
│ ├── assets/ # Processed assets (images optimized by Astro)
│ ├── components/
│ │ ├── AstroComponent/ # Static Astro components (zero JS)
│ │ └── ReactComponent/ # Interactive React islands (hydrated)
│ ├── config/
│ │ ├── featureFlag/ # Feature flag definitions (JSON)
│ │ └── theme/ # Tokyo Night color system & tokens
│ ├── content/
│ │ ├── blog/ # MDX blog posts
│ │ └── projects/ # MDX project pages
│ ├── hooks/ # Custom React hooks
│ ├── layouts/ # Page layouts (BlogPost, Project, Base)
│ ├── pages/
│ │ ├── api/ # Server API routes (article, author, project)
│ │ ├── blog/ # Blog listing & individual posts
│ │ ├── project/ # Project listing & detail pages
│ │ ├── tag/ # Tag-based content filtering
│ │ └── ... # Home, About, Experience, Contact, Search
│ ├── styles/ # Global styles & Tailwind utilities
│ └── types/ # Shared TypeScript type definitions
├── .sitepins/ # Sitepins CMS configuration & schemas
├── scripts/ # Build & utility scripts
├── astro.config.mjs # Astro configuration
├── tailwind.config.mjs # Tailwind CSS configuration
├── biome.json # Biome linter/formatter config
└── tsconfig.json # TypeScript configuration
| Tool | Version | Install |
|---|---|---|
| Bun | v1.0+ | bun.sh |
| Sitepins Account | — | Optional. Only for CMS features. Sign up here |
# 1. Clone the repository
git clone https://github.com/rafay99-epic/Astro-Portfolio-Blog.git
cd Astro-Portfolio-Blog
# 2. Install dependencies
bun install
# 3. Start the dev server
bun run dev
# 4. Open in browser
open http://localhost:4321Content is managed via Sitepins — a cloud-based CMS that connects directly to your Git repository. No local token required.
| Command | Description |
|---|---|
bun run dev |
Start development server |
bun run build |
Astro production build |
bun run production_build |
Full production build |
bun run preview |
Preview the production build locally |
bun run lint |
Run Biome checks + TypeScript type check |
bun run lint:fix |
Auto-fix lint issues with Biome |
bun run check |
Astro diagnostics (template/component checks) |
bun run scan |
Run react-scan against local dev server |
Deployed on Vercel with automatic deployments from the main branch.
| Environment | URL | Branch |
|---|---|---|
| Production | rafay99.com | main |
| Previews | Auto-generated | Every PR |
Contributions are welcome. Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit your changes:
git commit -m 'feat: add your feature' - Push to the branch:
git push origin feature/your-feature - Open a Pull Request targeting the
testingbranch
Note: PRs should target
testing, notmain. PRs tomainwill be redirected.
Official docs for the technologies used in this project:
| Technology | Documentation |
|---|---|
| Astro | docs.astro.build |
| React | react.dev/learn |
| React Compiler | react.dev/learn/react-compiler |
| Sitepins | docs.sitepins.com |
| Sitepins Developer Docs | developer.sitepins.com |
| Sitepins + Astro Guide | docs.astro.build/en/guides/cms/sitepins |
| Tailwind CSS | tailwindcss.com/docs |
| TypeScript | typescriptlang.org/docs |
| Bun | bun.sh/docs |
| Biome | biomejs.dev |
| Framer Motion | motion.dev/docs |
| Zod | zod.dev |
| MDX | mdxjs.com/docs |
| Mermaid | mermaid.js.org/intro |
| Shiki | shiki.style |
| Vercel | vercel.com/docs |
| Shields.io (badges) | shields.io |
Distributed under the MIT License. See LICENSE for full details.
If you found this project helpful, consider giving it a star!
