Class: Bridgetown::Configuration::ConfigurationDSL

Inherits:
FrontMatter::RubyFrontMatter show all
Includes:
Refinements::Helper
Defined in:
bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Refinements::Helper

#refine

Methods inherited from FrontMatter::RubyFrontMatter

#each, #initialize, #key?, #to_h

Constructor Details

This class inherits a constructor from Bridgetown::FrontMatter::RubyFrontMatter

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(key, *value, &block) ⇒ Object

rubocop:disable Style/MissingRespondToMissing



135
136
137
138
139
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 135

def method_missing(key, *value, &block) # rubocop:disable Style/MissingRespondToMissing
  return get(key) if value.empty? && block.nil?

  set(key, value[0], &block)
end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



8
9
10
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 8

def context
  @context
end

Instance Method Details

#_in_require_denylist?(name) ⇒ Boolean

Returns:

  • (Boolean) 


208
209
210
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 208

def _in_require_denylist?(name)
  REQUIRE_DENYLIST.include?(name.to_sym)
end

#_run_builtins! ⇒ Object

Initializers that are part of the Bridgetown boot sequence. Site owners can override defaults by running any of these manually…init is no-op if the initializer was already run.



214
215
216
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 214

def _run_builtins!
  init :streamlined
end

#_setup_initializer(name:, require_gem:, require_initializer:) ⇒ Bridgetown::Configuration::Initializer

Returns:



197
198
199
200
201
202
203
204
205
206
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 197

def _setup_initializer(name:, require_gem:, require_initializer:)
  Bridgetown::PluginManager.require_gem(name) if require_gem && !_in_require_denylist?(name)

  if require_initializer
    init_file_name = File.join(@scope.root_dir, "config", "#{name}.rb")
    load(init_file_name) if File.exist?(init_file_name)
  end

  @scope.initializers[name.to_sym]
end

#additional_watch_paths(paths) ⇒ Object

Watch additional directories for reloads not normally covered by autoloader (relative to project root)

Parameters:

  • paths (Array<String>) 



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 270

#autoload_paths ⇒ Object

Add paths to the Zeitwerk autoloader. Use a config.defaults << "..." syntax or a more advanced hash config

Examples:

Add a new path for autoloading and eager load on boot

config.autoload_paths << {
  path: "loadme",
  eager: true
}



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 261

#base_path(url) ⇒ Object

Optionally host your site off a path, e.g. /blog

Parameters:

  • url (String) —
    • default: /



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 294

#builder(klass = nil) ⇒ void

This method returns an undefined value.

Used by plugins to register the provided Builder class, or alternatively register an “inline builder” by defining the class body in a block using the provided symbol as the class name.

Parameters:



106
107
108
109
110
111
112
113
114
115
116
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 106

def builder(klass = nil, &)
  return klass.register if klass.is_a?(Class) && klass < Bridgetown::Builder

  unless klass.is_a?(Symbol)
    raise "You must supply a constant symbol to register an inline builder"
  end

  Object.const_set(
    klass, Class.new(Bridgetown::Builder, &).tap(&:register)
  )
end

#defaults ⇒ Object

Use a config.defaults << {...} syntax to add front matter defaults

Examples:

Set a default layout for a collection

config.defaults << {
  scope: { collection: :docs },
  values: { layout: :default },
}



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 279

#destination(path) ⇒ Object

Change the directory where Bridgetown will write files

Parameters:

  • path (String) —
    • default: output



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 230

#except(*context) ⇒ void

This method returns an undefined value.

Do not execute the provided block for configuration if the current context matches the provided criteria.

Parameters:

  • context (Symbol) —

    supply one or more contexts for avoiding execution. Generally these are :static, :console, :rake, and :server



67
68
69
70
71
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 67

def except(*context, &)
  return if context.any? { _1 == @context }

  instance_exec(&)
end

#exclude(files_list) ⇒ Object

Exclude source directories and/or files from the build conversion

Parameters:

  • files_list (Array<String>) 



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 247

#fast_refresh(bool) ⇒ Object

Control the behavior of Bridgetown’s live reload functionality in development

Parameters:

  • bool (Boolean) —
    • default: true



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 243

#get(key) ⇒ Object 



141
142
143
144
145
146
147
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 141

def get(key)
  unless @data.key?(key)
    Bridgetown.logger.debug("Initializing:", "Uh oh, missing key `#{key}' in configuration")
  end

  super
end

#hook(owner, event, priority: Bridgetown::Hooks::DEFAULT_PRIORITY) {|obj| ... } ⇒ Object

Provides a wrapper around the register_one method of the Hooks class.

Parameters:

  • owner (Symbol) —

    name of the owner (:site, :resource, etc.)

  • event (Symbol) —

    name of the event (:pre_read, :post_render, etc.)

  • priority (Integer, Symbol) (defaults to: Bridgetown::Hooks::DEFAULT_PRIORITY) —

    either :low, :normal, or :high, or an integer. Default is normal (20)

Yields:

  • the block will be called when the event is triggered. Typically it receives at least one argument.

Yield Parameters:

  • obj —

    the object which triggered the event hook

See Also:



83
84
85
86
87
88
89
90
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 83

def hook(
  owner,
  event,
  priority: Bridgetown::Hooks::DEFAULT_PRIORITY,
  &
)
  Bridgetown::Hooks.register_one(owner, event, priority:, reloadable: false, &)
end

#include(files_list) ⇒ Object

Force inclusion of directories and/or files in the conversion (e.g. starting with underscores or dots)

