configuration

Jekyll Site Configuration Guide

Jekyll Site Configuration Guide

Overview

The _config.yml file is the central configuration file for a Jekyll website. It controls site-wide settings, plugins, collections, pagination, and other critical aspects of your site’s behavior.

Site Identity and URL Configuration

baseurl: "" 
url: "https://snowlake-jekyll-v2.pages.dev"
permalink: "/:title"

Parameters

  • baseurl: Subpath of your site (e.g., /blog)

    • Used when your site is hosted in a subdirectory
    • Leave empty for root-level deployment

  • url: Base hostname and protocol

    • Defines the complete base URL for your site
    • Important for generating absolute URLs and SEO

  • permalink: URL structure for blog posts

    • :title generates URLs based on the post’s title
    • Alternatives:
      • /:year/:month/:day/:title/
      • /:categories/:title/

Plugins Configuration

plugins:
  - jekyll-feed
  - jekyll-paginate-v2
  - jekyll-archives

Installed Plugins

  1. jekyll-feed: Generates an RSS/Atom feed for your posts
  2. jekyll-paginate-v2: Advanced pagination for Jekyll
  3. jekyll-archives: Automatic archive page generation

Collections Definition

collections:
  authors:
    output: true
  shop_items:
    output: true
    permalink: /shop/:name
  portfolio:
    output: true
    permalink: /portfolio/:name

Collection Types

  • authors: Author profile pages
    • output: true generates individual pages for each author
  • shop_items: Product pages
    • Custom permalink structure
  • portfolio: Portfolio item pages
    • Generates individual portfolio pages

Collection Properties

  • output: Determines if collection items generate standalone pages
  • permalink: Custom URL structure for collection items

Pagination Configuration

pagination:
  enabled: true
  debug: true
  collection: 'posts'
  per_page: 5
  permalink: '/page/:num/'
  sort_field: 'date'
  sort_reverse: true

Key Pagination Settings

  • enabled: Turns pagination on/off
  • debug: Enables pagination debugging
  • collection: Source collection for pagination
  • per_page: Number of items per page
  • permalink: URL structure for paginated pages
  • sort_field: Field used for sorting posts
  • sort_reverse: Reverses post order

Advanced Pagination Options

  • trail: Controls pagination trail display
  • limit: Limits total paginated pages
  • category/tag: Optional filtering
  • locale: Internationalization support

Jekyll Archives Configuration

jekyll-archives:
  enabled:
    - tags
    - categories
  layouts:
    tag: tag
    category: category
  permalinks:
    tag: '/tag/:name/'
    category: '/category/:name/'

Archive Generation

  • Automatically creates archive pages for tags and categories
  • Specifies custom layouts for tag and category pages
  • Defines custom permalink structures

Feed Configuration

feed:
  collections:
    posts:
      path: "/index.xml"

RSS/Atom Feed Settings

  • Generates XML feed for blog posts
  • Customizable feed path

Syntax Highlighting

highlighter: rouge
  • Uses Rouge for code syntax highlighting
  • Supports multiple programming languages

Best Practices

  1. Keep _config.yml well-organized
  2. Use meaningful permalink structures
  3. Enable only necessary plugins
  4. Configure collections thoughtfully
  5. Test pagination and archive generation

Troubleshooting

  • Restart Jekyll server after config changes
  • Check console for plugin-related warnings
  • Validate YAML syntax
  • Use jekyll build --verbose for detailed output

Performance Considerations

  • Limit the number of plugins
  • Use pagination to reduce page load times
  • Optimize collection definitions
  • Minimize complex permalink structures

Version Compatibility

Tested with:

  • Jekyll 4.x
  • jekyll-paginate-v2 1.9.x
  • jekyll-archives 2.2.x

Note: Always check plugin compatibility and Jekyll version requirements.