Jekyll自定义集合无法在Ruby插件中调用的技术求助

Hey there, let's tackle this issue you're having with Jekyll custom collections not being accessible in your Ruby plugin—even though they show up fine on your site pages. I've run into similar quirks before, so let's break down the most likely fixes step by step:

1. Double-Check Your Collection Configuration in _config.yml #

First, make sure your collection is properly defined in your config file. Jekyll relies on this to register and load collections correctly. For example, if you have an authors collection:

collections:
  authors:
    output: true  # Optional, but ensures pages are generated
    permalink: /authors/:name/  # Optional, for clean URLs

• Key note: Jekyll uses plural collection names by default. So if your folder is _authors, your config should list authors (plural), and you'll access it as site.authors or site.collections['authors'] in your plugin.

2. Verify Your Hook's Execution Timing #

This is the most common culprit! Jekyll runs hooks at different stages of the build process, and if you're trying to access collections too early, they won't be loaded yet.

• If you're using a hook tied to :posts (like Jekyll::Hooks.register :posts, :pre_render), it only triggers for the default posts collection. To target all collections, use :documents instead:

  Jekyll::Hooks.register :documents, :pre_render do |document, payload|
    # This runs for every document in ALL collections (posts, authors, etc.)
    puts "Processing document from collection: #{document.collection.label}"
  end
  

• If you need to run code once after all collections are loaded, use the :site, :post_read hook—this stage ensures all documents from all collections are loaded into the site object:

  Jekyll::Hooks.register :site, :post_read do |site|
    # Access your custom collection here
    site.collections['authors'].docs.each do |author|
      puts "Found author: #{author.data['name']}"
    end
  end
  

Avoid hooks like :site, :after_init—they run before collections are parsed and loaded.

3. Ensure You're Accessing Collections Correctly in the Plugin #

Sometimes the shortcut site.authors might not work if there's a config quirk. Instead, use the more explicit path to access the collection's documents:

# Instead of site.authors (which is a shortcut for site.collections['authors'].docs)
site.collections['authors'].docs.each do |doc|
  # Work with the document data
end

This bypasses any potential issues with the auto-generated shortcut methods.

4. Check Your Collection Documents' Format #

Make sure your collection files are in the right place and have valid YAML front matter:

• Files must live in a folder named _[collection-name] (e.g., _authors for the authors collection).
• Each file needs a valid YAML front matter block at the top, like:

  ---
  name: Jane Smith
  bio: Loves writing about Jekyll and web development
  ---
  # Author Bio
  ...
  

If the front matter is malformed (missing dashes, invalid YAML), Jekyll won't recognize the file as part of the collection, so it won't show up in your plugin.

5. Test with a Minimal Plugin #

To rule out conflicts with other code, create a tiny test plugin to print collection details. Run jekyll build --verbose and check the console output:

Jekyll::Hooks.register :site, :post_read do |site|
  puts "\n=== Loaded Collections ==="
  site.collections.each do |name, collection|
    puts "- #{name}: #{collection.docs.size} documents"
  end
end

If your custom collection doesn't appear here, the issue is with how Jekyll is loading the collection (not your plugin code).

内容的提问来源于stack exchange，提问作者Kevin Rovers