Vijay Chandra Atheli's

Perspectives on Business & Technology

Developer Guide - Vijay’s Journal

Developer Guide - Vijay’s Journal

Technical documentation for vijaychandraatheli.com

Table of Contents

  1. Architecture Overview
  2. Technology Stack
  3. Repository Structure
  4. File Purposes
  5. Design System
  6. Build & Deployment
  7. Custom Features
  8. Troubleshooting

Architecture Overview

Platform

  • Static Site Generator: Jekyll 4.3.0
  • Hosting: GitHub Pages (free)
  • Domain: vijaychandraatheli.com (via Squarespace Domains)
  • Deployment: Automatic on git push to master branch

Design Philosophy

  • Modern magazine-style editorial layout
  • Mobile-first responsive design
  • Ultra-compact spacing for minimal scrolling
  • Clean typography with Crimson Pro (serif) + Work Sans (sans-serif)
  • Dark mode support with localStorage persistence

Content Management

  • Write articles in Markdown (.md files)
  • Version controlled via Git
  • No database required
  • Automatic URL generation based on categories

Technology Stack

Core Technologies

Jekyll: 4.3.0          # Static site generator
Ruby: 3.0+             # Required for Jekyll (server-side only)
Markdown: Kramdown     # Content formatting
HTML5: Semantic markup
CSS3: Modern features (Grid, Flexbox, Custom Properties)
JavaScript: Vanilla ES6 (no frameworks)

Jekyll Plugins

jekyll-feed       # RSS feed generation
jekyll-seo-tag    # Meta tags for SEO
jekyll-sitemap    # XML sitemap for search engines

Fonts (Google Fonts)

Crimson Pro: Body text, tagline (serif)
Work Sans: Headers, navigation, UI (sans-serif)

Repository Structure

vijaychandraatheli.com/
│
├── _config.yml              # Jekyll site configuration
├── Gemfile                  # Ruby dependencies
├── CNAME                    # Custom domain configuration
├── README.md                # Basic repository info
├── DEVELOPER_GUIDE.md       # This file
├── ADMIN_GUIDE.md           # Content publishing guide
│
├── _layouts/                # HTML templates
│   ├── default.html         # Base wrapper (header + footer)
│   ├── home.html            # Homepage layout
│   ├── post.html            # Single article layout
│   └── page.html            # Static pages layout
│
├── _includes/               # Reusable components
│   ├── header.html          # Site header (centered, sticky)
│   ├── footer.html          # Site footer
│   └── article-card.html    # Grid card component
│
├── _posts/                  # 📝 YOUR ARTICLES GO HERE
│   ├── 2025-12-28-welcome-to-my-journal.md
│   ├── 2025-12-29-article-title.md
│   └── YYYY-MM-DD-article-slug.md
│
├── assets/
│   ├── css/
│   │   └── main.css         # Complete site styling (~800 lines)
│   └── js/
│       └── theme.js         # Dark mode + sticky header logic
│
├── images/
│   ├── posts/               # Article images
│   │   └── YYYY-MM-DD-article-name/
│   │       ├── hero.jpg     # Featured image
│   │       └── diagram.png  # Inline images
│   └── about/
│       └── profile.jpg      # About page photo
│
└── pages/
    ├── about.md             # About page
    ├── journal.md           # All articles grid
    ├── analytics-bi.md      # Category: Analytics & BI
    ├── data-strategy.md     # Category: Data Strategy
    ├── salesforce.md        # Category: Salesforce
    └── consulting-insights.md # Category: Consulting Insights

File Purposes

Configuration Files

_config.yml

Purpose: Jekyll site configuration
You Edit: When changing featured posts, navigation, site metadata
Contains:

  • Site title, tagline, description
  • Author information (name, email, social links)
  • Navigation menu structure
  • Category definitions
  • Featured posts list
  • Permalink structure
  • Plugin configuration

Example settings you might change:

featured_posts:
  - "2025-12-28-welcome-to-my-journal"
  - "2026-01-15-your-new-featured-article"

Gemfile

Purpose: Ruby dependencies for Jekyll
You Edit: Rarely (only when updating Jekyll or adding plugins)
Contains: Jekyll version, plugins list

CNAME

Purpose: Custom domain configuration for GitHub Pages
You Edit: Never (unless changing domain)
Contains: Single line: vijaychandraatheli.com

Layout Files (_layouts/)

default.html

