Documentation for Obicol

#Introduction

Obicol is a world-class agency and portfolio Astro template designed for creative studios, digital agencies, design freelancers, and product teams. Built with Astro v7 and TailwindCSS v4, Obicol features:

• Interactive Sticky Stacking Service Cards: As visitors scroll down the services section, cards dynamically pin to the top and stack smoothly over one another with layered depth.
• Interactive Video Showreel Modal: Hero section showreel with an interactive play button that opens a full video player modal.
• Top Scroll Progress Indicator: A sleek progress bar at the very top of the browser that tracks reading and scroll depth.
• Animated Number Counters: Numerical stats that dynamically count up when scrolled into view.
• Dual Blog Layouts: Full-featured agency journal available in both /blog (masonry grid) and /blog-horizontal (editorial horizontal timeline).
• Careers & Job Board System: Dedicated /job/[slug] careers section for studio openings, department filtering, and vacancy details.
• Interactive Swiper Carousels: Touch-enabled sliders for portfolio case studies, client reviews, and studio team members.

#File Structure

The theme files are structured as follows:

 ./theme-files
│
├── public
│  │
│  ├── images
│  │  │
│  │  ├── favicon.png
│  │  │
│  │  └── ogimage.png
│  │
│  └── robots.txt
│
├── src
│  │
│  ├── assets
│  │  │
│  │  ├── images
│  │  │
│  │  └── videos
│  │
│  ├── components
│  │  │
│  │  ├── helper
│  │  │  │
│  │  │  ├── AstroImage.astro
│  │  │  │
│  │  │  ├── AstroVideo.astro
│  │  │  │
│  │  │  └── DeviceSizeIndicator.astro
│  │  │
│  │  ├── menu
│  │  │  │
│  │  │  └── DropdownNav.tsx
│  │  │
│  │  ├── ui
│  │  │  │
│  │  │  └── GradualBlur.tsx
│  │  │
│  │  ├── BannerShape.astro
│  │  │
│  │  ├── BlogCard.astro
│  │  │
│  │  ├── Clients.astro
│  │  │
│  │  ├── CounterUp.tsx
│  │  │
│  │  ├── Facts.astro
│  │  │
│  │  ├── Faq.astro
│  │  │
│  │  ├── PageHeader.astro
│  │  │
│  │  ├── PortfolioCard.astro
│  │  │
│  │  ├── PortfolioCarousel.astro
│  │  │
│  │  ├── ReviewCarousel.astro
│  │  │
│  │  ├── ScrollProgress.astro
│  │  │
│  │  ├── Showreel.astro
│  │  │
│  │  ├── StackedServices.astro
│  │  │
│  │  ├── TeamGroupCarousel.astro
│  │  │
│  │  └── WorkProcess.astro
│  │
│  ├── config
│  │
│  ├── content
│  │
│  ├── layouts
│  │
│  ├── pages
│  │
│  ├── styles
│  │
│  └── content.config.ts
│
├── .gitignore
│
├── astro.config.mjs
│
├── package.json
│
└── tsconfig.json

#Quick Start & Installation

Getting your agency website running locally takes less than two minutes.

#System Requirements

• Node.js - v20.0.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 your agency website running live with instant hot-reloading as you edit files!

#Global Site Settings

All global settings—including your site URL, studio branding, SEO metadata, contact form email, and footer contact details—are managed in one central file: src/config/site.config.json.

{
  "baseURL": "https://yourstudio.com",
  "trailingSlash": false,
  "favicon": "/images/favicon.png",
  "logo": {
    "src": "/images/logo.svg",
    "alt": "Obicol Studio",
    "width": 110,
    "height": 29
  },
  "seo": {
    "title": "Obicol - Agency & Portfolio Template",
    "description": "Obicol is a world-class creative studio. We design & build digital products that make an impact.",
    "keywords": "agency, portfolio, creative studio, design, branding, astro template",
    "author": "Your Studio Name",
    "image": "/images/ogimage.png"
  },
  "author": {
    "name": "Your Studio",
    "url": "https://yourstudio.com"
  },
  "contact_form": {
    "email": "[email protected]"
  },
  "footer": {
    "cta": {
      "title": "Have an idea, tell us about it!",
      "url": "/contact",
      "label": "Contact Us"
    },
    "email": "[email protected]",
    "phone": "+1 555 0123",
    "address_line_1": "123 Creative Street, Suite 400",
    "address_line_2": "San Francisco, CA 94103, USA"
  }
}

#Field Breakdown:

