Skip to content

Jekyll in IT-Journey

This section contains Jekyll documentation specific to how IT-Journey implements and uses Jekyll as its static site generator.

About This Documentation

Purpose: Educational resources for learning how IT-Journey uses Jekyll's features, specifically: - Configuration options used in this repository - Liquid templating as implemented in IT-Journey - Frontmatter structure and CMS approach - Mermaid diagrams integration - MathJax mathematical notation - Jekyll configuration reference

Note: For technical developer documentation about repository structure and contribution workflows, see the docs/ directory in the repository root.

Jekyll in IT-Journey

IT-Journey is a static site generator powered by Jekyll {{ site.data.powered_by[1].version }} running on Ruby {{ site.data.powered_by[0].version }}.

Key Features

  • Collections System: Organizing content into _posts, _docs, _quests, _notebooks, _notes, _about, and _quickstart
  • Remote Theme: Using the zer0-mistakes theme
  • GitHub Pages: Automated deployment via GitHub Pages
  • Markdown Processing: GitHub Flavored Markdown via Kramdown
  • Plugins: Jekyll plugins for SEO, feeds, sitemaps, and more

Prerequisites

Jekyll requires the following:

  • Ruby version {{ site.data.ruby.min_version }} or higher
  • RubyGems
  • GCC and Make

See the Development Environment Setup guide for detailed installation instructions.

Available Documentation

Configuration

Templating

Rich Content

🎯 New: Mermaid Auto-Detection

Zero Configuration Required! The zer0-mistakes theme now automatically detects and renders Mermaid diagrams.

Quick Usage

Simply use standard markdown code fences - no front matter needed:

```mermaid
graph TD;
    A[Start] --> B[End];
```

Benefits

  • ✅ No configuration - just use ```mermaid blocks
  • ✅ Better performance - library loads only when needed
  • ✅ Impossible to forget - automatic detection
  • ✅ GitHub Pages compatible - works everywhere

Learn more → • Migration guide →

Quick Start

Local Development

# Clone the repository
git clone https://github.com/bamr87/it-journey.git
cd it-journey

# Install dependencies
bundle install

# Start development server
bundle exec jekyll serve --config _config_dev.yml

# Access at http://localhost:4002

Creating Content

# Create a new post
touch pages/_posts/2025-10-13-my-new-post.md

# Add frontmatter
cat > pages/_posts/2025-10-13-my-new-post.md << 'EOF'
---
title: "My New Post"
description: "Brief description"
date: 2025-10-13T00:00:00.000Z
categories:
  - development
tags:
  - jekyll
---

# My New Post

Content goes here...
EOF

IT-Journey Specific Implementation

Collections Structure

IT-Journey uses Jekyll collections extensively:

collections:
  posts:    # Blog posts and journals
  docs:     # Learning resources and references
  quests:   # Gamified learning experiences
  notebooks: # Jupyter notebooks
  notes:    # Personal development notes
  about:    # About pages and site information
  quickstart: # Quick reference guides

Each collection has specific frontmatter requirements and URL patterns. See Frontmatter Standards for details.

Theme Integration

IT-Journey uses the zer0-mistakes remote theme:

remote_theme: "bamr87/zer0-mistakes"

Local files override theme files, allowing customization while maintaining theme updates.

Build Process

Development: 

bundle exec jekyll serve --config _config_dev.yml

Production: 

JEKYLL_ENV=production bundle exec jekyll build

Docker: 

docker-compose up

Troubleshooting

Common Issues

Port Already in Use 

# Find and kill process on port 4002
lsof -i :4002
kill -9 <PID>

# Or use different port
bundle exec jekyll serve --port 4003

Build Fails 

# Check for errors
bundle exec jekyll build --verbose

# Run diagnostics
bundle exec jekyll doctor

Missing Dependencies 

# Update gems
bundle update

# Reinstall
bundle install

Additional Resources

Developer Documentation

External Resources

Support

Last Updated: 2025-10-13