Documentation for Twnty

#Introduction

Twnty is a modern personal portfolio, resume, and blog theme built with Astro v7 and TailwindCSS v4. Designed for designers, developers, writers, and digital creators, Twnty features:

• Interactive Fisheye Dock Navigation: A macOS-style dock side navigation with smooth fisheye magnification physics on cursor hover, automatic active section highlighting on scroll, and a mobile bottom drawer menu.
• All-in-One Resume & Portfolio Layout: Hero bio, numerical achievement counters, service offerings, career experience timeline, visual skill progress bars, client logos, testimonials, transparent pricing tables, accordion FAQ, and a working contact form.
• Dual Showcase Portfolio: Highlights your top featured case study as a full hero card, followed by two-column grid cards, dedicated single case study pages, and pagination.
• Editorial Blog System: Complete journal system with inline newsletter subscription cards, reading time estimation, syntax highlighting powered by Astro Expressive Code, and 5-platform social sharing.
• Zero-Config Contact Form: Built-in contact form powered by FormSubmit with direct email delivery.

#File Structure

The theme files are structured as follows:

 ./theme-files
│
├── public
│  │
│  ├── favicon.ico
│  │
│  ├── ogimage.jpg
│  │
│  └── robots.txt
│
├── src
│  │
│  ├── assets
│  │  │
│  │  └── images
│  │     │
│  │     ├── blog
│  │     │
│  │     ├── clients
│  │     │
│  │     ├── project
│  │     │
│  │     └── profile.jpg
│  │
│  ├── components
│  │  │
│  │  ├── blog
│  │  │  │
│  │  │  └── BlogCard.astro
│  │  │
│  │  ├── helpers
│  │  │  │
│  │  │  ├── AstroImage.astro
│  │  │  │
│  │  │  └── DeviceSizeIndicator.astro
│  │  │
│  │  ├── landing
│  │  │  │
│  │  │  ├── Achievements.astro
│  │  │  │
│  │  │  ├── Banner.astro
│  │  │  │
│  │  │  ├── Clients.astro
│  │  │  │
│  │  │  ├── Contact.astro
│  │  │  │
│  │  │  ├── Experience.astro
│  │  │  │
│  │  │  ├── FAQ.astro
│  │  │  │
│  │  │  ├── Pricing.astro
│  │  │  │
│  │  │  ├── Projects.astro
│  │  │  │
│  │  │  ├── Services.astro
│  │  │  │
│  │  │  ├── Skills.astro
│  │  │  │
│  │  │  └── Testimonials.astro
│  │  │
│  │  ├── project
│  │  │  │
│  │  │  ├── ProjectCard.astro
│  │  │  │
│  │  │  └── ProjectCardTwo.astro
│  │  │
│  │  ├── Navigation.astro
│  │  │
│  │  ├── Newsletter.astro
│  │  │
│  │  ├── Pagination.astro
│  │  │
│  │  ├── SectionTitle.astro
│  │  │
│  │  └── SocialShare.astro
│  │
│  ├── config
│  │
│  ├── content
│  │
│  ├── layouts
│  │
│  ├── pages
│  │
│  ├── styles
│  │
│  └── content.config.ts
│
├── .gitignore
│
├── astro.config.mjs
│
├── package.json
│
└── tsconfig.json

#Quick Start & Installation

Getting your portfolio up and running locally takes less than two minutes.

#System Requirements

• Node.js - v22.12.0 or higher installed on your computer (Download Node.js).
• Code Editor - We recommend VS Code with the Official Astro Extension.
• Terminal - Mac Terminal, Command Prompt, or VS Code integrated terminal.

#Step 1: Install Dependencies

Unzip your downloaded template, open your terminal, navigate into the project folder, and run:

npm install

#Step 2: Start Local Preview

Start the local development server:

npm run dev

Open http://localhost:4321 in your web browser. You will see Twnty running live with instant hot-reloading as you edit files!

