Jekyll Implementation Details

This document details how Jekyll is configured and used in the IT-Journey repository, including collections, plugins, themes, and build processes.

Jekyll Version & Configuration

Version Information

Configuration Files

_config.yml (Production)

Main configuration file for production builds and GitHub Pages deployment.

Key Settings:

remote_theme: "bamr87/zer0-mistakes"
markdown: kramdown
permalink: pretty
collections_dir: pages

_config_dev.yml (Development)

Development-specific overrides for local testing.

Usage:

bundle exec jekyll serve --config _config_dev.yml

Collections System

Jekyll collections organize content into logical groups with specific purposes and URL structures.

Collection Definitions

All collections are stored in the pages/ directory (defined by collections_dir: pages).

_posts Collection

Traditional Jekyll blog posts.

posts:
  output: true
  permalink: /:collection/:year/:month/:day/:slug/

URL Pattern: /posts/2025/10/13/my-post-title/

Purpose: Blog articles, tutorials, journal entries, technical write-ups

Frontmatter Requirements: title, date, layout, tags (recommended)

_docs Collection

Learning resources and reference documentation.

docs:
  output: true
  permalink: /:collection/:categories/:name/

URL Pattern: /docs/jekyll/jekyll-config/ (if categories: jekyll)

Purpose: External tool documentation, reference guides, educational resources

Note: Distinct from developer docs in /docs/ directory

_quests Collection

Gamified learning experiences with progressive difficulty.

quests:
  output: true
  permalink: /:collection/:categories/:name/

URL Pattern: /quests/automation/link-health-guardian/

Purpose: Hands-on projects, skill-building exercises, themed learning adventures

Special Features:

_notebooks Collection

Jupyter notebooks and interactive code content.

notebooks:
  output: true
  permalink: /:collection/:path/:name/

URL Pattern: /notebooks/data-science/analysis-example/

Purpose: Runnable code examples, data analysis, interactive tutorials

Format Support: .ipynb, .md (converted notebooks)

_notes Collection

Personal development notes and work-in-progress content.

notes:
  output: true
  permalink: /:collection/:path/:name/

URL Pattern: /notes/development/feature-idea/

Purpose: Draft content, research notes, experimental ideas

Visibility: May be excluded from main navigation

_about Collection

Information about the IT-Journey project.

about:
  output: true
  permalink: /:collection/:categories/:name/

URL Pattern: /about/features/mermaid-diagrams/

Purpose: Project information, site documentation, team pages

_quickstart Collection

Quick reference guides for rapid learning.

quickstart:
  output: true
  permalink: /:collection/:name/

URL Pattern: /quickstart/jekyll-setup/

Purpose: Fast onboarding, cheat sheets, common task references

_hobbies Collection

Personal hobby-related content.

hobbies:
  output: true
  permalink: /:collection/:categories/:name/

URL Pattern: /hobbies/woodworking/project-name/

Purpose: Non-technical personal projects

Collection Defaults

Default frontmatter values for each collection are set in _config.yml:

defaults:
  # All files
  - scope:
      path: ""
    values:
      layout: root
      author_profile: false
      read_time: true
      comments: false
      share: true
      related: true

  # Posts-specific
  - scope:
      path: pages/_posts
    values:
      layout: journals
      sidebar:
        nav: dynamic

  # Docs-specific
  - scope:
      path: pages/_docs
    values:
      layout: default
      sidebar:
        nav: docs

  # Quests-specific
  - scope:
      path: pages/_quests
    values:
      layout: default
      sidebar:
        nav: dynamic

Plugins

Enabled Plugins

Plugins are defined in _config.yml and Gemfile:

plugins:
  - github-pages
  - jekyll-remote-theme
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-paginate
  - jekyll-relative-links

github-pages

Meta-gem that includes all GitHub Pages-compatible Jekyll plugins.

jekyll-remote-theme

Enables using themes hosted on GitHub without installing them locally.

jekyll-feed

Generates an Atom feed for posts at /feed.xml.

jekyll-sitemap

Creates sitemap.xml for search engines.

jekyll-seo-tag

Adds meta tags for SEO and social media sharing.

jekyll-paginate

Provides pagination for posts.

paginate: 10
paginate_path: "/pages/:num/"

Converts relative links to proper Jekyll links.

Markdown Processing

Kramdown Configuration

markdown: kramdown

kramdown:
  input: GFM  # GitHub Flavored Markdown
  header_offset: 0
  toc_levels: 1..6

Features:

Syntax Highlighting

Handled by Rouge (included in github-pages gem):

Usage in Markdown:

```python
def hello_world():
    print("Hello, IT-Journey!")
```

Theme Integration

Remote Theme: zer0-mistakes

Repository: https://github.com/bamr87/zer0-mistakes

Theme Structure:

Local Overrides

Local files take precedence over theme files:

