Jekyll Blog Style Guide

Comprehensive style guide for maintaining consistency across the Jekyll blog.

🎨 Design System

Color Palette

// Primary Colors
--primary-color: #0074d9;      // Main brand blue
--primary-hover: #0056b3;      // Darker blue for hover states
--secondary-color: #2c3e50;    // Dark slate for secondary elements
--accent-color: #e74c3c;       // Red accent for highlights

// Text Colors
--text-primary: #222;          // Main text
--text-secondary: #666;        // Secondary text
--text-muted: #999;           // Muted/disabled text
--text-inverse: #fff;         // White text for dark backgrounds

// Background Colors
--bg-primary: #fff;           // Main background
--bg-secondary: #f8f8f8;      // Secondary background
--bg-accent: #f0f8ff;         // Light blue accent background
--border-color: #eee;         // Standard borders
--border-light: #f5f5f5;      // Light borders

Typography Scale

// Font Sizes (responsive)
--font-size-xs: 0.75rem;      // 12px
--font-size-sm: 0.875rem;     // 14px
--font-size-base: 1rem;       // 16px
--font-size-lg: 1.125rem;     // 18px
--font-size-xl: 1.25rem;      // 20px
--font-size-2xl: 1.5rem;      // 24px
--font-size-3xl: 1.75rem;     // 28px
--font-size-4xl: 2rem;        // 32px
--font-size-5xl: 2.5rem;      // 40px

Spacing System

// Consistent spacing scale
--space-xs: 0.25rem;   // 4px
--space-sm: 0.5rem;    // 8px
--space-md: 1rem;      // 16px
--space-lg: 1.5rem;    // 24px
--space-xl: 2rem;      // 32px
--space-2xl: 3rem;     // 48px
--space-3xl: 4rem;     // 64px

Border Radius

--radius-sm: 3px;      // Small radius for tags, badges
--radius-md: 4px;      // Standard radius for buttons, inputs
--radius-lg: 8px;      // Large radius for cards, sections
--radius-xl: 12px;     // Extra large for hero sections
--radius-full: 50%;    // Circular elements

📝 Content Guidelines

Writing Style

Tone: Professional but approachable
Voice: First person when sharing experiences, third person for tutorials
Clarity: Use simple, direct language
Structure: Lead with the most important information

Post Structure

---
title: "Clear, Descriptive Title (Max 60 chars)"
description: "Brief description for SEO (120-160 chars)"
date: 2024-01-01
tags: [java, spring-boot, tutorial]
series: "Series Name" # Optional
comments: true # Optional, defaults to true
image: "/public/images/post-image.png" # Optional
---

# Post Title

Brief introduction paragraph that explains what the reader will learn.

<!-- more --> <!-- Excerpt separator -->

## Main Content

### Subsections

Use H3 for subsections under main topics.

#### Code Examples

