Jekyll Documentation

By Amr

Jekyll documentation specific to IT-Journey implementation

Estimated reading time: 3 minutes

Edit on GitHub

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 ** running on Ruby **.

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 ** or higher
  • RubyGems
  • GCC and Make

See the Development Environment Setup guide for detailed installation instructions.

Available Documentation

Configuration

Templating

Rich Content

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