Override Priority:

  1. Local _layouts/javascript.html → Used
  2. Theme _layouts/default.html → Used (if no local version)
  3. Local assets/css/custom.css → Appended to theme CSS
  4. Local _includes/ → Override or extend theme includes

Theme Configuration

theme_skin: "dark"  # Options: air, aqua, contrast, dark, dirt, neon, mint, plum, sunrise

theme_color:
  main: #007bff
  secondary: #6c757d
  # ... additional color definitions

Layouts

Available Layouts

From Theme (zer0-mistakes)

Local Custom Layouts

Layout Hierarchy

root.html (theme)
└── default.html (theme)
    ├── journals.html (theme)
    ├── collection.html (theme)
    └── javascript.html (local)

Layout Usage

Specified in frontmatter:

---
layout: journals
---

Or via collection defaults in _config.yml.

Includes

Theme Includes

Provided by zer0-mistakes theme (partial list):

Local Custom Includes

Located in _includes/:

Using Includes

In layouts or content:

<!-- Direct Content Statistics Template -->
<div class="content-stats">
  <h3>Content Overview</h3>
  <p><strong>Total Posts:</strong> 70+ articles covering technical topics</p>
  <p><strong>Categories:</strong> 10+ major domains including DevOps, Security, Programming</p>
  <p><strong>Active Learning:</strong> Continuously updated with new content</p>
</div>

Data Files

Located in _data/, accessible via site.data:

_data/navigation/main.yml:

- title: "About"
  url: /about/
- title: "Quests"
  url: /quests/
- title: "Docs"
  url: /docs/

Access in templates:


  <a href="/quickstart">Quick-Start</a>

  <a href="/posts">Journey</a>

  <a href="/docs/">Library</a>

  <a href="/notes">Notebook</a>

  <a href="/about/">About</a>

Other Data Files

Assets & SCSS

SCSS Compilation

Jekyll compiles SCSS to CSS automatically:

Source: assets/css/main.scss

---
# Front matter required for Jekyll processing
---

@import "custom";
@import "theme-variables";
// ... additional imports

Output: _site/assets/css/main.css

Asset Pipeline

  1. SCSS files in _sass/ are imported
  2. Theme SCSS is imported automatically
  3. Local overrides applied
  4. Compiled to single CSS file
  5. Served from _site/assets/

Custom Styles

Located in assets/css/custom.css for direct CSS or _sass/custom.scss for SCSS.

Build Process

Local Development Build

# Standard build
bundle exec jekyll build

# Development server with auto-reload
bundle exec jekyll serve --config _config_dev.yml --livereload

# Production build
JEKYLL_ENV=production bundle exec jekyll build

GitHub Pages Build

Automatic on push to main branch:

  1. GitHub Actions triggered
  2. Jekyll build with github-pages gem
  3. Output deployed to GitHub Pages
  4. Available at configured URL

Docker Build

# Start development server
docker-compose up

# Build only
docker-compose run jekyll bundle exec jekyll build

Environment Variables

JEKYLL_ENV

Controls build environment:

Usage:


  <!-- Production-only code -->

Custom Environment Variables

Defined in _config.yml and accessible via site.*:

url: 'https://it-journey.dev'
baseurl: ""
port: 4002

Special Features

Mermaid Diagrams

Enabled via frontmatter:

---
mermaid: true
---

Then use in content:

<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
</div>

MathJax Support

Enabled via frontmatter:

---
mathjax: true
---

Then use LaTeX syntax:

$a^2 + b^2 = c^2$

$$\begin{equation}
E = mc^2
\end{equation}$$

Comments (Giscus)

GitHub Discussions-based comments:

gisgus:
  enabled: true
  data-repo-id: "MDEwOlJlcG9zaXRvcnkyODM4MjI1NzM"
  data-category-id: "DIC_kwDOEOrJ7c4CAn8D"

Performance Optimizations

Incremental Builds

bundle exec jekyll serve --incremental

Only rebuilds changed files (experimental).

Exclude from Build

In _config.yml:

exclude:
  - .sass-cache/
  - .jekyll-cache/
  - node_modules/
  - vendor/
  - Gemfile.lock

Caching

Jekyll caches:

Delete cache directories to force full rebuild.

Troubleshooting

Common Build Issues

Issue: Bundle install fails

# Solution: Update bundler
gem update bundler
bundle install

Issue: Port already in use

# Solution: Use different port
bundle exec jekyll serve --port 4003

Issue: Theme not loading

# Solution: Clear cache and rebuild
rm -rf .jekyll-cache _site
bundle exec jekyll serve

Debug Mode

# Verbose output
bundle exec jekyll serve --verbose

# Show configuration
bundle exec jekyll serve --config _config_dev.yml --verbose

Best Practices

Configuration

Collections

Performance

Theme Customization

Additional Resources

Last Updated: 2025-10-13
Version: 1.0.0