\```java
public class Example {
    // Well-commented, working code
}
\```

## Conclusion

Summary of key takeaways and next steps.

Image Guidelines

Alt Text: Always provide descriptive alt text
Lazy Loading: Use loading="lazy" for images below the fold
Responsive: Use the responsive image include when possible
Optimization: Images should be under 100KB when possible

<!-- Preferred: Use responsive image include -->

<figure class="responsive-image">
  <img
    src="/public/images/example.png"
    alt="Descriptive alt text"
    loading="lazy"
    sizes="(max-width: 768px) 100vw, 768px"
    
  />
  
    <figcaption>Optional caption</figcaption>
  
</figure>

<!-- Standard: With lazy loading -->
![Alt text](path/to/image.png){:loading="lazy"}

🎯 Component Usage

Buttons

<!-- Primary action -->
<a href="#" class="btn btn-primary">Primary Action</a>

<!-- Secondary action -->
<a href="#" class="btn btn-secondary">Secondary Action</a>

<!-- Outline style -->
<a href="#" class="btn btn-outline">Learn More</a>

<!-- Automatic inclusion in posts -->






<div class="social-sharing">
  <div class="social-sharing-header">
    <h3 class="social-sharing-title">
      <span class="sharing-icon">📤</span>
      Share this post
    </h3>
  </div>

  <div class="social-sharing-buttons">
    <!-- Twitter -->
    <a href="https://twitter.com/intent/tweet?text=Jekyll+Blog+Style+Guide&url=https%3A%2F%2Fcarloschac.in%2Fclaudedocs%2FSTYLE_GUIDE%2F&via=CarlosChacin"
       class="social-share-btn twitter-share"
       target="_blank"
       rel="noopener noreferrer"
       aria-label="Share on Twitter">
      <span class="share-icon">🐦</span>
      <span class="share-text">Twitter</span>
    </a>

    <!-- LinkedIn -->
    <a href="https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fcarloschac.in%2Fclaudedocs%2FSTYLE_GUIDE%2F&title=Jekyll+Blog+Style+Guide&summary="
       class="social-share-btn linkedin-share"
       target="_blank"
       rel="noopener noreferrer"
       aria-label="Share on LinkedIn">
      <span class="share-icon">💼</span>
      <span class="share-text">LinkedIn</span>
    </a>

    <!-- Facebook -->
    <a href="https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fcarloschac.in%2Fclaudedocs%2FSTYLE_GUIDE%2F"
       class="social-share-btn facebook-share"
       target="_blank"
       rel="noopener noreferrer"
       aria-label="Share on Facebook">
      <span class="share-icon">📘</span>
      <span class="share-text">Facebook</span>
    </a>

    <!-- Reddit -->
    <a href="https://reddit.com/submit?url=https%3A%2F%2Fcarloschac.in%2Fclaudedocs%2FSTYLE_GUIDE%2F&title=Jekyll+Blog+Style+Guide"
       class="social-share-btn reddit-share"
       target="_blank"
       rel="noopener noreferrer"
       aria-label="Share on Reddit">
      <span class="share-icon">🔗</span>
      <span class="share-text">Reddit</span>
    </a>

    <!-- HackerNews -->
    <a href="https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fcarloschac.in%2Fclaudedocs%2FSTYLE_GUIDE%2F&t=Jekyll+Blog+Style+Guide"
       class="social-share-btn hackernews-share"
       target="_blank"
       rel="noopener noreferrer"
       aria-label="Share on Hacker News">
      <span class="share-icon">📰</span>
      <span class="share-text">HN</span>
    </a>

    <!-- Copy Link -->
    <button class="social-share-btn copy-link-btn"
            onclick="copyToClipboard('https://carloschac.in/claudedocs/STYLE_GUIDE/')"
            aria-label="Copy link to clipboard">
      <span class="share-icon">📋</span>
      <span class="share-text">Copy</span>
    </button>
  </div>

  <!-- Copy success message -->
  <div class="copy-success" id="copy-success" style="display: none;">
    <span class="success-icon">✅</span>
    Link copied to clipboard!
  </div>
</div>

<script>
function copyToClipboard(text) {
  if (navigator.clipboard && window.isSecureContext) {
    // Modern clipboard API
    navigator.clipboard.writeText(text).then(function() {
      showCopySuccess();
    }).catch(function(err) {
      fallbackCopyToClipboard(text);
    });
  } else {
    // Fallback for older browsers
    fallbackCopyToClipboard(text);
  }
}

function fallbackCopyToClipboard(text) {
  var textArea = document.createElement("textarea");
  textArea.value = text;
  textArea.style.top = "0";
  textArea.style.left = "0";
  textArea.style.position = "fixed";
  document.body.appendChild(textArea);
  textArea.focus();
  textArea.select();

  try {
    var successful = document.execCommand('copy');
    if (successful) {
      showCopySuccess();
    }
  } catch (err) {
    console.error('Copy failed:', err);
  }

  document.body.removeChild(textArea);
}

function showCopySuccess() {
  var successMsg = document.getElementById('copy-success');
  successMsg.style.display = 'block';
  setTimeout(function() {
    successMsg.style.display = 'none';
  }, 2000);
}
</script>

Author Bio

<!-- Full bio (for About page) -->

<div class="author-bio">
  <div class="author-bio-container">
    
    <div class="author-avatar">
      <img src="https://github.com/cchacin.png?size=120"
           alt="Carlos Chacin's profile picture"
           loading="lazy"
           class="avatar-image">
    </div>
    
    <div class="author-content">
      <div class="author-header">
        <h3 class="author-name">Carlos Chacin</h3>
        
      </div>

      <div class="author-description">
        
          <p>Software engineer sharing experiences in Java, cloud technologies, and modern development practices.
             Passionate about clean code, architecture, and continuous learning.</p>
        
      </div>

      <div class="author-social">
        <h4 class="social-title">Follow me:</h4>
        <div class="social-links">
          
          <a href="mailto:cchacin@gmail.com"
             class="social-link email"
             aria-label="Send email">
            <span class="social-icon">📧</span>
            <span class="social-text">Email</span>
          </a>
          
        </div>
      </div>
      
      <div class="author-stats">
        <div class="stats-grid">
          <div class="stat-item">
            <span class="stat-number">15</span>
            <span class="stat-label">Posts</span>
          </div>
          <div class="stat-item">
            <span class="stat-number">44</span>
            <span class="stat-label">Topics</span>
          </div>
          <div class="stat-item">
            <span class="stat-number">
              
              12k
            </span>
            <span class="stat-label">Words</span>
          </div>
        </div>
      </div>
      
    </div>
  </div>

</div>

<!-- Compact bio (for posts) -->

<div class="author-bio author-bio-compact">
  <div class="author-bio-container">
    
    <div class="author-content">
      <div class="author-header">
        <h3 class="author-name">Carlos Chacin</h3>
        
      </div>

      <div class="author-description">
        
          <p>Software engineer sharing experiences in Java, cloud technologies, and modern development practices.
             Passionate about clean code, architecture, and continuous learning.</p>
        
      </div>

      <div class="author-social">
        <h4 class="social-title">Follow me:</h4>
        <div class="social-links">
          
          <a href="mailto:cchacin@gmail.com"
             class="social-link email"
             aria-label="Send email">
            <span class="social-icon">📧</span>
            <span class="social-text">Email</span>
          </a>
          
        </div>
      </div>
      
    </div>
  </div>

  <div class="author-cta">
    <a href="/about" class="author-cta-link btn btn-outline">
      Learn more about me
    </a>
  </div>
  
</div>

<!-- Default -->

<!-- Custom -->

<!-- Inline version -->

Comments

<!-- Automatic inclusion in posts -->

🔧 Technical Standards

File Organization

├── _includes/           # Reusable components
│   ├── author_bio.html
│   ├── comments.html
│   ├── newsletter_signup.html
│   ├── responsive_image.html
│   └── social_sharing.html
├── _layouts/           # Page templates
├── _posts/            # Blog posts (YYYY-MM-DD-title.md)
├── claudedocs/        # Documentation and guides
├── public/
│   ├── css/           # Stylesheets
│   ├── images/        # Image assets
│   └── js/            # JavaScript files
└── scripts/           # Utility scripts

Naming Conventions

Files: Use kebab-case (post-title.md)
CSS Classes: Use kebab-case (nav-card, author-bio)
CSS Variables: Use kebab-case (--primary-color)
Jekyll Variables: Use snake_case (post_title)

Code Standards

Indentation: 2 spaces for HTML/CSS/SCSS, 4 spaces for JavaScript
Comments: Comment complex logic and component purposes
Accessibility: Always include ARIA labels and semantic HTML
Performance: Minimize CSS/JS, optimize images, use lazy loading

📱 Responsive Design

Breakpoints

@media (max-width: 480px)  { /* Mobile */ }
@media (max-width: 768px)  { /* Tablet */ }
@media (max-width: 1024px) { /* Small desktop */ }
@media (min-width: 1025px) { /* Large desktop */ }

Mobile-First Approach

Design for mobile first
Enhance for larger screens
Test on multiple devices
Ensure touch targets are minimum 44px

♿ Accessibility Standards

Required Elements

Alt Text: All images must have descriptive alt text
Headings: Proper heading hierarchy (H1 → H2 → H3)
Labels: Form inputs must have associated labels
Focus: Keyboard navigation must be functional
Color: Don’t rely solely on color to convey meaning
Contrast: Text must meet WCAG contrast requirements

ARIA Implementation

<!-- Navigation -->
<nav role="navigation" aria-label="Main navigation">

<!-- Main content -->
<main role="main">

<!-- Articles -->
<article role="article" aria-labelledby="post-title">

<!-- Skip links -->
<a href="#main-content" class="skip-link">Skip to main content</a>

🔍 SEO Best Practices

Meta Tags

<!-- Required in all pages -->
<title>Page Title (30-60 chars)</title>
<meta name="description" content="Description (120-160 chars)">

<!-- Open Graph -->
<meta property="og:title" content="Page Title">
<meta property="og:description" content="Description">
<meta property="og:image" content="Image URL">

<!-- Twitter Cards -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page Title">

Structured Data

All posts automatically include JSON-LD structured data for:

Article schema
Author information
Publishing dates
Organization details

URL Structure

Posts: /YYYY/MM/DD/post-title/
Pages: /page-name/
Tags: /tags/#tag-name
Series: /series/#series-name

🧪 Testing Checklist

Before Publishing

Content proofread and spell-checked
Images optimized and have alt text
Links work and open appropriately
Mobile responsive design tested
Accessibility validated
SEO meta tags complete

Quality Assurance

# Run quality tests
./scripts/test-site-quality.sh

# Run performance check
./scripts/performance-check.sh

# Optimize images if needed
./scripts/optimize-images.sh

🚀 Deployment

Pre-Deployment

Test locally with bundle exec jekyll serve
Run quality tests
Check for broken links
Validate HTML and CSS
Test on multiple browsers

Post-Deployment

Verify site loads correctly
Test critical user journeys
Check analytics setup
Validate sitemap and RSS feed
Monitor Core Web Vitals

🔄 Maintenance

Regular Tasks

Weekly: Review and respond to comments
Monthly: Update dependencies, check for broken links
Quarterly: Audit site performance and accessibility
Annually: Review and update style guide

Version Control

Use semantic commit messages
Create feature branches for major changes
Include Claude Code generation attribution in commits

📚 Resources

Tools

Documentation

This style guide is a living document. Update it as the site evolves and new patterns emerge.

Jekyll Blog Style Guide

Jekyll Blog Style Guide

🎨 Design System

Color Palette

Typography Scale

Spacing System

Border Radius

📝 Content Guidelines

Writing Style

Post Structure

Image Guidelines

🎯 Component Usage

Buttons

Social Sharing

Author Bio

Newsletter Signup

Comments

🔧 Technical Standards

File Organization

Naming Conventions

Code Standards

📱 Responsive Design

Breakpoints

Mobile-First Approach

♿ Accessibility Standards

Required Elements

ARIA Implementation

🔍 SEO Best Practices

Meta Tags

Structured Data

URL Structure

🧪 Testing Checklist

Before Publishing

Quality Assurance

🚀 Deployment

Pre-Deployment

Post-Deployment

🔄 Maintenance

Regular Tasks

Version Control

📚 Resources

Tools

Documentation