#Global Site Settings

All core settings—including your website URL, creator name, professional role, pagination, and SEO metadata—are configured in src/config/site.config.json.

{
  "baseURL": "https://yourportfolio.com",
  "favicon": "/favicon.ico",
  "basePath": "/",
  "trailingSlash": false,

  "site": {
    "logo_title": "Twnty Watts",
    "logo_subtitle": "Designer x Writer",
    "blog_paginate": 5,
    "project_paginate": 4
  },

  "metadata": {
    "title": "Twnty - Personal Blog x Portfolio",
    "description": "Twnty is a personal blog and portfolio theme for Astro based on TailwindCSS.",
    "author": "Twnty Watts",
    "keywords": "portfolio, resume, cv, blog, designer, developer, astro",
    "image": "/ogimage.jpg"
  }
}

#Field Breakdown:

• baseURL: Your website's live web address. Used for canonical URLs, sitemaps, and social cards.
• site.logo_title: Your name or brand title shown in the top navigation header.
• site.logo_subtitle: Your professional title or tagline (e.g. "Product Designer & Writer").
• site.blog_paginate: Number of articles shown per page on /blog before pagination kicks in.
• site.project_paginate: Number of case studies shown per page on /project.
• metadata:
  • title: The title displayed in the browser tab and search results.
  • description: The short summary shown in search engine results and social link shares.
  • image: The preview banner displayed when sharing your link on Twitter/X, LinkedIn, or Facebook.

#Navigation & Menus

The header navigation links are configured in src/config/menus.json.

[
  {
    "name": "Writing",
    "link": "/blog",
    "target": "",
    "rel": ""
  },
  {
    "name": "Projects",
    "link": "/project",
    "target": "",
    "rel": ""
  },
  {
    "name": "Contact",
    "link": "/#contact",
    "target": "",
    "rel": ""
  },
  {
    "name": "Hire Me",
    "link": "mailto:[email protected]",
    "target": "",
    "rel": ""
  }
]

