imathis/octopress · error · SyntaxError

Error in tag 'include_array' - Valid syntax: include_array [

Error message

Error in tag 'include_array' - Valid syntax: include_array [array from _config.yml]

What it means

Raised at Liquid parse time by the include_array Jekyll plugin when the tag's markup does not match a single Liquid QuotedFragment (include_array.rb:15-21). The tag requires exactly one argument: the name of a top-level key in _config.yml that holds an array of partial paths (e.g. asides). The regex only fails when the argument is missing or consists solely of characters QuotedFragment excludes (commas, colons, bare quotes); a missing _config.yml key does NOT raise this, because render falls back to an empty array at line 34. Because it is a Liquid SyntaxError, the whole Jekyll build stops.

Source

Thrown at plugins/include_array.rb:20

# Author: Jason Woodward http://www.woodwardjd.com
# Description: Import files on your filesystem as specified in a configuration variable in _config.yml.  Mostly cribbed from Jekyll's include tag.
# Syntax: {% include_array variable_name_from_config.yml %}
#
# Example 1:
# {% include_array asides  %}
#
# _config.yml snippet:
# asides: [asides/twitter.html, asides/custom/my_picture.html]
#
module Jekyll

  class IncludeArrayTag < Liquid::Tag
    Syntax = /(#{Liquid::QuotedFragment}+)/
    def initialize(tag_name, markup, tokens)
      if markup =~ Syntax
        @array_name = $1
      else
        raise SyntaxError.new("Error in tag 'include_array' - Valid syntax: include_array [array from _config.yml]")
      end

      super
    end

    def render(context)
      includes_dir = File.join(context.registers[:site].source, '_includes')

      if File.symlink?(includes_dir)
        return "Includes directory '#{includes_dir}' cannot be a symlink"
      end

      rtn = ''
      (context.environments.first['site'][@array_name] || []).each do |file|
        if file !~ /^[a-zA-Z0-9_\/\.-]+$/ || file =~ /\.\// || file =~ /\/\./
          rtn = rtn + "Include file '#{file}' contains invalid characters or sequences"
        end

View on GitHub (pinned to 5717a50f4e)

Solutions

Add the argument: {% include_array asides %} — one bare word, no brackets or colons
Make sure that word is a top-level key in _config.yml whose value is an array of paths under _includes
Sweep every template for bare tags: grep -rnE 'include_array\s*%}' . and fix each hit
If you only need one partial, use Jekyll's built-in {% include file.html %} instead

Example fix

// before
{% include_array %}

// after
{% include_array asides %}

# _config.yml
asides: [asides/twitter.html, asides/custom/my_picture.html]

Defensive patterns

Strategy: validation

Validate before calling

# Fail fast before the build: find include_array tags whose argument cannot parse
QUOTED = /\A#{Liquid::QuotedFragment}+\z/
Dir.glob('**/*.{html,markdown,erb}').each do |path|
  File.read(path).scan(/\{%\s*include_array\s*(.*?)\s*%\}/m).flatten.each do |arg|
    warn "#{path}: {% include_array %} needs exactly one _config.yml array name" if arg.to_s !~ QUOTED
  end
end

Type guard

# Returns true when the markup include_array would accept
def valid_include_array_markup?(markup)
  markup.to_s =~ /\A#{Jekyll::IncludeArrayTag::Syntax}\z/ ? true : false
end

Try / catch

begin
  Liquid::Template.parse(source)
rescue SyntaxError => e
  if e.message.include?("include_array")
    abort "Template error: every {% include_array %} tag needs one _config.yml array key — #{e.message}"
  end
  raise
end

Prevention

Always give include_array exactly one bare argument: {% include_array asides %}
Keep the matching array key defined at the top level of _config.yml
Grep templates for bare tags before deploying: grep -rnE 'include_array\s*%}' _layouts _includes _posts
Prefer Jekyll's built-in {% include %} when you don't need a config-driven array of partials

When it happens

Trigger: Writing {% include_array %} with no argument; passing an argument made only of excluded punctuation such as {% include_array , %} or {% include_array : %}; leaving stray punctuation after a deleted variable name in a layout. The accepted form is one bare word after the tag name, e.g. {% include_array asides }.

Common situations: Hand-editing Octopress/Jekyll layouts and accidentally deleting the variable name; copy-pasting the usage example but leaving its placeholder unexpanded; migrating templates from Jekyll's built-in {% include %} tag and forgetting that include_array takes a _config.yml key, not a filename.

Related errors

AI-assisted analysis of imathis/octopress@5717a50f4e (2026-08-21). Data as JSON: /api/errors/09532df85a7b5cb4. Report an issue: GitHub.