class GitHubPages::Configuration

Sets and manages Jekyll configuration defaults and overrides

Constants

CONFIGS_WITH_METHODS

These configuration settings have corresponding instance variables on Jekyll::Site and need to be set properly when the config is updated.

DEFAULTS

Default, user overwritable options

DEFAULT_PLUGINS

Backward compatability of constants

DEVELOPMENT_PLUGINS
OVERRIDES

Options which GitHub Pages sets, regardless of the user-specified value

The following values are also overridden by GitHub Pages, but are not overridden locally, for practical purposes:

  • source

  • destination

  • jailed

  • verbose

  • incremental

  • GH_ENV

PLUGIN_WHITELIST
PRODUCTION_DEFAULTS

User-overwritable defaults used only in production for practical reasons

THEMES

Public Class Methods

defaults_for_env() click to toggle source
# File lib/github-pages/configuration.rb, line 89
def defaults_for_env
  defaults = development? ? DEFAULTS : PRODUCTION_DEFAULTS
  Jekyll::Utils.deep_merge_hashes Jekyll::Configuration::DEFAULTS, defaults
end
development?() click to toggle source
# File lib/github-pages/configuration.rb, line 85
def development?
  Jekyll.env == "development"
end
disable_whitelist?() click to toggle source
# File lib/github-pages/configuration.rb, line 81
def disable_whitelist?
  development? && !ENV["DISABLE_WHITELIST"].to_s.empty?
end
effective_config(user_config) click to toggle source

Given a user's config, determines the effective configuration by building a user configuration sandwhich with our overrides overriding the user's specified values which themselves override our defaults.

Returns the effective Configuration

Note: this is a highly modified version of Jekyll#configuration

# File lib/github-pages/configuration.rb, line 101
def effective_config(user_config)
  # Merge user config into defaults
  config = Jekyll::Utils.deep_merge_hashes(defaults_for_env, user_config)
    .fix_common_issues
    .add_default_collections

  # Allow theme to be explicitly disabled via "theme: null"
  config["theme"] = user_config["theme"] if user_config.key?("theme")

  migrate_theme_to_remote_theme(config)
  exclude_cname(config)

  # Merge overwrites into user config
  config = Jekyll::Utils.deep_merge_hashes config, OVERRIDES

  restrict_and_config_markdown_processor(config)

  configure_plugins(config)

  config
end
processed(site) click to toggle source
# File lib/github-pages/configuration.rb, line 77
def processed(site)
  site.instance_variable_set :@_github_pages_processed, true
end
processed?(site) click to toggle source
# File lib/github-pages/configuration.rb, line 73
def processed?(site)
  site.instance_variable_get(:@_github_pages_processed) == true
end
set(site) click to toggle source

Set the site's configuration. Implemented as an `after_reset` hook. Equivalent set! function contains the code of interest. This function guards against double-processing via the value in processed.

# File lib/github-pages/configuration.rb, line 126
def set(site)
  return if processed? site

  debug_print_versions
  set!(site)
  processed(site)
end
set!(site) click to toggle source

Set the site's configuration with all the proper defaults and overrides. Should be called by set to protect against multiple processings.

# File lib/github-pages/configuration.rb, line 136
def set!(site)
  site.config = effective_config(site.config)
end

Private Class Methods

configure_plugins(config) click to toggle source

Requires default plugins and configures whitelist in development

# File lib/github-pages/configuration.rb, line 173
def configure_plugins(config)
  # Ensure we have those gems we want.
  config["plugins"] = Array(config["plugins"]) | DEFAULT_PLUGINS

  # To minimize errors, lazy-require jekyll-remote-theme if requested by the user
  config["plugins"].push("jekyll-remote-theme") if config.key? "remote_theme"

  return unless development?

  if disable_whitelist?
    config["whitelist"] = config["whitelist"] | config["plugins"]
  end

  config["whitelist"] = config["whitelist"] | DEVELOPMENT_PLUGINS
end
debug_print_versions() click to toggle source

Print the versions for github-pages and jekyll to the debug stream for debugging purposes. See by running Jekyll with '–verbose'

# File lib/github-pages/configuration.rb, line 191
def debug_print_versions
  Jekyll.logger.debug "GitHub Pages:", "github-pages v#{GitHubPages::VERSION}"
  Jekyll.logger.debug "GitHub Pages:", "jekyll v#{Jekyll::VERSION}"
end
exclude_cname(config) click to toggle source

If the user's 'exclude' config is the default, also exclude the CNAME

# File lib/github-pages/configuration.rb, line 166
def exclude_cname(config)
  return unless config["exclude"].eql? Jekyll::Configuration::DEFAULTS["exclude"]

  config["exclude"].concat(DEFAULTS["exclude"])
end
migrate_theme_to_remote_theme(config) click to toggle source

If the user has set a 'theme', then see if we can automatically use remote theme instead.

# File lib/github-pages/configuration.rb, line 161
def migrate_theme_to_remote_theme(config)
  # This functionality has been rolled back due to complications with jekyll-remote-theme.
end
restrict_and_config_markdown_processor(config) click to toggle source

Ensure we're using Kramdown or GFM. Force to Kramdown if neither of these.

This can get called multiply on the same config, so try to be idempotentish.

# File lib/github-pages/configuration.rb, line 147
def restrict_and_config_markdown_processor(config)
  config["markdown"] = "kramdown" unless \
    %w(kramdown gfm commonmarkghpages).include?(config["markdown"].to_s.downcase)

  return unless config["markdown"].to_s.casecmp("gfm").zero?

  config["markdown"] = "CommonMarkGhPages"
  config["commonmark"] = {
    "extensions" => %w(table strikethrough autolink tagfilter),
    "options" => %w(footnotes),
  }
end