Implement custom category section layouts and reusable component for filtering posts by category/tag

Author: sineeli

CUSTOM-MODIFICATIONS.md

@@ -0,0 +1,251 @@
+# Custom Theme Modifications Summary
+
+This document outlines all custom modifications made to the Icarus theme.
+
+## Overview
+Your theme uses the built-in Icarus configuration system effectively, with minimal custom code modifications focused on improving the post reading experience.
+
+---
+
+## Custom Modifications
+
+### 1. Post Page Layout (✅ Custom Code)
+**Files Modified:**
+- `themes/icarus/layout/layout.jsx`
+- `themes/icarus/layout/common/widgets.jsx`
+
+**Changes:**
+- **Left Sidebar**: Shows only TOC widget on post pages
+- **Right Sidebar**: Hidden on post pages  
+- **Main Content**: Expanded to 75% width (9/12 columns) on widescreen
+- **Left Sidebar Width**: Reduced to 25% (3/12 columns) on post pages
+
+**Why Custom Code Needed:**
+Icarus doesn't provide built-in config to hide specific widgets per layout type, so custom logic was added.
+
+**Code Location:**
+```javascript
+// themes/icarus/layout/layout.jsx
+if (page.layout === 'post' && columnCount === 3) {
+    columnCount = 2;
+    isPostWithLeftSidebar = true;
+}
+
+// themes/icarus/layout/common/widgets.jsx
+if (page.layout === 'post' && position === 'right') {
+    return null;  // Hide right sidebar
+}
+const filteredWidgets = page.layout === 'post' && position === 'left'
+    ? widgets.filter(widget => widget.type === 'toc')  // Only TOC
+    : widgets;
+```
+
+---
+
+### 2. Category Section Layouts (✅ Custom Code)
+**Files Created:**
+- `themes/icarus/layout/common/category-posts.jsx` (reusable component)
+- `themes/icarus/layout/blogs.jsx`
+- `themes/icarus/layout/photography.jsx`
+- `themes/icarus/layout/life.jsx`
+
+**Purpose:**
+Create custom landing pages that filter and display posts by category/tag.
+
+**Why Custom Code Needed:**
+The built-in `category.jsx` layout requires Hexo's category system integration. Custom layouts give more flexibility for creating section landing pages independent of Hexo's category hierarchy.
+
+**Usage:**
+- `/blogs/` page uses `blogs.jsx` to show all posts with "blogs" category/tag
+- `/photography/` page uses `photography.jsx` for "photography" posts
+- `/life/` page uses `life.jsx` for "life" posts
+
+---
+
+### 3. Category Layout Fix (✅ Custom Code)
+**File Modified:**
+- `themes/icarus/layout/category.jsx`
+
+**Change:**
+Added null check for `page.parents` to prevent errors:
+```javascript
+{page.parents && page.parents.map(category => {
+    return <li><a href={url_for(category.path)}>{category.name}</a></li>;
+})}
+```
+
+**Why Needed:**
+The original theme assumed all category pages have a `parents` array, which caused crashes for top-level categories.
+
+---
+
+## Configurations Using Built-in Features (✅ No Custom Code)
+
+All of these are configured via `_config.icarus.yml` without custom code:
+
+### 1. Sticky Left Sidebar
+```yaml
+sidebar:
+  left:
+    sticky: true  # TOC follows scroll
+  right:
+    sticky: false
+```
+
+### 2. TOC Widget Settings
+```yaml
+widgets:
+  -
+    position: left
+    type: toc
+    index: true
+    collapsed: true
+    depth: 3
+```
+
+### 3. Code Highlighting
+```yaml
+article:
+  highlight:
+    theme: atom-one-light
+    clipboard: true
+    fold: unfolded
+```
+
+### 4. Read Time & Update Time
+```yaml
+article:
+  readtime: true
+  update_time: true
+```
+
+### 5. Navigation & Footer
+```yaml
+navbar:
+  menu:
+    Home: /
+    Archives: /archives
+    Blogs: /blogs
+    Photography: /photography
+    Categories: /categories
+    Tags: /tags
+  dark_mode_toggle: true
+```
+
+### 6. Profile Widget
+```yaml
+widgets:
+  -
+    position: left
+    type: profile
+    author: Siva Sravana Kumar Neeli
+    author_title: Sr. ML Engineer
+    location: Dallas, TX
+    avatar: /img/profile_pic.png
+    # ... social links
+```
+
+---
+
+## Configuration Strategy Analysis
+
+### ✅ What's Done Right
+
+1. **Using Built-in Features First**
+   - Most settings use Icarus's configuration system
+   - No redundant custom code for features that exist
+
+2. **Sticky Sidebar**
+   - ✅ Using `sidebar.left.sticky: true` (built-in)
+   - ❌ NOT implemented via custom CSS
+
+3. **TOC Configuration**
+   - ✅ Using widget configuration (built-in)
+   - ❌ NOT hardcoded
+
+4. **Per-Post Overrides**
+   - Can override any config in post front matter
+   - No need for separate config files
+
+### 🔧 Custom Code is Justified
+
+1. **Post Layout Changes**
+   - Icarus doesn't support per-layout widget filtering
+   - Custom code is necessary
+
+2. **Category Section Pages**
+   - More flexible than built-in category system
+   - Allows custom landing pages
+   - Justified customization
+
+3. **Category Layout Fix**
+   - Bug fix for missing null check
+   - Should be contributed back to Icarus theme
+
+---
+
+## Recommended Actions
+
+### Keep As-Is ✅
+- Custom post layout modifications (improves UX)
+- Category section layouts (adds flexibility)
+- Category layout fix (fixes bug)
+- All built-in configurations
+
+### Consider Creating `_config.post.yml` (Optional)
+If you want ALL posts to have specific settings without front matter:
+
+```yaml
+# _config.post.yml
+toc: true
+article:
+  highlight:
+    theme: atom-one-dark
+```
+
+This would apply to all posts by default, but can still be overridden in individual post front matter.
+
+### Not Needed ❌
+- Custom CSS for sticky sidebar (built-in works)
+- Custom TOC implementation (widget system works)
+- Separate layout files for categories (unless you want custom styling)
+
+---
+
+## File Structure Summary
+
+```
+├── _config.icarus.yml              # Main theme config (✅ Uses built-in features)
+├── themes/icarus/layout/
+│   ├── layout.jsx                  # Modified: Post layout width (✅ Custom)
+│   ├── category.jsx                # Modified: Null check fix (✅ Custom)
+│   ├── blogs.jsx                   # Created: Custom section (✅ Custom)
+│   ├── photography.jsx             # Created: Custom section (✅ Custom)
+│   ├── life.jsx                    # Created: Custom section (✅ Custom)
+│   └── common/
+│       ├── widgets.jsx             # Modified: Post widget filtering (✅ Custom)
+│       └── category-posts.jsx      # Created: Reusable component (✅ Custom)
+└── source/
+    ├── blogs/index.md              # Uses blogs.jsx layout
+    ├── photography/index.md        # Uses photography.jsx layout
+    └── life/index.md               # Uses life.jsx layout
+```
+
+---
+
+## Conclusion
+
+Your theme configuration is **well-optimized**:
+
+1. ✅ Uses built-in features wherever possible
+2. ✅ Custom code is minimal and justified
+3. ✅ No redundant implementations
+4. ✅ Follows Icarus configuration patterns
+5. ✅ Easy to maintain and extend
+
+**No changes needed** - your current setup is clean and efficient!
+
+---
+
+**Date**: November 8, 2025
+**Theme Version**: Icarus 5.1.0