• baseURL: Your live domain name (used for canonical URLs and sitemaps).
• logo: Path to your studio logo, its accessible alt text, and dimensions.
• seo:
  • title: The title shown in browser tabs and Google search results.
  • description: The short summary shown in search results and social shares.
  • image: The preview banner displayed when sharing your link on Twitter/X, LinkedIn, or Facebook.
• contact_form.email: The recipient email address for inquiries submitted through the contact page.
• footer:
  • cta: The call-to-action banner displayed at the bottom of pages before the footer.
  • email, phone, address_line_1, address_line_2: Studio contact details displayed in the footer.

#Navigation & Menus

You can customize the main header navigation and the three-column footer menu in src/config/menu.json.

{
  "main": [
    { "name": "Home", "url": "/" },
    { "name": "About", "url": "/about" },
    {
      "name": "Portfolio",
      "url": "#",
      "children": [
        { "name": "All Projects", "url": "/portfolio" },
        { "name": "Featured Project", "url": "/portfolio/spearmint" }
      ]
    },
    {
      "name": "Blog",
      "url": "#",
      "children": [
        { "name": "Blog Grid", "url": "/blog" },
        { "name": "Blog Horizontal", "url": "/blog-horizontal" }
      ]
    },
    { "name": "Contact", "url": "/contact" }
  ],
  "footer": {
    "col1": [
      { "name": "About Us", "url": "/about" },
      { "name": "Services", "url": "/services" },
      { "name": "Portfolio", "url": "/portfolio" },
      { "name": "Our Blog", "url": "/blog" }
    ],
    "col2": [
      { "name": "Our Team", "url": "/team" },
      { "name": "Pricing Plans", "url": "/pricing" },
      { "name": "FAQ", "url": "/faq" }
    ],
    "col3": [
      { "name": "Contact Us", "url": "/contact" },
      { "name": "Privacy Policy", "url": "/privacy" },
      { "name": "Style Guide", "url": "/style-guide" }
    ]
  }
}

• Top-Level Links: Add objects with "name" and "url".
• Dropdown Menus: Add a "children" array containing sub-items.
• Footer Columns: Edit "col1", "col2", and "col3" to organize your footer links.

#Social Media Links

To update your social profiles, edit src/config/social.json:

[
  { "name": "Twitter", "url": "https://x.com/yourhandle" },
  { "name": "Instagram", "url": "https://instagram.com/yourhandle" },
  { "name": "LinkedIn", "url": "https://linkedin.com/company/yourstudio" },
  { "name": "Facebook", "url": "https://facebook.com/yourstudio" }
]

#Updating Website Content

Obicol organizes all page content, case studies, and blog posts inside src/content/. You can edit text and data using simple Markdown or JSON files without touching layout code.

#Homepage Content

The entire homepage is controlled through frontmatter fields in src/content/homepage/index.mdx:

#Hero Banner & Video Showreel:

banner:
  subtitle: "We Are Obicol"
  title: "We build brands, relations & trust"
  lead: "We design & build world-class digital products that make an impact and connect people."
  primary_cta: { label: "Case Studies", href: "/portfolio" }
  secondary_cta: { label: "About Us", href: "/about" }
  image: "videos/poster.png"
  video: "videos/showreel.webm"

• Replace image and video with your own studio showreel and poster stored in src/assets/videos/.

#Social Proof Avatars:

  social_proof:
    label: "Loved by 550+ Founders"
    avatars:
      - image: images/testimonials/01.png
        name: "David Okafor"
        role: "Head of Product @Pylon"
        social: { icon: "hugeicons:linkedin-02", url: "https://www.linkedin.com/" }

#Intro / About Section:

intro:
  section_title: "About Us"
  title: "About Obicol®"
  description: "Obicol is a world-class creative studio..."
  info:
    - Shaping the Future
    - Driving Meaningful Impact
    - Sculpting Digital Masterpieces

#4-Step Work Process:

process:
  subtitle: "Here is the"
  title: "Work Process"
  steps:
    - { heading: "Analysis", text: "We analyze your business and search for an idea" }
    - { heading: "Planning", text: "We plan the strategy and tactics based on the idea" }
    - { heading: "Development", text: "Now we start working on developing that idea" }
    - { heading: "Release", text: "And now your product is ready for release" }

#Testimonials Summary & Ratings:

testimonials:
  subtitle: "Testimonials"
  title: "Why teams trust us"
  total_rating: "4.9"
  total_reviews: "230+ Reviews"

---

#Portfolio & Case Studies

Each project has its own .mdx file inside src/content/portfolio/ (e.g. spearmint.mdx, caramel.mdx).

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

