implement ssg config for blog posts in project ,

2026-08-16 21:14:31 +03:30 · 2025-11-10 18:09:18 +03:30
parent d2333d3db2
commit 713bb83981
37 changed files with 5505 additions and 297 deletions
@@ -0,0 +1,226 @@
+# Design Document: Layout Refactoring
+
+## Overview
+
+این طراحی یک refactoring ساده ولی مهم برای جابجایی کامپوننت‌های مشترک UI از `app.vue` به `default.vue` layout است. هدف اصلی پیروی از معماری استاندارد Nuxt و جداسازی concerns است.
+
+### Current Architecture Problems
+
+1. **Mixing Concerns**: `app.vue` هم global configuration و هم specific UI components دارد
+2. **Poor Reusability**: اگر بخواهیم صفحه‌ای بدون TopNav داشته باشیم، امکان‌پذیر نیست
+3. **Not Following Nuxt Conventions**: Nuxt layout system برای همین موارد طراحی شده ولی استفاده نمی‌شود
+
+### Proposed Solution
+
+جابجایی TopNav و FooterCopyright به `default.vue` layout و تمیز کردن `app.vue` به یک wrapper خالص.
+
+## Architecture
+
+### File Structure
+
+```
+app/
+├── app.vue                    # Global wrapper (cleaned)
+├── layouts/
+│   ├── default.vue           # Main layout with TopNav + Footer (updated)
+│   └── marketing.vue         # Preserved for future use
+├── components/
+│   └── common/
+│       ├── TopNav.vue        # No changes needed
+│       └── FooterCopyright.vue # No changes needed
+└── pages/
+    ├── index.vue             # Uses default layout automatically
+    └── blog/
+        ├── index.vue         # Uses default layout automatically
+        └── [...slug].vue     # Uses default layout automatically
+```
+
+### Component Hierarchy
+
+**Before:**
+```
+UApp (app.vue)
+├── NuxtLoadingIndicator
+├── TopNav
+├── NuxtPage
+│   └── Page Content
+└── FooterCopyright
+```
+
+**After:**
+```
+UApp (app.vue)
+├── NuxtLoadingIndicator
+└── NuxtLayout (default)
+    ├── TopNav
+    ├── NuxtPage
+    │   └── Page Content
+    └── FooterCopyright
+```
+
+## Components and Interfaces
+
+### 1. app.vue (Refactored)
+
+**Purpose**: Global application wrapper با configuration و global components
+
+**Structure**:
+```vue
+<template>
+  <UApp :toaster="{ expand: false }">
+    <NuxtLoadingIndicator />
+    <NuxtLayout>
+      <NuxtPage />
+    </NuxtLayout>
+  </UApp>
+</template>
+```
+
+**Responsibilities**:
+- Global app configuration (UApp, toaster)
+- Loading indicator
+- Head management (fonts, meta tags)
+- Language and direction attributes
+- Layout wrapper
+
+**What to Remove**:
+- TopNav component import and usage
+- FooterCopyright component import and usage
+- FloatingActions unused import
+
+### 2. layouts/default.vue (Updated)
+
+**Purpose**: Main layout برای صفحات اصلی و بلاگ
+
+**Structure**:
+```vue
+<template>
+  <div class="layout-default">
+    <TopNav />
+    <slot />
+    <FooterCopyright />
+  </div>
+</template>
+```
+
+**Responsibilities**:
+- Render TopNav
+- Provide slot for page content
+- Render FooterCopyright
+- Maintain proper spacing and structure
+
+**Styling Considerations**:
+- باید مطمئن شویم که spacing بین TopNav و content حفظ می‌شود
+- TopNav از قبل `fixed` positioning دارد، پس نیازی به تغییر نیست
+- ممکن است نیاز به `padding-top` برای content باشد تا زیر TopNav نرود
+
+### 3. TopNav.vue (No Changes)
+
+این کامپوننت تغییری نمی‌کند چون:
+- خودش `fixed positioning` دارد
+- مستقل از parent خودش کار می‌کند
+- هیچ dependency به app.vue ندارد
+
+### 4. FooterCopyright.vue (No Changes)
+
+این کامپوننت هم تغییری نمی‌کند.
+
+## Data Models
+
+هیچ data model جدیدی نیاز نیست. این یک refactoring ساختاری است.
+
+## Error Handling
+
+### Potential Issues
+
+1. **Layout Not Applied**: اگر Nuxt به درستی default layout را تشخیص ندهد
+   - **Solution**: اضافه کردن explicit layout declaration در nuxt.config.ts یا pages
+
+2. **Styling Breaks**: ممکن است spacing یا positioning مشکل پیدا کند
+   - **Solution**: بررسی دقیق visual regression و اضافه کردن padding/margin در صورت نیاز
+
+3. **Client-Side Hydration Mismatch**: اگر TopNav در layout و app.vue تفاوت داشته باشد
+   - **Solution**: حذف کامل TopNav از app.vue قبل از اضافه کردن به layout
+
+## Migration Strategy
+
+### Step-by-Step Approach
+
+1. **Update default.vue layout**
+   - Import TopNav و FooterCopyright
+   - Add components to template
+   - Test visual appearance
+
+2. **Update app.vue**
+   - Remove TopNav و FooterCopyright imports
+   - Remove components from template
+   - Add NuxtLayout wrapper
+   - Keep all head management and global config
+
+3. **Verify pages work correctly**
+   - Test homepage
+   - Test blog index
+   - Test blog post pages
+   - Check navigation between pages
+
+4. **Clean up unused code**
+   - Remove FloatingActions unused import
+   - Remove isLocaleSwitching unused variable
+
+## Testing Strategy
+
+### Manual Testing Checklist
+
+1. **Visual Regression**
+   - [ ] Homepage looks identical
+   - [ ] Blog index looks identical
+   - [ ] Blog post pages look identical
+   - [ ] TopNav positioning is correct
+   - [ ] Footer positioning is correct
+
+2. **Functionality**
+   - [ ] TopNav navigation works (hero, skills, work, projects)
+   - [ ] Blog link works
+   - [ ] Language switcher works
+   - [ ] Theme switcher works
+   - [ ] Responsive behavior works on mobile
+
+3. **Navigation**
+   - [ ] Navigate from home to blog
+   - [ ] Navigate from blog to home
+   - [ ] Navigate between blog posts
+   - [ ] TopNav and Footer persist correctly
+
+4. **Performance**
+   - [ ] No hydration errors in console
+   - [ ] No layout shift (CLS)
+   - [ ] Loading indicator works
+
+### Browser Testing
+
+- Chrome/Edge (desktop & mobile)
+- Firefox
+- Safari (if available)
+
+## Performance Considerations
+
+این refactoring نباید تأثیر منفی روی performance داشته باشد:
+
+- **Bundle Size**: تغییری نمی‌کند (فقط جابجایی کد)
+- **Rendering**: ممکن است کمی بهتر شود چون Nuxt layout caching دارد
+- **Hydration**: باید مشابه قبل باشد
+
+## Future Enhancements
+
+بعد از این refactoring، می‌توانیم:
+
+1. **Create Blog-Specific Layout**: اگر بخواهیم blog layout متفاوتی داشته باشیم
+2. **Create Clean Layout**: برای صفحاتی که نیاز به TopNav ندارند (مثل login, 404)
+3. **Add Layout Transitions**: انیمیشن بین layout های مختلف
+4. **Conditional Footer**: نمایش footer های متفاوت بر اساس صفحه
+
+## References
+
+- [Nuxt Layouts Documentation](https://nuxt.com/docs/guide/directory-structure/layouts)
+- [Nuxt app.vue Documentation](https://nuxt.com/docs/guide/directory-structure/app)
+- [Vue Slot Documentation](https://vuejs.org/guide/components/slots.html)
@@ -0,0 +1,60 @@
+# Requirements Document
+
+## Introduction
+
+این سند الزامات refactoring ساختار layout در پروژه Nuxt را مشخص می‌کند. هدف اصلی جابجایی کامپوننت‌های مشترک (TopNav و Footer) از `app.vue` به layout مناسب است تا از best practices Nuxt پیروی شود و قابلیت نگهداری و توسعه‌پذیری بهبود یابد.
+
+## Glossary
+
+- **Layout System**: سیستم مدیریت قالب‌های صفحه در Nuxt که امکان تعریف ساختارهای مشترک برای صفحات مختلف را فراهم می‌کند
+- **TopNav**: کامپوننت نوار ناوبری بالای صفحه که در تمام صفحات نمایش داده می‌شود
+- **FooterCopyright**: کامپوننت فوتر که اطلاعات کپی‌رایت را نمایش می‌دهد
+- **app.vue**: فایل اصلی اپلیکیشن Nuxt که wrapper کلی برنامه است
+- **Default Layout**: قالب پیش‌فرض که برای صفحات اصلی و بلاگ استفاده می‌شود
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** به عنوان توسعه‌دهنده، می‌خواهم ساختار layout پروژه را بر اساس best practices Nuxt سازماندهی کنم تا نگهداری و توسعه آینده آسان‌تر شود
+
+#### Acceptance Criteria
+
+1. THE Layout System SHALL move TopNav component from app.vue to default layout
+2. THE Layout System SHALL move FooterCopyright component from app.vue to default layout
+3. THE app.vue SHALL contain only global wrappers and configuration without specific UI components
+4. THE Default Layout SHALL include TopNav, page content slot, and FooterCopyright in correct order
+5. WHEN a page uses default layout, THE Layout System SHALL render TopNav and Footer automatically
+
+### Requirement 2
+
+**User Story:** به عنوان توسعه‌دهنده، می‌خواهم صفحات موجود به صورت خودکار از layout جدید استفاده کنند بدون اینکه نیاز به تغییرات دستی در هر صفحه باشد
+
+#### Acceptance Criteria
+
+1. THE Layout System SHALL set default layout as the fallback layout for all pages
+2. THE Layout System SHALL ensure homepage uses default layout without explicit declaration
+3. THE Layout System SHALL ensure blog pages use default layout without explicit declaration
+4. WHEN no layout is specified in a page, THE Layout System SHALL apply default layout automatically
+
+### Requirement 3
+
+**User Story:** به عنوان توسعه‌دهنده، می‌خواهم layout های موجود (marketing) را حفظ کنم برای استفاده‌های آینده
+
+#### Acceptance Criteria
+
+1. THE Layout System SHALL preserve existing marketing layout without modifications
+2. THE Layout System SHALL keep marketing layout available for future use
+3. THE Layout System SHALL not break any existing layout functionality
+
+### Requirement 4
+
+**User Story:** به عنوان کاربر، می‌خواهم تجربه کاربری من بعد از refactoring دقیقاً مانند قبل باشد
+
+#### Acceptance Criteria
+
+1. THE Layout System SHALL maintain identical visual appearance after refactoring
+2. THE Layout System SHALL preserve all navigation functionality
+3. THE Layout System SHALL maintain all responsive behaviors
+4. THE Layout System SHALL keep all animations and transitions working
+5. WHEN user navigates between pages, THE Layout System SHALL display TopNav and Footer consistently
@@ -0,0 +1,40 @@
+# Implementation Plan
+
+- [x] 1. Update default.vue layout with TopNav and Footer
+
+
+  - Import TopNav and FooterCopyright components
+  - Add TopNav before the slot
+  - Add FooterCopyright after the slot
+  - Add appropriate wrapper div with proper spacing
+  - _Requirements: 1.1, 1.4_
+
+
+
+- [x] 2. Refactor app.vue to use layout system
+
+
+  - Remove TopNav component import and usage
+  - Remove FooterCopyright component import and usage
+  - Remove unused FloatingActions import
+  - Remove unused isLocaleSwitching variable
+  - Wrap NuxtPage with NuxtLayout component
+  - Keep all head management and global configuration
+
+
+
+  - _Requirements: 1.1, 1.2, 1.3_
+
+
+- [x] 3. Verify visual appearance and functionality
+
+
+  - Check homepage renders correctly with TopNav and Footer
+  - Check blog index page renders correctly
+  - Check blog post pages render correctly
+  - Verify TopNav navigation works (hero, skills, work, projects, blog)
+  - Verify language switcher functionality
+  - Verify theme switcher functionality
+  - Check responsive behavior on different screen sizes
+  - Verify no console errors or hydration warnings
+  - _Requirements: 2.1, 2.2, 2.3, 4.1, 4.2, 4.3, 4.4, 4.5_