• name: The text displayed on the navigation bar.
• link: Internal page path (/blog, /project), in-page anchor (/#contact), or external URL.

#Updating Website Content

Twnty separates all page content into Astro Content Collections inside src/content/. You can update every section of your portfolio and resume without writing any code.

#Homepage & Resume Sections

The entire homepage—including your hero bio, achievements, services, work experience, skill bars, testimonials, pricing, FAQ, and contact form—is managed directly through frontmatter fields in src/content/_index/_index.mdx:

#Hero Banner & Profile:

banner:
  title: "Hey, I'm Twnty Watts"
  description: "A Designer based in Berlin, Germany"
  content: |
    Author of "The Art of Design" and digital product builder. Explore my recent case studies and thoughts on design systems.
  image:
    src: "/images/profile.jpg"
    alt: "Twnty Watts"
    width: 280
    height: 216

• Replace /images/profile.jpg with your photo in public/images/profile.jpg.

#Achievements & Stats:

achievements:
  title: "Achievements"
  subtitle: "Impact & Milestones"
  description: "Key numbers from my work over the last 8 years."
  stats:
    - value: "40"
      value_prefix: ""
      value_suffix: "+"
      title: "Design Awards"
    - value: "75"
      value_prefix: ""
      value_suffix: "+"
      title: "Shipped Projects"
    - value: "120"
      value_prefix: ""
      value_suffix: "%"
      title: "Average Client ROI"

#Services Offered:

services:
  title: "Services"
  subtitle: "What I do"
  service_list:
    - title: "Product Design"
      content: |
        - Design Systems
        - User Interface & Experience
        - Interactive Prototypes
    - title: "Web Development"
      content: |
        - Astro & Next.js Websites
        - TailwindCSS Styling
        - Performance Optimization

#Work Experience / Resume Timeline:

experience:
  title: "Resume"
  subtitle: "Career Experience"
  experience_list:
    - title: "Lead Product Designer"
      company: "Studio Acme"
      period: "2023 - Present"
      content: "Leading design systems and end-to-end digital product design for global clients."
    - title: "Senior UI/UX Designer"
      company: "Innovate Labs"
      period: "2021 - 2023"
      content: "Crafted intuitive web applications and mobile experiences."

#Skills & Progress Bars:

skills:
  title: "Skills"
  subtitle: "Core Capabilities"
  skill_list:
    - title: "UI/UX & Design Systems"
      percentage: 95
    - title: "Prototyping & Motion"
      percentage: 85
    - title: "Frontend (HTML/CSS/Tailwind)"
      percentage: 90

#Client Logos:

clients:
  title: "Customers"
  subtitle: "Trusted by Leading Teams"
  customer_list:
    - title: "Client 1"
      image: "/images/clients/01.svg"
    - title: "Client 2"
      image: "/images/clients/02.svg"
    - title: "Client 3"
      image: "/images/clients/03.svg"

#Client Testimonials:

testimonials:
  title: "Testimonials"
  subtitle: "What clients say about working together"
  testimonial_list:
    - name: "Sarah Mitchell"
      designation: "Head of Product, TechCorp"
      review: "Working with Twnty was an absolute pleasure. His attention to detail and ability to turn complex workflows into simple designs exceeded all expectations."

#Pricing Plans:

pricing:
  title: "Pricing"
  subtitle: "Transparent engagement models"
  pricing_list:
    - plan: "Retainer / Dedicated"
      price: "$95"
      service_duration: "/hour"
      description: "Ideal for teams needing dedicated design support on an ongoing basis."
      services:
        - "Dedicated Design Time"
        - "Weekly Progress Calls"
        - "Direct Slack Communication"
        - "Unlimited Design Revisions"

#Frequently Asked Questions (FAQ):

faq:
  title: "FAQ"
  subtitle: "Common Questions"
  faq_list:
    - question: "What is your typical project timeline?"
      answer: "Most full design projects take between 3 to 6 weeks from discovery to final delivery."
    - question: "Are you available for freelance projects?"
      answer: "Yes, I am currently taking on select freelance and contract design projects."

#Interactive macOS Fisheye Dock Navigation:

Twnty includes a signature macOS-style Dock Side Navigation (src/components/Navigation.astro) anchored along the left edge:

• Fisheye Magnification Physics: Moving your cursor up and down over the dots triggers smooth physical magnification (scaling from scale(1) up to scale(2)) using a curved influence distance algorithm (Math.pow(1 - dist/120, 2)).
• Auto-Scroll Tracking: As visitors scroll down the page, an Intersection observer continuously detects the section with maximum visibility and highlights the active dot.
• Smooth Anchor Jumps: Clicking any dot smoothly glides directly to that section (#intro, #achievements, #services, #experience, #skills, #projects, #clients, #testimonials, #pricing, #faq, #contact).
• Mobile Drawer: On smaller screens, the side dots seamlessly transform into a floating bottom-right drawer button with clean SVG icons and a backdrop-blur modal.

---

#Portfolio Case Studies

Each portfolio case study lives as its own .mdx file inside src/content/project/ (e.g. bleu.mdx, bloomscape.mdx).

#Dual Showcase Layout on Homepage:

The homepage projects section (src/components/landing/Projects.astro) dynamically showcases your work using two distinct card layouts:

1. Top Hero Feature (ProjectCard.astro): The newest project appears at the top as an expansive, full-width feature card.
2. Two-Column Grid (ProjectCardTwo.astro): Projects 2 and 3 render side-by-side below the hero card, creating an editorial showcase hierarchy.

To add a new project, create a new file in src/content/project/ (e.g. my-project.mdx):

---
draft: false
date: 2026-05-10T10:00:00+06:00
title: "Modern FinTech Mobile App"
subtitle: "Product Design & Strategy"
description: "A complete mobile banking experience built from the ground up for modern smartphone users."
image: "/images/project/01.webp"
---

## Project Overview

Briefly introduce the project, client goals, and core target audience.

## The Challenge

• Single Project Page: Every project has a dedicated page at /project/<slug> featuring your case study markdown, next/previous navigation, and a 5-platform social share bar (SocialShare.astro for X, Facebook, LinkedIn, Reddit, and Pinterest).

---

#Writing Blog Articles

To publish a new article, create a .mdx file in src/content/blog/ (e.g. my-first-article.mdx):

---
draft: false
date: 2026-06-15T10:00:00+06:00
title: "The Power of Minimalist Design"
description: "How simplifying your interface amplifies user clarity and product value."
image: "/images/blog/01.webp"
category: "Design"
tags: ["Minimalism", "UI/UX", "Productivity"]
---

Write your article here using standard Markdown syntax.

## Why Minimalism Works

Minimalism isn't about removing what you need; it's about removing what distracts you.

- Clear hierarchy
- Faster user task completion
- Timeless aesthetics

#Blog Highlights & In-Stream Newsletter:

• In-Stream Newsletter Injection: Twnty automatically inserts an interactive newsletter subscription card (src/components/Newsletter.astro) directly into the article feed after the second article on the first page, and at the end of paginated archive pages.
• Reading Time: Reading duration is automatically computed and displayed on post cards.
• Syntax Highlighting: Powered by Astro Expressive Code.
• Social Sharing: Every post includes a 5-platform social share widget (SocialShare.astro) for X, Facebook, LinkedIn, Reddit, and Pinterest.

---

#Working Contact Form

Twnty includes an integrated contact form on the homepage (/#contact) powered by FormSubmit.

To receive form submissions directly in your inbox:

1. Open src/content/_index/_index.mdx.
2. Scroll to the contact section at the bottom:

contact:
  title: "Contact"
  subtitle: "Let's work together"
  form:
    email_to: "[email protected]"
    subject: "New Inquiry from Portfolio"
    success_message: "Thank you! Your message has been sent successfully."
    error_message: "Oops! Something went wrong. Please try again."

3. Change email_to to your real email address. The first time a message is sent through the form, FormSubmit will send a one-time activation email to confirm your address.

#Changing Logos, Favicon & Media

#Favicon & Social Share Banner

• Favicon: Replace public/favicon.ico with your icon file.
• OpenGraph Share Image: Replace public/ogimage.jpg with your banner (recommended: 1200 x 630 pixels).

#Profile Photo

• Replace public/images/profile.jpg with your profile portrait.

#Client Logos

• Add or replace client logo SVGs in public/images/clients/ and update customer_list in src/content/_index/_index.mdx.

#Changing Fonts

Twnty uses Astro's built-in Font API with Google Fonts. The default font is Inter.

#How to Switch Fonts

1. Open astro.config.mjs and change the font configuration:

fonts: [{
  name: "Plus Jakarta Sans", // Choose any Google Font (e.g. Inter, Outfit, DM Sans)
  cssVariable: "--font-primary",
  provider: fontProviders.google(),
  weights: [300, 400, 500, 600, 700],
  fallbacks: ["sans-serif"]
}],

2. Astro will automatically download and optimize the font at build time with zero layout shift.

#Building for Production & Deployment

When your content is finalized and ready to launch:

#1. Build the Site

Run the build command in your terminal:

npm run build

Astro compiles an ultra-fast, fully optimized static website into the dist/ directory.

#2. Deploy

Deploy the dist/ folder directly to any static hosting service:

• Vercel (Recommended): Push your project to GitHub, connect your repository on Vercel, and click Deploy. Astro is auto-detected.
• Netlify: Connect your repository to Netlify and select the Astro build preset.
• Cloudflare Pages / GitHub Pages: Deploy the dist/ folder directly.