Technical Documentation

This document provides detailed technical information about the website structure, customization options, and development workflow.

🏗️ Architecture Overview

Technology Stack

• Framework: Quarto (v1.4+)
• Styling: Custom CSS with Bootstrap integration
• Icons: Font Awesome 6.0 + Academicons
• Deployment: Netlify with continuous deployment
• Version Control: Git with GitHub

Project Structure

quarto-website/
├── _quarto.yml              # Main Quarto configuration
├── _publish.yml             # Publishing and deployment settings
├── home.qmd                 # Homepage (outputs docs/index.html)
├── cv.qmd                   # CV page
├── about/                   # About section
│   └── about.qmd
├── portfolio/               # Portfolio showcase
│   └── portfolio.qmd
├── publications/            # Research publications
│   ├── publications.qmd     # Listing page (outputs index.html)
│   ├── peer-reviewed/
│   ├── preprints/
│   └── publication[1-8]/    # e.g. article.qmd → index.html per folder
├── projects/                # Case studies and projects
│   ├── dual-task-case-study.qmd
│   ├── memory-and-meditation.qmd
│   └── surgeon-performance-predict.qmd
├── research/                # Research overview
│   └── research.qmd
├── skills/                  # Skills and methodology
│   └── skills.qmd
├── assets/                  # Static assets
│   ├── css/
│   │   ├── main.css         # Main stylesheet
│   │   ├── index.css        # Homepage styles
│   │   ├── publications.css # Publication-specific styles
│   │   └── skills.css       # Skills page styles
│   └── listing-default.css  # Default listing styles
├── images/                  # Images and media files
├── CV/                      # CV and resume files
├── _extensions/             # Quarto extensions
│   └── mcanouil/iconify/    # Iconify extension
└── supporting_docs/         # Supporting documents

⚙️ Configuration Files

_quarto.yml

Main configuration file controlling:

• Site metadata: Title, description, URL
• Navigation: Menu structure and links
• Theme: Visual appearance and styling
• Features: Search, social links, footer
• Execution: Code execution settings

Key sections:

website:
  title: "Mohammad Dastgheib"
  site-url: https://mdastgheib.com
  description: "Vision science researcher..."
  navbar: # Navigation menu
  page-footer: # Footer content and social links

format:
  html:
    theme:
      light: cosmo
    css: 
      - assets/css/main.css
    include-in-header: # External CSS and JS

_publish.yml

Deployment configuration for Netlify:

- source: project
  netlify:
    - id: 676bfb81-9a40-4de6-990b-6fcd2ae00e10
      url: https://mdastgheib.com

🎨 Styling and Theming

CSS Architecture

Main Stylesheet (assets/css/main.css)

• Global styles and variables
• Typography and layout
• Component-specific styles
• Responsive design rules

Component Stylesheets

• index.css: Homepage-specific styling
• publications.css: Publication listing styles
• skills.css: Skills page layout

Color Scheme

• Primary: #e63946 (Red)
• Secondary: Bootstrap default colors
• Background: White/light gray
• Text: Dark gray/black

Custom Styling

CSS Variables

:root {
  --primary-color: #e63946;
  --secondary-color: #f1faee;
  --text-color: #1d3557;
  --background-color: #ffffff;
}

Responsive Design

• Mobile-first approach
• Bootstrap grid system
• Custom breakpoints for academic content
• Optimized for tablets and mobile devices

📱 Responsive Design

Breakpoints

• Mobile: < 768px
• Tablet: 768px - 1024px
• Desktop: > 1024px

Mobile Optimizations

• Touch-friendly navigation
• Optimized image sizes
• Readable typography
• Simplified layouts

🔧 Development Workflow

Local Development

1. Setup

   git clone https://github.com/mohdasti/quarto-website.git
   cd quarto-website
   npm install  # Optional: for package.json dependencies

2. Development Server

   quarto preview --watch
   # or
   npm run dev

3. Build for Production

   quarto render
   # or
   npm run build

File Organization

Content Files (.qmd)

• Use YAML front matter for metadata
• Markdown for content structure
• Quarto-specific features for interactivity

Asset Management

• Images in images/ directory
• CSS in assets/css/
• Organized by functionality

Version Control

Git Workflow

1. Feature branches for new content
2. Pull requests for review
3. Main branch for production
4. Automatic deployment via Netlify

Commit Conventions

• Add: for new content
• Update: for content changes
• Fix: for bug fixes
• Style: for styling changes

🚀 Deployment

Netlify Configuration

Build Settings

• Build Command: quarto render
• Publish Directory: _site
• Node Version: 18.x

Environment Variables

• No sensitive data required
• Public repository deployment

Custom Domain

• mdastgheib.com configured
• SSL certificate automatic
• Redirects from www to non-www

Build Process

1. Trigger: Push to main branch
2. Build: Quarto renders site
3. Deploy: Netlify publishes to CDN
4. Cache: Automatic caching for performance

📊 Performance Optimization

Image Optimization

• WebP format where supported
• Responsive image sizing
• Lazy loading for large images
• Alt text for accessibility

CSS Optimization

• Minified CSS in production
• Critical CSS inlining
• Unused CSS removal
• Font loading optimization

JavaScript Optimization

• Minimal JavaScript usage
• Async loading where possible
• No external dependencies for core functionality

🔍 SEO and Accessibility

SEO Features

• Meta tags and descriptions
• Open Graph tags
• Twitter Card support
• Structured data markup
• XML sitemap generation

Accessibility Features

• Semantic HTML structure
• Alt text for images
• Keyboard navigation support
• Screen reader compatibility
• Color contrast compliance

🛠️ Customization Guide

Adding New Pages

1. Create .qmd file

   ---
   title: "Page Title"
   ---
   
   # Page Content

2. Update navigation in _quarto.yml

   navbar:
     right:
       - text: "New Page"
         href: new-page.qmd

Adding New Projects

1. Create project file in projects/
2. Use consistent front matter
3. Add to portfolio if needed
4. Update navigation if required

Styling Changes

1. Global styles: Edit assets/css/main.css
2. Page-specific: Create new CSS file
3. Include in config: Add to _quarto.yml

Content Updates

1. Publications: Add to publications/
2. About: Update about/about.qmd
3. Skills: Modify skills/skills.qmd
4. CV: Update cv.qmd and PDF files

🐛 Troubleshooting

Common Issues

Build Errors

• Check Quarto version compatibility
• Verify YAML syntax
• Check file paths and references

Styling Issues

• Clear browser cache
• Check CSS file paths
• Verify Bootstrap integration

Deployment Issues

• Check Netlify build logs
• Verify build command
• Check file permissions

Debug Tools

Local Debugging

quarto check  # Check configuration
quarto render --debug  # Verbose output

Browser Tools

• Developer tools for CSS debugging
• Network tab for asset loading
• Console for JavaScript errors

📚 Resources

Documentation

• Quarto Documentation
• Bootstrap Documentation
• Font Awesome Icons

Tools

• Quarto CLI
• Netlify CLI
• Git

Best Practices

• Semantic HTML structure
• Mobile-first responsive design
• Performance optimization
• Accessibility compliance
• SEO best practices

---

For questions or issues, please refer to the Contributing Guidelines or open an issue on GitHub.