Purpose: Master template that wraps all pages
You Edit: Never (unless adding site-wide features)
Contains:

  • <head> with meta tags, fonts, CSS links
  • Ambient gradient background
  • Dark mode toggle button
  • Header include
  • Main content placeholder (`<div class="container">

    Admin Guide - Publishing to Vijay’s Journal

    Admin Guide - Publishing to Vijay’s Journal

Your complete guide to writing and publishing articles

Quick Start - Publishing a New Article

5-Minute Workflow

# 1. Create new file in _posts folder
# Filename format: YYYY-MM-DD-article-title.md
touch _posts/2026-01-15-my-article-title.md

# 2. Open in your editor, add front matter + content

# 3. Commit and push
git add .
git commit -m "New article: My Article Title"
git push origin master

# 4. Wait 1-2 minutes
# 5. Article is live!

Table of Contents

  1. Creating a New Article
  2. Front Matter Guide
  3. Markdown Syntax
  4. Adding Images
  5. Formatting Tips
  6. Categories & Tags
  7. Publishing Checklist
  8. Updating Existing Articles

Creating a New Article

Step 1: Create the File

Naming convention: YYYY-MM-DD-article-slug.md

Examples:

2026-01-15-salesforce-integration-best-practices.md
2026-02-03-real-time-analytics-frameworks.md
2026-03-20-data-governance-strategies.md

Rules:

  • ✅ Start with date: YYYY-MM-DD-
  • ✅ Lowercase only
  • ✅ Use hyphens (not spaces or underscores)
  • ✅ Keep slug short but descriptive
  • ✅ File extension: .md

Where: _posts/ folder in your repository

Step 2: Add Front Matter

Every article starts with front matter (metadata between --- lines):

---
layout: post
title: "Your Article Title Here"
date: 2026-01-15
category: analytics-bi
tags: [business intelligence, analytics, real-time data]
excerpt: "A brief 1-2 sentence description of what this article covers."
image: /images/posts/2026-01-15-article-slug/hero.jpg
---

Required fields:

  • layout: Always post
  • title: Article title (use quotes if contains colons)
  • date: Publication date (YYYY-MM-DD)
  • category: One of: analytics-bi, data-strategy, salesforce, consulting-insights

Optional fields:

  • tags: Array of topics (for cross-referencing)
  • excerpt: Short description (shows in cards on hover, SEO meta)
  • image: Featured image path (shows in grid cards)

Step 3: Write Your Content

After the closing ---, write your article in Markdown:

---
layout: post
title: "The Future of Real-Time Analytics"
date: 2026-01-15
category: analytics-bi
tags: [real-time data, streaming, business intelligence]
excerpt: "How modern organizations leverage streaming architectures for instant insights."
---

## Introduction

Your first paragraph here...

## Main Section

More content...

### Subsection

Details...

Front Matter Guide

Required Fields Explained

layout: post

Purpose: Tells Jekyll which template to use
Value: Always post for articles
Don’t change this

title: "Article Title"

Purpose: Article headline
Format: Use quotes, especially if title contains : or #
Tips:

  • Keep under 60 characters (better for SEO)
  • Use title case: “The Future of Real-Time Analytics”
  • Be specific and descriptive
  • Avoid clickbait

Examples:

title: "Building Scalable Data Pipelines with Apache Kafka"
title: "5 Salesforce Integration Patterns Every Architect Should Know"
title: "Why Data Governance Fails: Lessons from 10 Client Engagements"

date: YYYY-MM-DD

Purpose: Publication date (affects URL and sorting)
Format: Must be YYYY-MM-DD exactly
Behavior: Jekyll won’t show future-dated posts

Examples:

date: 2026-01-15
date: 2025-12-28

Note: You can schedule posts by using future dates. They’ll appear automatically on that date.

category:

Purpose: Primary topic classification
Values: Must be one of these exact slugs:

  • analytics-bi → Analytics & BI
  • data-strategy → Data Strategy
  • salesforce → Salesforce
  • consulting-insights → Consulting Insights

Affects:

  • URL structure: /category/article-title/
  • Category page filtering
  • Category badge on cards

Example:

category: analytics-bi

Wrong:

category: Analytics & BI  # Don't use display name!
category: analytics  # Wrong slug

Optional Fields Explained

tags: [tag1, tag2, tag3]

Purpose: Topic keywords for cross-referencing
Format: Array in square brackets, comma-separated
Display: Pills at bottom of article

Best practices:

  • Use 3-6 tags per article
  • Lowercase, hyphenated for multi-word
  • Be consistent (reuse tags across articles)
  • Mix general and specific

Examples:

tags: [real-time analytics, apache kafka, streaming data, decision-making]
tags: [salesforce, integration, rest api, data sync]
tags: [consulting, client engagement, transformation, change management]

excerpt: "Description"

Purpose: Short summary (shows in cards on hover, search results, SEO)
Format: Quoted string, 1-2 sentences
Length: 100-160 characters ideal

Examples:

excerpt: "How forward-thinking organizations leverage streaming data to make decisions at the speed of business."
excerpt: "Five integration patterns that solve 90% of Salesforce connectivity challenges."

If omitted: Jekyll uses first paragraph (might not be ideal)

image: /path/to/image.jpg

Purpose: Featured image for article card
Format: Absolute path from root (starts with /)
Recommended size: 1200x720px (5:3 ratio), compressed to <300KB

Examples:

image: /images/posts/2026-01-15-article-title/hero.jpg
image: /images/posts/2026-02-03-another-article/cover.png

If omitted: Card shows gradient placeholder

Markdown Syntax (Complete Guide)

Headings

## Main Section (H2)
### Subsection (H3)
#### Sub-subsection (H4)

Hierarchy rules:

  • H1 is article title (set in front matter, don’t use in content)
  • Start with H2 (##) for main sections
  • Use H3 (###) for subsections
  • Use H4 (####) rarely (detailed breakdowns)

Best practices:

  • Don’t skip levels (H2 → H4 is wrong)
  • Keep headings concise (under 10 words)
  • Use sentence case, not ALL CAPS

Paragraphs

This is a paragraph. Just write normally.

Leave a blank line between paragraphs.

This is a new paragraph.

Line breaks within paragraphs:

This is one line  
Add two spaces at end of line to force break
This appears on new line

Emphasis

**Bold text** for strong emphasis
*Italic text* for subtle emphasis
***Bold and italic*** for maximum emphasis

Renders as:

  • Bold text for strong emphasis
  • Italic text for subtle emphasis
  • Bold and italic for maximum emphasis
[Link text](https://example.com)
[Another article](/analytics-bi/previous-article/)
[Link with title](https://example.com "Hover text")

Internal links (to other articles):

Read my [previous article on data governance](/data-strategy/governance-frameworks/)

External links:

Check out [Apache Kafka documentation](https://kafka.apache.org/documentation/)

Email links:

Contact me at [athelivijay17@gmail.com](mailto:athelivijay17@gmail.com)

Lists

Unordered (Bullet) Lists

- First item
- Second item
- Third item
  - Nested item (indent with 2 spaces)
  - Another nested item
- Fourth item

Ordered (Numbered) Lists

1. First step
2. Second step
3. Third step
   1. Sub-step (indent with 3 spaces)
   2. Another sub-step
4. Fourth step

Mixed lists:

1. Main point
   - Supporting detail
   - Another detail
2. Next main point

Blockquotes

> This is a quote or callout.
> It can span multiple lines.
> 
> Even multiple paragraphs.

Renders as:

This is a quote or callout. It can span multiple lines.

Use for:

  • Quotes from sources
  • Key takeaways
  • Important callouts
  • Pulling out main ideas

Code

Inline Code

Use `inline code` for commands, variables, or technical terms.

Example: The `requestAnimationFrame` function improves performance.

Code Blocks

```python
def analyze_data(df):
    """Process dataframe and return insights."""
    return df.groupby('category').agg({
        'revenue': 'sum',
        'count': 'count'
    })
```

Supported languages (for syntax highlighting):

  • python, javascript, java, sql, bash, yaml, json, css, html

Best practices:

  • Always specify language after opening ```
  • Keep code blocks under 30 lines
  • Add comments for clarity
  • Include context before code block

Horizontal Rules

Use three hyphens for a divider:

---

Content continues after the line.

Use sparingly - section transitions, major topic changes

Images

Basic Image

![Alt text description](/images/posts/2026-01-15-article/diagram.png)

Image with Caption

![Data pipeline architecture](/images/posts/2026-01-15-article/pipeline.png)
*Figure 1: Modern data pipeline with streaming and batch processing*

Best practices:

  • Always include alt text (accessibility + SEO)
  • Use descriptive filenames
  • Compress images before adding
  • Recommended size: 1200px wide max

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
| Row 2 Col 1 | Row 2 Col 2 | Row 2 Col 3 |

Alignment:

| Left | Center | Right |
|:-----|:------:|------:|
| Text | Text   | Text  |

Tips:

  • Use for data comparison
  • Keep tables simple (max 5 columns)
  • Consider using an image of a table for complex data

Adding Images

Image Workflow

Step 1: Prepare Images

Recommended specs:

  • Featured image (card): 1200x720px (5:3 ratio)
  • Inline images: 1200px width max
  • Diagrams/screenshots: As needed, but compress
  • Format: JPG for photos, PNG for diagrams/screenshots
  • Compression: Aim for <300KB per image

Tools:

  • Compression: TinyPNG.com, Squoosh.app
  • Editing: Photoshop, GIMP, Canva

Step 2: Organize in Folder

# Create folder for your article's images
mkdir -p images/posts/2026-01-15-article-title

# Copy images into that folder
# Name them descriptively
images/posts/2026-01-15-article-title/
├── hero.jpg          # Featured image for card
├── diagram-1.png     # First diagram in article
├── screenshot-2.png  # Screenshot
└── chart-3.jpg       # Data visualization

Step 3: Reference in Article

---
title: "My Article"
image: /images/posts/2026-01-15-article-title/hero.jpg
---

## Section with Image

Here's a diagram explaining the concept:

![Data flow diagram](/images/posts/2026-01-15-article-title/diagram-1.png)

The diagram shows how data moves through the system...

Important:

  • ✅ Paths start with / (absolute from root)
  • ✅ Use exact filename (case-sensitive)
  • ✅ Include alt text in square brackets
  • ✅ Compress images before committing

Image Best Practices

Do:

  • ✅ Compress all images (<300KB each)
  • ✅ Use descriptive filenames: salesforce-architecture-diagram.png
  • ✅ Store in article-specific folder
  • ✅ Use alt text that describes the image content
  • ✅ Reference with absolute paths: /images/...

Don’t:

  • ❌ Use spaces in filenames: my diagram.png
  • ❌ Upload uncompressed RAW images (MBs in size)
  • ❌ Use relative paths: ../images/...
  • ❌ Forget alt text (bad for SEO and accessibility)
  • ❌ Use generic names: image1.jpg, screenshot.png

Markdown Formatting Tips

Emphasis in Content

Bold for:

  • Key terms on first use
  • Important takeaways
  • Strong emphasis

Example:

The **modern data stack** has fundamentally changed how organizations approach analytics.

Italic for:

  • Subtle emphasis
  • Foreign words
  • Internal thoughts
  • Quotes within text

Example:

This approach requires *rethinking* the entire data architecture.

Creating Lists

When to use bullet lists:

  • Multiple related items
  • No specific order
  • Quick reference points

When to use numbered lists:

  • Sequential steps
  • Ranked items
  • Procedures or processes

Example - Mixing both:

## Implementation Steps

1. **Assess current state**
   - Review existing data infrastructure
   - Interview key stakeholders
   - Document pain points

2. **Design solution**
   - Choose appropriate tools
   - Create architecture diagram
   - Define success metrics

3. **Execute in phases**
   - Start with pilot project
   - Gather feedback
   - Iterate and expand

Using Blockquotes Effectively

For quotes:

As the CTO mentioned in our kickoff meeting:

> "We need real-time visibility into customer behavior, not yesterday's dashboard."

This became the north star for our analytics transformation.

For key takeaways:

> **Key Insight:** Organizations that treat data as a product, not a byproduct, build more sustainable analytics capabilities.

For callouts:

> **Important:** Always validate data quality before making strategic decisions based on new metrics.

Code Snippets

When to use code blocks:

  • SQL queries
  • Python/Java code examples
  • Configuration files
  • API examples
  • Terminal commands

SQL example:

Here's how you query the data:

```sql
SELECT 
    category,
    COUNT(*) as article_count,
    AVG(reading_time) as avg_time
FROM articles
WHERE publish_date >= '2025-01-01'
GROUP BY category
ORDER BY article_count DESC;


**Python example:**
````markdown
Process the data with this function:

```python
import pandas as pd

def clean_dataframe(df):
    """Remove nulls and standardize column names."""
    df = df.dropna()
    df.columns = df.columns.str.lower().str.replace(' ', '_')
    return df

result = clean_dataframe(raw_data)


**Command line:**
````markdown
Run these commands:

```bash
cd /path/to/project
pip install -r requirements.txt
python main.py
```

Categories & Tags

Choosing the Right Category

Every article must have ONE category.

analytics-bi

Use for:

  • Business Intelligence platforms (Tableau, Power BI, Looker)
  • Analytics strategies and frameworks
  • Dashboard design
  • Reporting best practices
  • Data visualization
  • Analytics team organization

Example titles:

  • “Choosing the Right BI Platform for Your Organization”
  • “Building Executive Dashboards That Drive Action”
  • “The Evolution of Self-Service Analytics”

data-strategy

Use for:

  • Data architecture and infrastructure
  • Modern data stack
  • Data governance and quality
  • Data warehousing and lakes
  • ETL/ELT pipelines
  • Data platform selection

Example titles:

  • “Designing a Scalable Data Architecture”
  • “Data Governance Without Bureaucracy”
  • “Migrating from On-Prem to Cloud Data Warehouse”

salesforce

Use for:

  • Salesforce implementation
  • CRM strategy
  • Salesforce configuration and customization
  • Integration patterns
  • Specific Salesforce clouds (Sales, Service, Marketing)
  • Apex, Lightning, Flow

Example titles:

  • “Salesforce Integration Patterns for Enterprise”
  • “Building Custom Lightning Components”
  • “Sales Cloud vs Service Cloud: When to Use Which”

consulting-insights

Use for:

  • Client engagement stories (anonymized)
  • Consulting methodologies
  • Transformation projects
  • Change management
  • Stakeholder management
  • Lessons learned
  • Industry observations

Example titles:

  • “Why Digital Transformations Fail (And How to Prevent It)”
  • “Managing Stakeholder Expectations in Analytics Projects”
  • “5 Lessons from My First Year as an Independent Consultant”

Using Tags Effectively

Tags are cross-category topics.

Strategy:

  • Use 3-6 tags per article
  • Mix broad and specific tags
  • Be consistent (reuse tags across articles)
  • Think: “What would someone search for?”

Good tag examples:

# Broad + Specific:
tags: [analytics, real-time data, apache kafka, streaming]

# Technology + Concept:
tags: [salesforce, integration, rest api, middleware]

# Domain + Application:
tags: [retail analytics, customer behavior, predictive models]

Tag naming conventions:

  • Lowercase
  • Multi-word: Use hyphens real-time-analytics
  • Technologies: Use proper names Apache Kafka, Salesforce, Python
  • Concepts: Be specific data-governance not just governance

Article Structure Best Practices

---
[Front matter]
---

## Introduction (2-3 paragraphs)
- Hook: Why this matters
- Context: Set the stage
- Promise: What reader will learn

## Background / Problem (Optional)
- Explain the challenge
- Provide context

## Main Content (3-5 sections)
### First Major Point
Content...

### Second Major Point
Content...

### Third Major Point
Content...

## Practical Application / Implementation
- How to apply these insights
- Step-by-step guidance
- Real-world examples

## Conclusion (1-2 paragraphs)
- Summarize key points
- Call to action or next steps
- Forward-looking statement

Article Length Guidelines

Short articles (500-800 words):

  • Quick insights
  • Single-topic deep dives
  • Tool reviews
  • Best practices lists

Medium articles (800-1500 words):

  • Most common length
  • Good depth without overwhelming
  • Case studies
  • How-to guides

Long articles (1500-3000 words):

  • Comprehensive guides
  • Multi-faceted topics
  • Thought leadership pieces
  • Research-based content

Reading time calculation:

  • ~200 words per minute
  • 1000 words ≈ 5 min read
  • 1500 words ≈ 7-8 min read

Advanced Formatting

Nested Lists

1. **First main point**
   - Supporting detail A
   - Supporting detail B
     - Sub-detail 1
     - Sub-detail 2
   - Supporting detail C

2. **Second main point**
   - Another set of details

Complex Blockquotes

> **Key Takeaway**
> 
> The most successful analytics transformations start with clear business objectives, not technology selection. Organizations that lead with "We need Snowflake" rather than "We need to reduce time-to-insight" often struggle.

Combining Code and Explanation

The query uses a window function for running totals:

```sql
SELECT 
    date,
    revenue,
    SUM(revenue) OVER (
        ORDER BY date 
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) as running_total
FROM daily_sales;
```

Breaking this down:
- `SUM(revenue) OVER (...)` creates the window function
- `ORDER BY date` ensures chronological calculation
- `ROWS BETWEEN...` defines the window frame

Creating Visual Breaks

Section divider:

---

New major section starts here.

Emphasis break (three asterisks):

* * *

Visual pause in content.

Full Article Example

---
layout: post
title: "Why Data Governance Fails in Most Organizations"
date: 2026-01-20
category: data-strategy
tags: [data governance, data quality, organizational change, best practices]
excerpt: "Data governance initiatives fail 70% of the time. Here's why, and how to be in the 30% that succeed."
image: /images/posts/2026-01-20-data-governance-fails/hero.jpg
---

## The Uncomfortable Truth

Most data governance programs fail. Not "underperform" or "take longer than expected." **Fail.** As in, three years and millions of dollars later, data quality is no better, compliance gaps remain, and the governance council has stopped meeting.

I've seen this pattern across industries—healthcare, financial services, retail, technology. The specifics differ, but the failure modes are remarkably consistent.

## Why Governance Initiatives Struggle

### They Start with Policies, Not Problems

![Governance framework diagram](/images/posts/2026-01-20-data-governance-fails/framework.png)

The typical approach:

1. Hire a data governance consultant
2. Create a comprehensive framework
3. Write extensive policies and procedures
4. Form a governance council
5. Wonder why no one follows the policies

The issue? **No one wakes up excited about policies.** They wake up frustrated about:

- Unreliable reports that contradict each other
- Customer data spread across 47 systems
- Compliance audits that reveal gaps
- Decisions delayed waiting for "clean" data

Start with these problems, not abstract frameworks.

### They Treat Governance as IT's Job

> **Reality Check:** Data governance is a business problem that requires technical solutions, not a technical problem that business happens to care about.

When governance lives in IT:
- Business teams see it as red tape
- Compliance becomes a checkbox exercise
- Real data quality issues go unaddressed
- Governance team lacks authority

**Better approach:** Business owns governance, IT enables it.

### They Aim for Perfection

I worked with a client who spent 18 months defining their "master data model" before attempting implementation. Meanwhile, their sales and support teams were using different customer databases, causing real business problems daily.

Perfect is the enemy of good in data governance.

## What Actually Works

### Start Small and Specific

Pick ONE critical business process that's broken because of data issues.

Examples:
- Customer onboarding takes 3 weeks because systems don't sync
- Finance can't close books without manual reconciliation
- Compliance can't trace data lineage for audits

Fix that ONE thing. Document what you learn. Expand from there.

### Make Governance Valuable, Not Burdensome

Good governance should make people's jobs **easier**, not harder.

**Bad governance:**
```
Submit data dictionary request → Wait for approval → 
Attend governance meeting → Wait for another meeting → 
Get dictionary 6 weeks later
```

**Good governance:**
```
Search data catalog → Find table with good documentation → 
Use immediately → Flag quality issues → 
Automated alerts improve data over time
```

### Measure What Matters

Don't measure:
- Number of policies written
- Governance meetings held
- People "trained" on governance

Measure:
- Data quality incidents (trending down?)
- Time to resolve data issues (getting faster?)
- Compliance gaps (closing?)
- Business decisions delayed by data problems (decreasing?)

## The Path Forward

Data governance succeeds when it:

1. Solves real business problems
2. Lives where the business is (not in IT)
3. Starts small and proves value
4. Makes work easier, not harder
5. Measures business outcomes, not process compliance

Start with your biggest pain point. Build governance around solving it. Let success breed expansion.

The 30% who succeed don't have better frameworks. They have better focus.

---

*Working on a data governance initiative? [Let's connect](https://linkedin.com/in/vijay-chandra-atheli) to discuss strategies.*

Publishing Checklist

Before Committing

  • Front matter complete and valid YAML
  • Title is clear and under 60 characters
  • Date is correct format (YYYY-MM-DD)
  • Category matches one of four options exactly
  • Tags are relevant and consistent with past articles
  • Excerpt is 100-160 characters
  • Featured image exists and is compressed
  • All inline images exist and paths are correct
  • No spelling/grammar errors (run through Grammarly or similar)
  • Markdown syntax is correct (headings, lists, links)
  • Code blocks specify language
  • Alt text added to all images

After Pushing

  • Wait 2 minutes for GitHub Pages to build
  • Visit article URL and verify it looks correct
  • Check on mobile device (or browser mobile view)
  • Test dark mode toggle
  • Verify images load
  • Check category page shows new article
  • Verify homepage shows in “Latest Articles”
  • Test all links in article

Updating Existing Articles

Fix Typos or Errors

# 1. Open the article file
code _posts/2025-12-28-article-name.md

# 2. Make changes

# 3. Commit with descriptive message
git add _posts/2025-12-28-article-name.md
git commit -m "Fix typo in 'Article Name'"
git push origin master

Major Content Updates

Update the date in front matter if significantly changed:

---
title: "Original Title"
date: 2025-12-28       # Original
updated: 2026-02-15    # Add this line for major updates
---

Note in article:

*Updated February 15, 2026: Added section on new Salesforce features.*

Unpublishing an Article

Option 1: Delete permanently

git rm _posts/2025-12-28-article-to-remove.md
git commit -m "Remove article: Article Name"
git push

Option 2: Rename to draft (won’t publish)

# Rename without date prefix
mv _posts/2025-12-28-article.md _posts/draft-article.md

git add .
git commit -m "Move article to draft"
git push

Git Workflow

Daily Publishing Routine

# Check current status
git status

# Pull latest changes (if working from multiple computers)
git pull origin master

# Create new article
touch _posts/2026-01-15-my-article.md

# Write content...

# Stage all changes
git add .

# Commit with message
git commit -m "New article: My Article Title"

# Push to GitHub
git push origin master

# Verify deployment
# Go to: https://github.com/VijayChandraAtheli/vijaychandraatheli.com/actions
# Check for green checkmark

Commit Message Best Practices

Good commit messages:

New article: The Future of Real-Time Analytics
Fix typo in Salesforce integration article
Update About page with recent experience
Add images to data governance article
Feature: Enable comments on articles

Bad commit messages:

Update
Fixed stuff
asdf
Changes

Edit _config.yml:

featured_posts:
  - "2026-01-20-data-governance-fails"      # Newest/best
  - "2026-01-10-salesforce-integration"     # Second choice
  - "2025-12-28-welcome-to-my-journal"      # Third choice

Rules:

  • Use exact filename (with date, without .md)
  • Order matters (shows in this order)
  • Maximum 3 posts recommended
  • Update monthly with your best work

After editing:

git add _config.yml
git commit -m "Update featured articles"
git push

Writing Tips for Technical Content

Make It Scannable

Use:

  • Short paragraphs (3-5 sentences)
  • Descriptive headings
  • Bullet lists for multiple points
  • Bold for key terms
  • Blockquotes for takeaways

Example of scannable content:

## The Three-Phase Approach

**Phase 1: Assessment**

Start by understanding current state. Interview stakeholders, map existing data flows, and document pain points.

Key activities:
- Stakeholder interviews (5-10 people)
- Process documentation
- Pain point inventory

**Phase 2: Design**

Create the target architecture. Choose tools, define processes, set success metrics.

**Phase 3: Implementation**

Execute in sprints. Start small, prove value, expand.

Balance Depth and Accessibility

For technical topics:

  • Explain concepts before diving into details
  • Use analogies for complex ideas
  • Provide context before jargon
  • Link to external resources for deeper dives

Example:

## Understanding Stream Processing

Think of stream processing like a factory assembly line, but for data. Instead of waiting for a batch of parts to arrive (batch processing), workers handle each item as it arrives (stream processing).

In technical terms, stream processing systems like Apache Kafka process events in real-time as they're generated, rather than collecting them and processing periodically.

For a deep dive into Kafka's architecture, see the [official documentation](https://kafka.apache.org/documentation/).

Use Real Examples

Instead of:

“Organizations should implement data quality checks.”

Write:

“Before loading customer data into Salesforce, we added validation rules: email format checks, duplicate detection, and mandatory field verification. This reduced data errors by 67% in the first month.”

Specific beats generic.

Common Markdown Mistakes to Avoid

❌ Wrong: Missing blank lines

## Heading
Next paragraph starts immediately (renders as same block!)

✅ Correct: Blank lines separate blocks

## Heading

New paragraph starts here (properly separated).

❌ Wrong: Inconsistent heading levels

## Main Section
#### Skipped H3 (wrong hierarchy!)

✅ Correct: Sequential hierarchy

## Main Section
### Subsection
#### Detail point

❌ Wrong: Inline HTML (avoid)

<div class="custom">HTML in markdown</div>

✅ Correct: Use markdown features

> Use blockquotes for callouts
**Use bold for emphasis**

Image Guidelines (Detailed)

Image Type Dimensions Max Size Format
Featured (hero) 1200x720px 300KB JPG
Inline photo 1200px wide 250KB JPG
Diagram/chart 1200px wide 150KB PNG
Screenshot Actual size 200KB PNG
Icon/small 400px 50KB PNG/SVG

Image Compression Tools

Online:

  • TinyPNG.com - Excellent compression, maintains quality
  • Squoosh.app - Control compression level, see before/after
  • CompressJPEG.com - Batch processing

Desktop:

  • Photoshop: “Save for Web”
  • GIMP: Export with quality slider
  • ImageOptim (Mac) - Drag and drop

Command line:

# JPG compression (requires imagemagick)
convert input.jpg -quality 85 -resize 1200x output.jpg

# PNG compression (requires optipng)
optipng -o5 input.png

Tools:

  • Canva - Templates, easy to use
  • Figma - Professional design tool
  • Photoshop - Full control
  • Unsplash - Free stock photos

Template size: 1200x720px

Design tips:

  • Simple, bold compositions
  • High contrast text (if adding text overlay)
  • Related to article topic
  • Professional, not clip-art
  • Consistent style across articles

Free photo sources:

  • Unsplash.com - High-quality, free
  • Pexels.com - Curated photos
  • Pixabay.com - Large library

Videos & Embeds

Embedding YouTube Videos

You cannot embed videos directly in Markdown/Jekyll.

Options:

Option 1: Link to video

Watch my explanation: [Data Pipeline Architecture](https://youtube.com/watch?v=xyz123)

Option 2: Screenshot + link

[![Video thumbnail](/images/posts/2026-01-15-article/video-thumb.jpg)](https://youtube.com/watch?v=xyz123)

*Click to watch the full explanation on YouTube*

Option 3: Add HTML (advanced)

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe src="https://www.youtube.com/embed/xyz123" 
          style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" 
          frameborder="0" 
          allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" 
          allowfullscreen>
  </iframe>
</div>

Recommendation: Link to videos, don’t embed (keeps page fast)

Updating Your Bio

File: pages/about.md

Structure:

---
layout: page
title: About Me
subtitle: Business Analyst | Consultant | Technology Strategist
permalink: /about/
---

## Background

2-3 paragraphs about your experience...

## What I Write About

### Business Intelligence & Analytics
Description...

### Data Strategy & Architecture
Description...

### Salesforce
Description...

### Consulting Insights
Description...

## Connect

- **LinkedIn:** [Profile](https://linkedin.com/in/your-profile)
- **GitHub:** [Projects](https://github.com/VijayChandraAtheli)
- **Email:** [athelivijay17@gmail.com](mailto:athelivijay17@gmail.com)

Update when:

  • Change jobs/roles
  • Gain new certifications
  • Major projects completed
  • Contact info changes

Common Questions

How do I schedule a post for future publication?

Use a future date:

date: 2026-02-01  # Article won't show until Feb 1, 2026

Jekyll automatically hides future-dated posts until that date.

How do I create a draft?

Option 1: Use _drafts folder

mkdir _drafts
touch _drafts/work-in-progress.md
# No date needed in filename
# Won't publish until moved to _posts

Option 2: Use future date

date: 2099-12-31  # Far future = draft

Can I edit articles after publishing?

Yes! Just edit the file and push:

# Edit the file
code _posts/2025-12-28-article.md

# Commit and push
git add _posts/2025-12-28-article.md
git commit -m "Update article: add new section on X"
git push

Changes appear in 1-2 minutes.

How do I change the site tagline?

Edit _config.yml:

tagline: New Tagline Here

Commit and push. Appears site-wide instantly.

How do I add a new page (not an article)?

Create in pages/ folder:

---
layout: page
title: Services
subtitle: How I Can Help
permalink: /services/
---

Your content here...

Add to navigation in _config.yml:

navigation:
  - title: "Services"
    url: "/services/"

Quick Reference

File Naming Cheat Sheet

Articles: YYYY-MM-DD-slug.md
Images: descriptive-name.jpg (lowercase, hyphens)
Folders: lowercase-with-hyphens/

Front Matter Template

---
layout: post
title: "Article Title"
date: YYYY-MM-DD
category: [analytics-bi | data-strategy | salesforce | consulting-insights]
tags: [tag1, tag2, tag3]
excerpt: "Short description"
image: /images/posts/YYYY-MM-DD-slug/hero.jpg
---

Markdown Quick Reference

## Heading 2
### Heading 3

**Bold text**
*Italic text*

[Link](https://url.com)
![Image](/path/to/image.jpg)

- Bullet list
1. Numbered list

> Blockquote

`inline code`

```language
code block


### Git Commands

```bash
git status           # Check what changed
git add .            # Stage all changes
git commit -m "msg"  # Commit with message
git push             # Push to GitHub
git log --oneline    # See recent commits
git diff             # See what changed

Support & Resources

If Something Breaks

  1. Check GitHub Actions - See build errors
  2. Revert last commit - git revert HEAD
  3. Validate YAML - Use yamllint.com
  4. Test locally - bundle exec jekyll serve
  5. Check browser console - F12 for JavaScript errors

Learning Resources

Markdown:

  • https://www.markdownguide.org/
  • https://commonmark.org/help/

Jekyll:

  • https://jekyllrb.com/docs/
  • https://jekyllrb.com/docs/posts/

Git:

  • https://git-scm.com/book/en/v2
  • https://learngitbranching.js.org/

Happy writing! 📝

For technical details, see DEVELOPER_GUIDE.md

    </div>
</article>

</div>`)

  • Footer include
  • JavaScript includes

Template hierarchy:

All pages use → default.html
    ├── home.html (uses default)
    ├── post.html (uses default)
    └── page.html (uses default)

home.html

Purpose: Homepage layout with intro + featured + grid
You Edit: Rarely (only to change homepage structure)
Contains:

  • Introduction section (from index.md)
  • Featured articles grid (3 columns)
  • Latest articles grid (4 columns)
  • Conditional rendering based on post count

post.html

Purpose: Single article page layout
You Edit: Never (unless changing article page structure)
Contains:

  • Category badge
  • Article title and subtitle
  • Author metadata (avatar, name, date, read time)
  • Article content area
  • Tags footer
  • “Back to Journal” link

page.html

Purpose: Static pages (About, category pages)
You Edit: Never (unless changing page structure)
Contains:

  • Page title and subtitle
  • Page content area
  • Minimal, clean layout

Include Files (_includes/)

header.html

Purpose: Site header with navigation
You Edit: Never (styling handled by CSS)
Contains:

  • Site title (your name)
  • Tagline
  • Navigation menu (dynamically generated from _config.yml)

Behavior:

  • Normal state: Centered, full branding
  • Sticky state: Compact with “VC” + inline navigation

footer.html

Purpose: Site footer with links
You Edit: Rarely (only to add/change footer links)
Contains:

  • Copyright notice (auto-updates year)
  • Social links (LinkedIn, GitHub, Email from _config.yml)

article-card.html

Purpose: Reusable article card for grids
You Edit: Never (unless changing card design)
Contains:

  • Card image with category badge (top-right)
  • Article title
  • Excerpt (hidden, shows on hover)
  • Metadata (date, reading time)

Content Files

_posts/ Folder

Purpose: All your journal articles
You Edit: THIS IS WHERE YOU WORK DAILY
Naming convention: YYYY-MM-DD-article-slug.md

Example:

_posts/2025-12-28-welcome-to-my-journal.md
_posts/2026-01-05-salesforce-integration-patterns.md
_posts/2026-01-12-data-governance-frameworks.md

Each file contains:

  • YAML front matter (metadata)
  • Markdown content (article body)

pages/ Folder

Purpose: Static pages and category archives
You Edit: Occasionally (updating bio, category descriptions)

Files:

  • about.md - Your professional bio
  • journal.md - All articles archive
  • analytics-bi.md - Analytics & BI category page
  • data-strategy.md - Data Strategy category page
  • salesforce.md - Salesforce category page
  • consulting-insights.md - Consulting category page

index.md

Purpose: Homepage content
You Edit: Rarely (only to update intro text)
Contains: Introduction section in YAML front matter

Asset Files

assets/css/main.css

Purpose: Complete site styling (~800 lines)
You Edit: Rarely (only for design changes)

Structure:

CSS Variables (lines 1-25)
    - Colors, fonts, spacing values
    
Base Styles (lines 26-60)
    - Reset, body defaults
    
Components:
    - Ambient gradient background
    - Theme toggle button
    - Sticky header system
    - Footer
    - Homepage hero section
    - Section titles
    - Article grids (3-col featured, 4-col latest)
    - Article cards
    - Single post pages
    - Static pages
    
Responsive Design (lines 800+)
    - Tablet breakpoints (@992px)
    - Mobile breakpoints (@768px)
    - Small mobile (@480px)

Key sections you might edit:

  • Lines 10-20: Color variables (change accent color, etc.)
  • Lines 40-50: Body font size and line-height
  • Lines 450-550: Spacing values (if you want more/less compact)

assets/js/theme.js

Purpose: Interactive features
You Edit: Never (unless adding new features)

Features implemented:

  1. Dark mode toggle
    • Saves preference to localStorage
    • Persists across sessions
    • Updates moon/sun icon
  2. Sticky compact header
    • Activates at 100px scroll
    • Smooth opacity crossfade
    • Placeholder prevents content jump
    • Body class for theme toggle positioning
  3. Keyboard shortcuts
    • Press ‘T’ to scroll to top
  4. External link handling
    • Automatically opens in new tab
    • Adds security attributes
  5. Image lazy loading
    • Improves page load performance
  6. Print handling
    • Removes dark mode when printing
    • Resets header to normal

Design System

Typography Scale

Fonts:

  • Serif (Crimson Pro): Body text, tagline, intro paragraphs
  • Sans-serif (Work Sans): Headers, navigation, UI elements, metadata

Font Sizes:

Site Title: 48px (Work Sans, weight 800)
Article Title: 50px (Work Sans, weight 800)
H2 in articles: 30px (Work Sans, weight 700)
H3 in articles: 22px (Work Sans, weight 600)
Body text: 18px (Crimson Pro, weight 400)
Navigation: 13px uppercase (Work Sans, weight 600)
Compact nav (sticky): 11px
Card titles: 18px (Work Sans, weight 700)
Meta text: 12-13px (Work Sans)

Color Palette

CSS Variables (defined in :root):

--accent: #d63447         /* Red - primary action color */
--dark: #1a1a1a          /* Almost black - text */
--light: #ffffff         /* White - backgrounds */
--gray: #666             /* Medium gray - secondary text */
--border: #ddd           /* Light gray - borders */
--gradient-start: #d63447 /* Red - gradient start */
--gradient-end: #9b59b6   /* Purple - gradient end */

Dark Mode Overrides:

--light: #0a0a0a
--dark: #e8e8e8
--border: #333
--gray: #999

Usage:

  • Accent color: Category badges, hover states, underlines, links
  • Dark: Text, borders in light mode
  • Light: Backgrounds in light mode
  • Gray: Secondary text, metadata, subtle elements

Spacing System

Line Heights:

  • Body text: 1.4
  • Article content: 1.45-1.5
  • Headers: 1.08-1.25 (tight for impact)

Margins (Vertical Rhythm):

  • Between paragraphs: 0.5-0.65em
  • Before H2: 28px
  • Before H3: 22px
  • Between sections: 35-45px
  • Article header: 28px bottom
  • Article footer: 35px top

Grid System

Homepage:

  • Featured Articles: 3 columns (desktop)
  • Latest Articles: 4 columns (desktop)
  • Gap: 22px

Responsive Breakpoints:

  • >1200px: 4 columns (latest), 3 columns (featured)
  • 992-1200px: 3 columns (latest)
  • 768-992px: 2 columns
  • <768px: 1 column (mobile)

Card Specifications:

  • Image aspect ratio: 5:3 (60% padding-top)
  • Border-radius: 8px
  • Hover: translateY(-5px) + box-shadow
  • Category badge: 8px top-right, 8px font size

Build & Deployment

How Jekyll Works

Process:

1. You write: Markdown files
2. You push: Git commit + push
3. GitHub runs: Jekyll build process
4. Jekyll reads:
   - _config.yml (settings)
   - _posts/*.md (articles)
   - _layouts/*.html (templates)
   - _includes/*.html (components)
   - assets/* (CSS, JS, images)
5. Jekyll generates: Complete HTML/CSS/JS website
6. GitHub serves: Static files at vijaychandraatheli.com

Build time: ~1-2 minutes after push

Deployment Workflow

Standard article publish:

# 1. Create article
touch _posts/2026-01-15-my-new-article.md

# 2. Write content (see ADMIN_GUIDE.md)

# 3. Add images (if any)
mkdir -p images/posts/2026-01-15-my-new-article
# Copy images to that folder

# 4. Commit and push
git add .
git commit -m "New article: My New Article"
git push origin master

# 5. Wait 1-2 minutes
# Article appears at: vijaychandraatheli.com/category/my-new-article/

Local Development (Optional)

If you want to preview before publishing:

# One-time setup (install Jekyll):
gem install bundler jekyll

# Install dependencies:
bundle install

# Run local server:
bundle exec jekyll serve

# View at: http://localhost:4000
# Auto-rebuilds when you save files

Pros of local preview:

  • See changes instantly
  • Catch formatting errors before publishing
  • Test on mobile devices via network

Cons:

  • Requires Ruby installed
  • Extra setup step

Custom Features

1. Sticky Compact Header

Implementation:

  • JavaScript: assets/js/theme.js lines 30-95
  • CSS: assets/css/main.css lines 145-280
  • Trigger: Scroll > 100px

How it works:

  1. Detects scroll position
  2. When > 100px: Adds .sticky class to <header>
  3. CSS fades out title/tagline, fades in “VC”
  4. Creates placeholder div to prevent content jump
  5. Placeholder height animates: expanded → compact
  6. Adds header-is-sticky class to <body> (moves dark mode toggle down)

States:

  • Normal: Full branding (title + tagline + nav)
  • Sticky: Compact (VC + nav inline)

Customization:

const scrollThreshold = 100; // Change this to trigger earlier/later

2. Dark Mode

Implementation:

  • JavaScript: assets/js/theme.js lines 15-30
  • CSS: CSS variables override in dark mode
  • Storage: localStorage key: theme

How it works:

  1. On page load: Check localStorage for saved preference
  2. Apply dark-mode class to <body> if saved
  3. Toggle button: Switches class, saves preference
  4. CSS variables automatically update colors

Color overrides:

body.dark-mode {
    --light: #0a0a0a;  /* Dark background */
    --dark: #e8e8e8;   /* Light text */
    --border: #333;
    --gray: #999;
}

3. Article Grid with Hover Effects

Implementation:

  • HTML: _includes/article-card.html
  • CSS: .article-card section

Features:

  • Category badge (top-right corner, 8px font)
  • Title below image
  • Excerpt (hidden, shows on hover with opacity transition)
  • Metadata (date, reading time)
  • Card lifts on hover (translateY(-5px))
  • Image zooms on hover (scale(1.05))

4. Category System

URL Structure:

/category-slug/article-slug/

Examples:
/analytics-bi/real-time-analytics/
/data-strategy/modern-data-stack/
/salesforce/integration-patterns/
/consulting-insights/transformation-case-study/

Categories:

  • analytics-bi → “Analytics & BI”
  • data-strategy → “Data Strategy”
  • salesforce → “Salesforce”
  • consulting-insights → “Consulting Insights”

Each category has:

  • Navigation link in header
  • Dedicated archive page (pages/category-name.md)
  • Auto-filtered article list

Implementation: _config.yml + homepage layout

How to feature an article:

  1. Add filename to featured_posts array in _config.yml
  2. Use exact filename (with date prefix, without .md)
  3. Order matters (shows in list order)
  4. Limit: 3 articles maximum

Example:

featured_posts:
  - "2025-12-28-welcome-to-my-journal"
  - "2026-01-10-best-article-ever"
  - "2026-01-20-another-great-one"

URL Structure

Set in _config.yml:

permalink: /:categories/:title/

Generated URLs:

Article: _posts/2026-01-15-salesforce-best-practices.md
Category: salesforce
Result: /salesforce/salesforce-best-practices/

Clean URLs:

  • No dates in URLs (evergreen content)
  • Category visible in path (good for SEO)
  • Lowercase, hyphenated slugs
  • No file extensions

Design System Details

Responsive Grid

CSS Grid Implementation:

.articles-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 22px;
}

/* Tablet */
@media (max-width: 1200px) {
    grid-template-columns: repeat(3, 1fr);
}

/* Mobile */
@media (max-width: 768px) {
    grid-template-columns: 1fr;
}

Automatically responsive - adjusts based on screen width AND browser zoom.

Typography System

Hierarchy:

Level 1: Site title (48px, 800 weight)
Level 2: Article title (50px, 800 weight)
Level 3: H2 in content (30px, 700 weight)
Level 4: H3 in content (22px, 600 weight)
Level 5: Body text (18px, 400 weight)
Level 6: Metadata (12-13px, 400-600 weight)

Letter spacing:

  • Large titles: Negative (-2px to -1px) for tighter appearance
  • Body text: Normal (0)
  • Uppercase nav: Positive (1px) for readability

Animations

Page load:

  • Header: fadeInDown (0.8s ease)
  • Content: fadeIn (1s ease)
  • Article title: slideIn (0.8s ease)

Interactions:

  • Card hover: transform + box-shadow (0.3s ease)
  • Nav link hover: underline animation (0.3s ease)
  • Tag hover: background + lift (0.3s ease)
  • Dark mode toggle: rotate + scale (0.3s ease)

Sticky header:

  • Opacity crossfade: 0.25-0.3s
  • Placeholder height: 0.35s cubic-bezier
  • Smooth, coordinated transitions

Content Organization

Categories

Purpose: Primary article grouping (one per article)

Available categories:

  1. analytics-bi - Business Intelligence & Analytics
  2. data-strategy - Data architecture, governance, infrastructure
  3. salesforce - CRM, integrations, best practices
  4. consulting-insights - Client work, methodologies, lessons

In article front matter:

category: analytics-bi  # Use slug, not display name

Tags

Purpose: Cross-category topics (multiple per article)

Usage:

tags: [real-time analytics, streaming data, apache kafka, business intelligence]

Displayed: At bottom of articles as clickable pills

Future: Can add tag archive pages

DNS & Hosting Configuration

Domain Setup (Squarespace)

A Records (point to GitHub Pages):

@ → 185.199.108.153
@ → 185.199.109.153
@ → 185.199.110.153
@ → 185.199.111.153

CNAME Record:

www → vijaychandraatheli.github.io

TTL: 4 hours (14400 seconds)

GitHub Pages Settings

Repository: VijayChandraAtheli/vijaychandraatheli.com

Settings → Pages:

  • Source: master branch, / (root) folder
  • Custom domain: vijaychandraatheli.com
  • Enforce HTTPS: ✓ Enabled
  • Build: Automatic on push

CNAME file: Contains single line vijaychandraatheli.com

Troubleshooting

Issue: Site not updating after push

Cause: GitHub Pages build failed or still building

Solution:

  1. Go to repository → Actions tab
  2. Check latest “pages build and deployment” workflow
  3. If failed (red X): Click to see error
  4. If yellow: Still building, wait 2 more minutes
  5. Common errors: YAML syntax in front matter, missing layouts

Quick fix:

# Check Jekyll build locally:
bundle exec jekyll build

# If errors appear, fix them before pushing

Issue: CSS/JS changes not showing

Cause: Browser cache or GitHub Pages cache

Solution:

  1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
  2. Clear browser cache
  3. Open in incognito/private window
  4. Wait 2-3 minutes for GitHub Pages to rebuild
  5. Check if commit is in GitHub (verify push succeeded)

Issue: Article not showing on site

Cause: Filename format wrong or future date

Solution:

  1. Check filename: Must be YYYY-MM-DD-slug.md
  2. Check date: Jekyll won’t show future-dated posts
  3. Check category: Must match one of the defined categories
  4. Check front matter: YAML syntax must be valid

Validation:

---
layout: post               # Must be exactly "post"
title: "Your Title"        # Quoted strings
date: 2025-12-28          # YYYY-MM-DD format, not future
category: analytics-bi     # Must match defined category
tags: [tag1, tag2]        # Array format
excerpt: "Description"     # Optional
image: /images/...        # Optional, relative path
---

Issue: Images not loading

Cause: Wrong path or missing file

Solution:

  1. Check image path starts with / (absolute from root)
  2. Correct: /images/posts/2025-12-28-article/hero.jpg
  3. Wrong: images/posts/... or ./images/...
  4. Verify file exists in repository
  5. Check filename case (case-sensitive on Linux servers)
  6. Compress large images (<500KB recommended)

Issue: Sticky header flickering

Cause: Browser performance or transition conflicts

Solution:

  1. Check if multiple scroll handlers conflicting
  2. Verify placeholder has height: 0 and transition in CSS
  3. Ensure header::before transitions properly
  4. Check browser DevTools Performance tab for layout thrashing

If persists: Increase scroll threshold:

const scrollThreshold = 150; // Instead of 100

Issue: Dark mode not persisting

Cause: localStorage not saving

Solution:

  1. Check browser console for errors
  2. Verify browser allows localStorage (private browsing might block)
  3. Check theme.js loaded correctly
  4. Clear localStorage and try again: 
    // In browser console:
localStorage.clear();

Performance Optimization

Current Optimizations

  1. Static site - No server processing, instant page loads
  2. Image lazy loading - Images load as you scroll
  3. Minimal JavaScript - ~200 lines total, no frameworks
  4. CSS-only animations - GPU-accelerated transforms
  5. Passive scroll listeners - Doesn’t block scrolling
  6. RequestAnimationFrame - Synced with browser repaint

Load Performance

Typical metrics:

  • First paint: <1s
  • Time to interactive: <1.5s
  • Total page size: ~100-200KB (without images)

Future Optimizations

If site grows large:

  • Add pagination (>20 articles per page)
  • Implement search functionality
  • Add service worker for offline
  • Use WebP images with fallbacks
  • Minify CSS/JS in production

Extending the Site

Adding a New Category

Steps:

  1. Add to _config.yml: 
    category_names:
  new-category: "Display Name"
   
navigation:
  - title: "Display Name"
    url: "/new-category/"
  2. Create page: pages/new-category.md 
    ---
layout: page
title: Display Name
subtitle: Description
permalink: /new-category/
---
   
<section class="articles-section">
    <div class="articles-grid">
           
           
    </div>
</section>
  3. Use in articles: 
    category: new-category

Adding Analytics

Google Analytics 4:

  1. Get tracking ID from Google Analytics
  2. Add to _layouts/default.html in <head>: 
    <!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Adding Comments

Using utterances (GitHub Issues as comments):

  1. Install utterances GitHub app on your repo
  2. Add to _layouts/post.html before </article>: 
    <script src="https://utteranc.es/client.js"
        repo="VijayChandraAtheli/vijaychandraatheli.com"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Code Maintenance

What to Edit Regularly

  • _posts/*.md - New articles (daily/weekly)
  • _config.yml - Featured posts (monthly)
  • pages/about.md - Bio updates (quarterly)

What to Edit Rarely

  • assets/css/main.css - Design tweaks (rarely)
  • index.md - Homepage intro (rarely)
  • Category page descriptions (rarely)

What to NEVER Edit (Unless You Know What You’re Doing)

  • _layouts/*.html - Core templates
  • _includes/*.html - Components
  • assets/js/theme.js - Interactive features
  • CNAME - Domain configuration

Backup & Version Control

Git is Your Backup

Everything is version controlled:

# See all changes:
git log --oneline

# Restore previous version:
git checkout abc1234 _posts/2025-12-28-article.md

# Undo last commit:
git revert HEAD

# See what changed:
git diff

Recommendation: Never force-push, always commit logically

Disaster Recovery

If site breaks:

# 1. Check GitHub Actions for build errors
# 2. Revert to last working commit:
git log --oneline
git revert <bad-commit-hash>
git push

# 3. Or restore specific file:
git checkout HEAD~1 path/to/file
git commit -m "Restore working version"
git push

Security & Best Practices

What’s Secure

  • ✅ Static site (no database to hack)
  • ✅ HTTPS enforced (GitHub provides free SSL)
  • ✅ No user input (no injection vulnerabilities)
  • ✅ External links use rel="noopener noreferrer"
  • ✅ No sensitive data in repository

Best Practices

  • ✅ Keep images compressed (<500KB)
  • ✅ Write semantic HTML in content
  • ✅ Use proper heading hierarchy (H2 → H3 → H4)
  • ✅ Add alt text to images
  • ✅ Test on mobile devices
  • ✅ Commit messages should be descriptive

Don’t Do This

  • ❌ Commit sensitive info (API keys, passwords)
  • ❌ Use uncompressed images (slows load time)
  • ❌ Edit files directly on GitHub web interface (error-prone)
  • ❌ Push without testing locally (if you have Jekyll installed)

Technical Debt & Future Improvements

Known Limitations

  1. No search functionality - Consider adding Jekyll search plugin
  2. No pagination - Will need it after ~30 articles
  3. No RSS reader count - Can’t track subscribers
  4. Manual featured posts - Could automate based on views/tags
  5. No related articles - Could add based on tags/category

Enhancement Ideas

Easy to add later:

  • Newsletter signup (Mailchimp, Substack)
  • Social share buttons
  • Reading time estimates (already calculated, just display)
  • “Popular articles” based on manual curation
  • Archive by year/month

Medium complexity:

  • Search functionality (Jekyll plugins available)
  • Comments (Disqus, utterances)
  • Related posts algorithm
  • Table of contents for long articles
  • Author bio box in articles

Complex:

  • Multiple authors
  • Draft/publish workflow
  • Scheduled posts
  • A/B testing
  • Analytics dashboard

Browser Compatibility

Tested & Working

  • ✅ Chrome/Edge (Chromium) 90+
  • ✅ Firefox 88+
  • ✅ Safari 14+
  • ✅ Mobile Safari (iOS 14+)
  • ✅ Chrome Mobile (Android)

CSS Features Used

  • CSS Grid (99%+ browser support)
  • Flexbox (99%+ support)
  • CSS Custom Properties (98%+ support)
  • CSS Animations (99%+ support)

JavaScript Features

  • ES6 Arrow functions
  • const/let
  • Template literals
  • RequestAnimationFrame
  • LocalStorage

No polyfills needed for modern browsers (2020+)

File Size Budget

Current sizes:

  • main.css: ~25KB (unminified)
  • theme.js: ~6KB (unminified)
  • HTML per page: ~10-15KB
  • Fonts (Google CDN): ~30KB (cached)

Per article page load:

  • Without images: ~70KB
  • With images: ~200-500KB (depends on image optimization)

Recommendation: Keep article images under 300KB each

Questions & Support

Getting Help

For Jekyll issues:

  • Official docs: https://jekyllrb.com/docs/
  • GitHub Pages docs: https://docs.github.com/en/pages

For Markdown:

  • Guide: https://www.markdownguide.org/
  • Cheatsheet: See ADMIN_GUIDE.md

For Git:

  • Guide: https://git-scm.com/docs
  • Interactive tutorial: https://learngitbranching.js.org/

Debugging Tips

Always check:

  1. GitHub Actions tab (build status)
  2. Browser console (F12) for JavaScript errors
  3. Network tab for failed resource loads
  4. _config.yml syntax (YAML is picky about indentation)

Common mistakes:

  • Wrong date format in filename
  • Missing closing quotes in front matter
  • Incorrect category slug
  • Image path doesn’t start with /
  • YAML indentation with tabs instead of spaces

Changelog

Version History

v1.0 - December 28, 2025

  • Initial launch
  • Jekyll 4.3 + GitHub Pages
  • Custom domain configured
  • Sticky header with opacity crossfade
  • Dark mode toggle
  • 4-column responsive grid
  • Ultra-compact spacing
  • Magazine-style design

End of Developer Guide

For content publishing instructions, see ADMIN_GUIDE.md