Famfolio

A modern, configurable portfolio template with full RTL support and delightful animations.

Demo · Documentation

---

Features

• Single Configuration File - Everything controlled via config/site.config.yaml
• Full RTL Support - Arabic and other RTL languages with automatic layout mirroring
• Per-Locale Fonts - Different font families for each language (e.g., Outfit for English, Tajawal for Arabic)
• Dark/Light Themes - System-aware with smooth animated transitions
• Animated Transitions - Mascot-driven theme switch, page flip locale change
• Interactive Mascot - Playful blob character that follows your cursor
• Kinetic Typography - Letter-by-letter animations (LTR) or word animations (RTL)
• Self-Hosted Fonts - No external dependencies (Fontsource)
• Accessibility - Respects prefers-reduced-motion, keyboard navigation, ARIA labels
• OG Image Generation - Auto-generate social images for all themes/locales
• Security Features - Email obfuscation, honeypot spam protection, CSP headers, secure external links

---

Quick Start

Prerequisites

• Node.js 20+ or 22+
• Bun 1.0+ (recommended) or npm/pnpm

Installation

git clone https://github.com/F2had/famfolio.git  # HTTPS
git clone git@github.com:F2had/famfolio.git      # SSH (requires keys)

cd famfolio
bun install  # Install dependencies
bun dev      # Start development server

Configure Your Portfolio

Edit config/site.config.yaml:

personal:
  name:
    en: 'Your Name'
    ar: 'اسمك'
  title:
    en: 'Software Engineer'
    ar: 'مهندس برمجيات'

Build for Production

bun run build

Output will be in the dist/ folder, ready for static hosting.

---

Use as Template

Famfolio is designed to be used as a template for your own portfolio. Here's how to create your own and keep it updated with new features.

Option 1: GitHub Template (Recommended)

1. Click "Use this template" → "Create a new repository" on GitHub
2. Clone your new repository
3. Edit config/site.config.yaml with your information
4. Push and deploy!

Option 2: Fork

1. Fork this repository on GitHub
2. Clone your fork:

   git clone https://github.com/F2had/famfolio.git portfolio
   cd portfolio
   

3. Edit config/site.config.yaml and customize as needed
4. Push to your repository

Syncing Updates from Template

To get new features, bug fixes, and improvements from the original template:

# Add the original repo as a remote (only once)
git remote add template https://github.com/F2had/famfolio.git

# Fetch and merge updates
git fetch template
git merge template/master --allow-unrelated-histories

# Resolve any conflicts, then push
git push

Tips for smooth updates:

• Keep your customizations organized (fonts in one commit, config in another)
• The main conflict areas are config/site.config.yaml and custom fonts/styles
• Review the template's changelog before merging major updates

What You'll Typically Customize