Parameters:

  • files_list (Array<String>) 



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 251

#inflector ⇒ Bridgetown::Foundation::Inflector

Configure the inflector to add new inflection types, based on Dry::Inflector

Returns:




# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 298

#init(name, require_gem: true, require_initializer: true, **kwargs, &block) ⇒ void

This method returns an undefined value.

Initialize a Bridgetown plugin, optionally passing along configuration data. By default, requires the associated Ruby gem as well, but this can be switched off for local initializer files.

Parameters:

  • name (Symbol)
  • require_gem (Boolean) (defaults to: true) —

    set false if you don’t want the named gem to be required

  • require_initializer (Boolean) (defaults to: true) —

    set false if the named file in your config folder shouldn’t get processed as an initializer

  • kwargs (Hash) —

    pass keyword arguments as configuration along to the plugin. This can also be accomplished via a block using “Ruby front matter” syntax



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 22

def init(name, require_gem: true, require_initializer: true, **kwargs, &block) # rubocop:todo Metrics
  return if @scope.initializers.key?(name.to_sym) &&
    @scope.initializers[name.to_sym].completed

  initializer = _setup_initializer(
    name:, require_gem:, require_initializer:
  )

  return unless initializer.nil? || initializer.completed == false

  set :init_params do
    block ? set(name, &block) : set(name, kwargs)
  end

  if initializer.nil?
    Bridgetown.logger.warn("Initializing:",
                           "The `#{name}' initializer could not be found")
    return
  end

  Bridgetown.logger.debug "Initializing:", name
  @scope.initializers[name.to_sym].block.(
    self, **@scope.init_params[name].transform_keys(&:to_sym)
  )
  initializer.completed = true
end

#keep_files(files_list) ⇒ Object

Files to keep when clobbering the site destination (aka not generated in typical Bridgetown builds)

Parameters:

  • files_list (Array<String>) 



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 256

#only(*context) ⇒ void

This method returns an undefined value.

Execute the provided block for configuration only if the current context matches the provided criteria.

Parameters:

  • context (Symbol) —

    supply one or more contexts for execution. Generally these are :static, :console, :rake, and :server



55
56
57
58
59
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 55

def only(*context, &)
  return unless context.any? { _1 == @context }

  instance_exec(&)
end

#pagination ⇒ Object

Enable and configure the settings for the paginator

Examples:

Basic setup

pagination do
  enabled true
end



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 287

#permalink(style) ⇒ Object

Change the default permalink style or template used by pages & blog posts

Parameters:

  • style (String) —
    • default: :pretty, alternatives: :pretty_ext, :simple, :simple_ext



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 238

#reflect(name, require_gem: true, require_initializer: true) ⇒ Object

Similar to init but it simply prints out a list of the configuration options accepted as keyword arguments by the initializer



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 168

def reflect(name, require_gem: true, require_initializer: true)
  initializer = _setup_initializer(
    name:, require_gem:, require_initializer:
  )

  if initializer.nil?
    Bridgetown.logger.info("Reflection:",
                           "The `#{name}' initializer could not be found")
    return
  end

  Bridgetown.logger.info(
    "Reflection:",
    "The #{name.to_s.yellow} initializer accepts the following options:"
  )
  initializer.block.parameters.each do |param|
    next if param[0] == :opt

    option = param[1].to_s
    option = "** #{option}" if param[0] == :keyrest

    Bridgetown.logger.info("",
                           "- #{option.cyan}#{" (required)" if param[0] == :keyreq}")
  end

  nil
end

#roda {|app| ... } ⇒ void

This method returns an undefined value.

Define an initializer block which is called when the Roda server is being configured.

Yield Parameters:



122
123
124
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 122

def roda(&block)
  @scope.roda_initializers << block
end

#set(key, value = nil, &block) ⇒ Object 



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 149

def set(key, value = nil, &block)
  # Handle nested data within a block
  if block
    value = self.class.new(scope: @scope).tap do |fm|
      fm.instance_exec(&block)
    end.to_h
  end

  key = key.to_s.delete_suffix("=") if key.to_s.ends_with?("=")

  @data[key] = if @data[key].is_a?(Hash) && value.is_a?(Hash)
                 Bridgetown::Utils.deep_merge_hashes(@data[key], value)
               else
                 value
               end
end

#source(path) ⇒ Object

Change the directory where Bridgetown will read content files

Parameters:

  • path (String) —
    • default: src



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 226

#source_manifest ⇒ void

This method returns an undefined value.

Used by plugins to supply a source manifest.

See Also:

  • SourceManifest.new


96
97
98
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 96

def source_manifest(**)
  @scope.source_manifests << SourceManifest.new(**)
end

#template_engine(engine) ⇒ Object

Change the template engine Bridgetown uses by default to process content files

Parameters:

  • engine (Symbol) —
    • default: :erb, alternatives: :serbea, :liquid



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 234

#timezone(zone) ⇒ Object

Set the time zone for site generation, using IANA Time Zone Database

Parameters:

  • zone (String) 


130
131
132
133
 
# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 130

def timezone(new_timezone)
  @data[:timezone] = new_timezone
  Bridgetown.set_timezone(new_timezone)
end

#url(url) ⇒ Object

Sets the base URL for absolute links. (This will be overridden with something like localhost:4000 in development.)

Parameters:

  • url (String) 



# File 'bridgetown-core/lib/bridgetown-core/configuration/configuration_dsl.rb', line 221