---
title: "Spearmint Branding & Web App"
subtitle: "Digital Product Design"
client: "Spearmint Inc"
service: "Product Design"
date: 2026-05-12T00:00:00.000Z
featured_image: "images/portfolio/carousel/01.jpg"
gallery:
  - "images/portfolio/masonry/01.jpg"
  - "images/portfolio/masonry/02.jpg"
  - "images/portfolio/masonry/03.jpg"
deliverables:
  - "Brand Identity & Strategy"
  - "UI/UX Design System"
  - "Full-Stack Development"
url: "https://spearmint.example.com"
---

## Project Overview

Write your case study introduction here. Explain what the client needed and the challenges they faced.

## The Challenge

Describe the problem you solved with your creative solution.

## The Solution & Outcome

Detail the final deliverable and the metrics/results achieved.

• Your new case study will automatically appear on the /portfolio page, in the homepage portfolio carousel, and on its own single page at /portfolio/my-project.

---

#Publishing Blog Posts

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

---
title: "Minimal UI Design: Less Clutter, More Impact"
description: "How minimalist design principles create stronger user engagement and memorable digital experiences."
date: 2026-06-20T00:00:00.000Z
image: "images/blogs/01.jpg"
author: "Alex Morgan"
category: "Design"
tags: ["UI/UX", "Minimalism", "Trends"]
---

Write your article here using standard Markdown syntax. You can include images, headings, lists, quotes, and code blocks.

• The post will automatically render on both /blog (grid layout) and /blog-horizontal (list layout), as well as on its dedicated post page.

---

#Services & Stacking Cards

Obicol features a signature Sticky Stacking Cards effect (src/components/StackedServices.astro):

• As visitors scroll down the services section, each service card pins to the top of the viewport with a sticky offset and smoothly stacks over the preceding card, creating an impressive depth and layering interaction.
• To customize the services and stacked offerings, open src/content/services/index.mdx. You can update service titles, bullet points, icon illustrations, and descriptions.

---

#Job Openings & Careers

To post a new job vacancy, create a .mdx file in src/content/jobs/ (e.g. senior-product-designer.mdx):

---
title: "Senior Product Designer"
department: "Design"
location: "Remote / San Francisco"
type: "Full-time"
salary: "$130,000 - $160,000"
date: 2026-06-01T00:00:00.000Z
---

### About the Role
Write an overview of the position...

### Responsibilities
- Lead design from concept to delivery
- Collaborate with engineering and product teams

### Requirements
- 5+ years of experience in digital product design
- Strong portfolio demonstrating end-to-end design thinking

---

#Team Members, Testimonials & Client Logos

Static structured data files live in src/content/data/:

• testimonials.json: Client reviews with client name, company, avatar, rating, and feedback text.
• team.json: Team members with name, designation, photo, and social links.
• clients.json & clients-dark.json: Client brand logos displayed in the logo marquee slider.

#Contact Form

Obicol comes with a pre-styled contact form on /contact (src/pages/contact.astro).

#Setting the Form Recipient Email

1. Open src/config/site.config.json.
2. Update the contact_form.email field with your studio email:

"contact_form": {
  "email": "[email protected]"
}

#Connecting to a Form Service

You can connect the form to free form endpoints such as Formspree, Web3Forms, or Formkeep by setting the form's action attribute in src/pages/contact.astro:

<form action="https://formspree.io/f/YOUR_FORM_ID" method="POST">

#Changing Logos, Favicon & Media

#Favicon & Social Share Image

• Favicon: Replace public/images/favicon.png with your own square icon (PNG format, 32x32 or 64x64 pixels).
• Social Media Banner (Open Graph): Replace public/images/ogimage.png with your studio preview image (recommended: 1200 x 630 pixels).

#Studio Logo

• Logo file: public/images/logo.svg (or src/assets/images/logo.svg).
• Replace with your SVG or PNG logo, and update the logo.width and logo.height in src/config/site.config.json.

#Video Showreel

• Replace src/assets/videos/showreel.webm and its poster preview src/assets/videos/poster.png with your own video reel.

#Changing Fonts

Obicol uses Astro's built-in Font API with Google Fonts. The default font is Space Grotesk.

#How to Switch Fonts

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

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

2. Astro will automatically fetch and optimize the font at build time. No manual font downloading or extra CSS imports required!

#Building for Production & Deployment

When your content is finalized and ready to launch:

#1. Build the Production Site

Run the build command:

npm run build

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

#2. Deploy

Deploy to your favorite hosting platform:

• Vercel (Recommended): Push your project to GitHub, connect the 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/ directory directly.