File/Folder	What to Change
config/site.config.yaml	All your personal info, projects, colors, etc.
src/locales/*.json	UI text if adding new languages
src/assets/styles/_typography.scss	If adding custom fonts
public/	Your images, resume PDF, favicon

---

Configuration

All configuration is in config/site.config.yaml. Here's the complete reference:

Site Metadata

site:
  title: 'Your Name | Software Engineer' # Browser tab title
  description: 'Portfolio description' # Meta description for SEO
  url: 'https://yoursite.dev' # Production URL
  defaultLocale: 'en' # Initial language
  supportedLocales:
    - code: 'en'
      name: 'English'
      nativeName: 'English'
      dir: 'ltr'
    - code: 'ar'
      name: 'Arabic'
      nativeName: 'العربية'
      dir: 'rtl' # Right-to-left

Personal Information

All text fields support localization:

personal:
  name:
    en: 'Jane'
    ar: 'جين'
  lastName:
    en: 'Doe'
    ar: 'دو'
  title:
    en: 'Software Engineer'
    ar: 'مهندسة برمجيات'
  tagline:
    en: 'Building things that matter.'
    ar: 'أبني أشياء ذات قيمة.'
  email: 'hello@example.com'
  location:
    en: 'Mecca, Saudi Arabia'
    ar: 'مكة المكرمة'
  avatar:
    enabled: false # Show/hide avatar
    src: '/images/avatar.jpg' # Path in public folder

Social Links

socials:
  - platform: 'github'
    url: 'https://github.com/username'
    icon: 'github' # Lucide icon name
  - platform: 'linkedin'
    url: 'https://linkedin.com/in/username'
    icon: 'linkedin'
  - platform: 'twitter'
    url: 'https://twitter.com/username'
    icon: 'twitter'
  - platform: 'email'
    url: 'mailto:hello@example.com'
    icon: 'mail'
  - platform: 'telegram'
    url: 'https://t.me/username' # Or https://t.me/+1234567890 for phone
    icon: 'telegram'
  - platform: 'whatsapp'
    url: 'https://wa.me/1234567890' # Phone number without + or spaces
    icon: 'whatsapp'

Sections Toggle

Enable or disable any section:

sections:
  hero:
    enabled: true
  about:
    enabled: true
  projects:
    enabled: true
  blog:
    enabled: false # Disabled by default
  resume:
    enabled: true
    pdfPath: '/resume.pdf' # Path in public folder
  contact:
    enabled: true
    showForm: false # Show form or just info

Projects

defaults:
  codeForge: 'https://github.com/username' # Base URL for repos

projects:
  - id: 'project-1'
    title:
      en: 'Project Name'
      ar: 'اسم المشروع'
    description:
      en: 'Project description here.'
      ar: 'وصف المشروع هنا.'
    image: 'https://example.com/image.jpg'
    tech:
      - 'Vue'
      - 'TypeScript'
    links:
      live: 'https://project.dev'
      repo: 'project-name' # Appends to defaults.codeForge
    featured: true

  - id: 'project-2'
    # ... same structure
    links:
      code: 'https://gitlab.com/user/repo' # Full URL (overrides default)

Theme Colors

theme:
  defaultMode: 'system' # "light", "dark", or "system"
  colors:
    light:
      bgPrimary: '#FFFDF9'
      bgSecondary: '#F7F4EE'
      textPrimary: '#2D2926'
      textSecondary: '#6B635A'
      accent: '#C8873D'
      accentHover: '#A66E2C'
      accentSubtle: '#FDF6ED'
      border: '#E8E4DC'
    dark:
      bgPrimary: '#1A1816'
      bgSecondary: '#252220'
      textPrimary: '#F5F2ED'
      textSecondary: '#A69E94'
      accent: '#E9A54D'
      accentHover: '#F0B865'
      accentSubtle: '#2E2519'
      border: '#3A3632'

Typography (Per-Locale Fonts)

typography:
  fonts:
    en:
      display: 'Outfit' # Headings
      body: 'Source Sans 3' # Body text
    ar:
      display: 'Tajawal' # Arabic headings
      body: 'IBM Plex Sans Arabic' # Arabic body

Animations

animations:
  enabled: true # Master switch
  respectReducedMotion: true # Honor browser preference
  hero:
    toy: true # Mascot character
  scrollReveal: true
  hoverEffects: true
  transitions:
    theme:
      enabled: true # Mascot + ripple effect
    locale:
      enabled: true
      directionChange: 'pageFlip' # "pageFlip" or "cardFlip"
      sameDirection: 'fade' # "ripple" or "fade"

Security

security:
  email:
    obfuscate: true # Display as "hello [at] example [dot] com"
    clickToReveal: true # Require click to show real email
  contact:
    honeypot: true # Hidden field to catch spam bots
  externalLinks:
    noopener: true # Add rel="noopener noreferrer"
    newTab: true # Open in new tab (_blank)

Server-Side Headers (Docker deployments):

The included nginx and Caddy configs add these security headers:

• Content-Security-Policy (CSP)
• X-Frame-Options
• X-Content-Type-Options
• Referrer-Policy
• Permissions-Policy

---

Customization

Adding a New Language

1. Add the locale to config/site.config.yaml:

site:
  supportedLocales:
    - code: 'es'
      name: 'Spanish'
      nativeName: 'Español'
      dir: 'ltr'

2. Create translation file src/locales/es.json:

{
  "nav": {
    "about": "Sobre mí",
    "projects": "Proyectos"
  }
}

3. Add localized content in config:

personal:
  name:
    en: 'Jane'
    es: 'Juan'

4. (Optional) Add fonts for the new locale in typography.fonts.

Adding Custom Fonts

1. Install from Fontsource:

bun add @fontsource/your-font

2. Import in src/assets/styles/_typography.scss:

@import '@fontsource/your-font/400.css';
@import '@fontsource/your-font/700.css';

3. Update config/site.config.yaml:

typography:
  fonts:
    en:
      display: 'Your Font'

Disabling Animations

Set the master switch to disable all animations:

animations:
  enabled: false

Or disable specific features:

animations:
  enabled: true
  hero:
    toy: false # Disable mascot only
  transitions:
    theme:
      enabled: false # Disable theme transition effect

---

Development

Available Scripts

bun dev                      # Start development server
bun dev:demo                 # Start dev server with demo config
bun run build                # Type-check and build for production
bun run build:demo           # Build with demo config
bun run preview              # Preview production build locally
bun run type-check           # Run TypeScript type checking
bun run lint                 # Run all linters (oxlint + eslint)
bun run format               # Format code with Prettier
bun run lighthouse           # Run Lighthouse audit locally
bun run generate:og          # Generate OG images (default locale)
bun run generate:og:all      # Generate OG images for all locales
bun run ci:test              # Test all CI jobs locally with act
bun run ci:test:lint         # Test lint & build job only
bun run ci:test:security     # Test security audit job only
bun run ci:test:lighthouse   # Test Lighthouse CI job only

Project Structure

famfolio/
├── src/
│   ├── assets/styles/      # SCSS (variables, typography, animations)
│   ├── components/
│   │   ├── common/         # Reusable (BaseButton, ProjectCard, etc.)
│   │   ├── layout/         # Navigation, Footer, SectionWrapper
│   │   ├── sections/       # Hero, About, Projects, Contact, etc.
│   │   └── transitions/    # Theme and Locale transition effects
│   ├── composables/        # V