ceedling 1.0.0 → 1.1.0

data/lib/ceedling/test_invoker/test_invoker_types.rb

@@ -0,0 +1,56 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+module TestInvokerTypes
+
+  # Partial build metadata for one test: config map plus accumulated output module names.
+  TestablePartials = Struct.new(:configs, :tests, :mocks, keyword_init: true)
+
+  # Carries all mutable state across the pipeline stages.
+  PipelineState = Struct.new(
+    :tests,             # Array of test filepaths (input to stage 1)
+    :testables,         # Hash<Symbol, Testable> — accumulated across all stages
+    :context,
+    :options,
+    :partials_headers,  # Produced by T1; consumed by stages 6 & 7
+    :partials_sources,  # Produced by T1; consumed by stages 6 & 7
+    :mocks_list,        # Produced by T2; consumed by stages 9 & 10
+    :objects_list,      # Produced by T3; consumed by stage 15
+    :lock,              # Mutex for thread-safe testable writes
+    keyword_init: true
+  )
+
+  # Named record replacing the raw hash per test file. Fields are populated
+  # across multiple stages; nil fields are valid until their stage sets them.
+  Testable = Struct.new(
+    :filepath, :name,
+    :paths,                                    # Hash — build/results/mocks/partials/preprocess paths
+    :preprocess,                               # Hash — preprocessing scratch state
+    :search_paths,
+    :compile_flags, :preprocess_flags, :assembler_flags, :link_flags,
+    :compile_defines, :preprocess_defines,
+    :runner,                                   # Hash — {output_filepath:, input_filepath:}
+    :mocks,                                    # Hash — mock name → mock info
+    :partials,                                 # TestablePartials — configs map + tests/mocks module name lists
+    :sources, :frameworks, :core, :objects, :executable,
+    :no_link_objects, :results_pass, :results_fail, :tool,
+    keyword_init: true
+  ) do
+    def initialize(**kwargs)
+      kwargs[:partials] ||= TestablePartials.new(configs: {}, tests: [], mocks: [])
+      super(**kwargs)
+    end
+  end
+
+  # Describes one pipeline step — either a named build_step or a silent transform.
+  Stage = Struct.new(:name, :heading, :condition, :transform, :body, keyword_init: true) do
+    def run?(state)
+      condition.nil? || condition.call(state)
+    end
+  end
+
+end

data/lib/ceedling/test_runner_manager.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 

data/lib/ceedling/tool_executor.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -11,7 +11,7 @@ require 'benchmark'
 
 class ToolExecutor
 
-  constructor :configurator, :tool_executor_helper, :loginator, :verbosinator, :system_wrapper
+  constructor :configurator, :tool_executor_helper, :loginator, :verbosinator, :system_wrapper, :ruby_expandinator
 
   # build up a command line from yaml provided config
 
@@ -38,7 +38,7 @@ class ToolExecutor
       ].reject{|s| s.nil? || s.empty?}.join(' ').strip
 
     # Log command as is
-    @loginator.log( "Command: #{command}", Verbosity::DEBUG )
+    @loginator.lazy( Verbosity::DEBUG ) { "> Command: #{command}\n\n" }
 
     # Update executable after any expansion
     command[:executable] = executable
@@ -46,7 +46,6 @@ class ToolExecutor
     return command
   end
 
-
   # shell out, execute command, and return response
   def exec(command, args=[])
     options = command[:options]
@@ -61,18 +60,23 @@ class ToolExecutor
       @tool_executor_helper.stderr_redirect_cmdline_append( options ),
       ].flatten.compact.join(' ')
 
-    shell_result = {}
+    shell_result = {
+      :output => '',
+      :stdout => '',
+      :stderr => '',
+      :exit_code => 0
+    }
 
     # Wrap system level tool execution in exception handling
     begin
-      time = Benchmark.realtime do
+      time = Benchmark.realtime do 
         shell_result = @system_wrapper.shell_capture3( command:command_line, boom:options[:boom] )
       end
       shell_result[:time] = time
 
     # Ultimately, re-raise the exception as ShellException populated with the exception message
     rescue => error
-      raise ShellException.new( name:pretty_tool_name( command ), message: error.message )
+      raise ShellException.new( name:pretty_tool_name( command ), message: "#{command_line}\n#{error.message}" )
 
     # Be sure to log what we can
     ensure
@@ -88,7 +92,7 @@ class ToolExecutor
     # Go boom if exit code is not 0 and that code means a fatal error
     # (Sometimes we don't want a non-0 exit code to cause an exception as the exit code may not mean a build-ending failure)
     if ((shell_result[:exit_code] != 0) and options[:boom])
-      raise ShellException.new( shell_result:shell_result, name:pretty_tool_name( command ) )
+      raise ShellException.new( shell_result:shell_result, name:pretty_tool_name( command ), message: "Executed Command: #{command_line}" )
     end
 
     return shell_result
@@ -127,18 +131,26 @@ class ToolExecutor
   end
 
 
-  # handle simple text string argument & argument array string replacement operators
+  # Handle simple text string argument & argument array string replacement operators
   def expandify_element(tool_name, element, *args)
     match = //
     to_process = nil
     args_index = 0
 
-    # handle ${#} input replacement
-    if (element =~ TOOL_EXECUTOR_ARGUMENT_REPLACEMENT_PATTERN)
+    # Handle ${#} input replacement
+    if (element =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+      # Convert argument numbering from configuration 1-indexed to array 0-indexed
       args_index = ($2.to_i - 1)
 
-      if (args.nil? or args[args_index].nil?)
-        error = "Tool '#{tool_name}' expected valid argument data to accompany replacement operator #{$1}."
+      args_size = args.nil? ? 0 : args.size()
+
+      if (args_size == 0)
+        error = "Command building for tool '#{tool_name}' expects argument data but was provided none."
+        raise CeedlingException.new( error )
+      end
+
+      if (args_index >= args_size)
+        error = "Command building for tool '#{tool_name}' was provided only #{args_size} arguments but references a replacement operator #{$1}."
         raise CeedlingException.new( error )
       end
 
@@ -146,22 +158,20 @@ class ToolExecutor
       to_process = args[args_index]
     end
 
-    # simple string argument: replace escaped '\$' and strip
+    # Simple string argument: replace escaped '\$' and strip
     element.sub!(/\\\$/, '$')
     element.strip!
 
     build_string = ''
 
-    # handle array or anything else passed into method to be expanded in place of replacement operators
+    # Handle array or anything else passed into method to be expanded in place of replacement operators
     case (to_process)
       when Array then to_process.each {|value| build_string.concat( "#{element.sub(match, value.to_s)} " ) } if (to_process.size > 0)
       else build_string.concat( element.sub(match, to_process.to_s) )
     end
 
-    # handle inline ruby string substitution
-    if (build_string =~ RUBY_STRING_REPLACEMENT_PATTERN)
-      build_string.replace(@system_wrapper.module_eval(build_string))
-    end
+    # Handle inline ruby string substitution
+    build_string.replace(@ruby_expandinator.expand(build_string, source: "tool '#{tool_name}'"))
 
     return build_string.strip
   end
@@ -187,8 +197,8 @@ class ToolExecutor
 
     expansion.each do |item|
       # String eval substitution
-      if (item =~ RUBY_STRING_REPLACEMENT_PATTERN)
-        elements << @system_wrapper.module_eval(item)
+      if (item =~ PATTERNS::RUBY_STRING_REPLACEMENT)
+        elements << @ruby_expandinator.expand(item, source: "tool '#{tool_name}'")
       # Global constants
       elsif (@system_wrapper.constants_include?(item))
         const = Object.const_get(item)

data/lib/ceedling/tool_executor_helper.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -66,32 +66,26 @@ class ToolExecutorHelper
     # No logging unless we're at least at Obnoxious
     return if !@verbosinator.should_output?( Verbosity::OBNOXIOUS )
 
-    output =      "> Shell executed command:\n"
+    output =      "> Shell executed::\n"
     output +=     "`#{command_str}`\n"
 
     if !shell_result.empty?
       # Detailed debug logging
       if @verbosinator.should_output?( Verbosity::DEBUG )
-        output +=   "> With $stdout: "
+        output +=   "> With $stdout:: "
         output += shell_result[:stdout].empty? ? "<empty>\n" : "\n#{shell_result[:stdout].strip()}\n"
 
-        output +=   "> With $stderr: "
+        output +=   "> With $stderr:: "
         output += shell_result[:stderr].empty? ? "<empty>\n" : "\n#{shell_result[:stderr].strip()}\n"
 
         output +=   "> And terminated with status: #{shell_result[:status]}\n"
 
-        @loginator.log( '', Verbosity::DEBUG )
-        @loginator.log( output, Verbosity::DEBUG )
-        @loginator.log( '', Verbosity::DEBUG )
+        @loginator.log( "#{output}\n\n", Verbosity::DEBUG )
 
         return # Bail out
       end
 
-      # Slightly less verbose obnoxious logging
-      if !shell_result[:output].empty?
-        output += "> Produced output: "
-        output += shell_result[:output].strip().empty? ? "<empty>\n" : "\n#{shell_result[:output].strip()}\n"
-      end
+      # Slightly less verbose obnoxious logging omits tool execution output
 
       if !shell_result[:exit_code].nil?
         output += "> And terminated with exit code: [#{shell_result[:exit_code]}]\n"
@@ -100,8 +94,6 @@ class ToolExecutorHelper
       end
     end
 
-    @loginator.log( '', Verbosity::OBNOXIOUS )
-    @loginator.log( output, Verbosity::OBNOXIOUS )
-    @loginator.log( '', Verbosity::OBNOXIOUS )
+    @loginator.log( "#{output}\n\n", Verbosity::OBNOXIOUS )
   end
 end

data/lib/ceedling/tool_validator.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -13,7 +13,7 @@ require 'ceedling/file_path_utils'  # For glob handling class methods
 
 class ToolValidator
   
-  constructor :file_wrapper, :loginator, :system_wrapper, :reportinator
+  constructor :file_wrapper, :loginator, :system_wrapper, :reportinator, :ruby_expandinator
 
   def validate(tool:, name:nil, extension:EXTENSION_EXECUTABLE, respect_optional:false, boom:false)
     # Redefine name with name inside tool hash if it's not provided
@@ -40,8 +40,8 @@ class ToolValidator
     executable = tool[:executable].dup()
 
     # Handle a missing :executable
-    if (executable.nil? or executable.empty?)
-      error = "Tool #{name} is missing :executable in its configuration."
+    if (executable.nil?)
+      error = "Tool #{name} is missing :executable in its configuration!"
       if !boom
         @loginator.log( error, Verbosity::ERRORS )
         return false 
@@ -53,10 +53,26 @@ class ToolValidator
     # If tool is optional and we're respecting that, don't bother to check if executable is legit
     return true if tool[:optional] and respect_optional
 
-    # Skip everything if we've got an argument replacement pattern or Ruby string replacement in :executable
+    # Skip everything if we've got an argument replacement pattern in :executable
     # (Allow executable to be validated by shell at run time)
-    return true if (executable =~ TOOL_EXECUTOR_ARGUMENT_REPLACEMENT_PATTERN)
-    return true if (executable =~ RUBY_STRING_REPLACEMENT_PATTERN)
+    return true if (executable =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+
+    # Skip shell-time validation for Ruby string replacement in :executable, but fail
+    # fast here (rather than deferring to tool_executor.rb's later expansion attempt)
+    # if the feature isn't enabled -- no reason to let the build proceed further only
+    # to blow up when this tool is actually invoked.
+    if (executable =~ PATTERNS::RUBY_STRING_REPLACEMENT)
+      begin
+        @ruby_expandinator.check!( executable, source: "tool '#{name}' :executable" )
+      rescue CeedlingException => e
+        if !boom
+          @loginator.log( e.message, Verbosity::ERRORS )
+          return false
+        end
+        raise
+      end
+      return true
+    end
 
     # Extract the executable (including optional filepath) apart from any additional arguments
     # Be mindful of legal quote enclosures (e.g. `"Code Cruncher" foo bar`)
@@ -103,7 +119,7 @@ class ToolValidator
     end
 
     if !exists
-      error = "#{name} ↳ :executable => `#{executable}` " + error
+      error = "#{name} ↳ :executable ➡️ `#{executable}` " + error
     end
 
     # Raise exception if executable can't be found and boom is set
@@ -130,7 +146,7 @@ class ToolValidator
     if redirect.class == Symbol
       if not StdErrRedirect.constants.map{|constant| constant.to_s}.include?( redirect.to_s.upcase )
         options = StdErrRedirect.constants.map{|constant| ':' + constant.to_s.downcase}.join(', ')
-        error = "#{name} ↳ :stderr_redirect => :#{redirect} is not a recognized option {#{options}}"
+        error = "#{name} ↳ :stderr_redirect ➡️ :#{redirect} is not a recognized option {#{options}}"
 
         # Raise exception if requested
         raise CeedlingException.new( error ) if boom

data/lib/ceedling/verbosinator.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 

data/lib/ceedling/yaml_wrapper.rb

@@ -1,31 +1,91 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
 require 'yaml'
-require 'erb'
-
+require 'ceedling/exceptions'
 
 class YamlWrapper
 
+  # Ceedling loads YAML from project config files, cache files, and generated test-result
+  # files. `YAML.load` can instantiate arbitrary Ruby objects from that content, which is
+  # unnecessary and unsafe -- `YAML.safe_load` restricts deserialization to plain data types
+  # plus whatever is explicitly permitted below.
+  #
+  # Ceedling's YAML convention (see assets/project.yml, cacheinator.rb, generator_test_results.rb)
+  # uses colon-prefixed keys (`:foo:`) to mean "this key is a Ruby Symbol"; unprefixed keys
+  # stay Strings. Psych recognizes `:foo` scalar notation as Symbol by default -- safe_load
+  # just needs `Symbol` added to its class allowlist to permit it. Aliases (`&anchor`/`*alias`)
+  # are off by default in safe_load as a DoS guard, so they're explicitly re-enabled.
+
+  # safe_load's calling convention changed between Psych 3 (bundled with Ruby 3.0) and
+  # Psych 4+ (bundled with Ruby 3.1+, and installable on any Ruby >= 3.0):
+  #   Psych 4+:  safe_load(yaml, permitted_classes: [], aliases: false, ...)   # keyword args
+  #   Psych 3:   safe_load(yaml, permitted_classes = [], permitted_symbols = [], aliases = false)  # positional
+  # Psych::VERSION is fixed for the life of the process, and #load/#load_string are called
+  # repeatedly over a Ceedling run, so the version check is memoized rather than repeated
+  # per call.
+
+  def self.psych_safe_load_uses_keywords?
+    return @psych_safe_load_uses_keywords if defined?(@psych_safe_load_uses_keywords)
+    @psych_safe_load_uses_keywords = (Gem::Version.new(Psych::VERSION) >= Gem::Version.new("4.0"))
+  end
+
   def load(filepath)
-    source = ERB.new(File.read(filepath)).result
     begin
-      return YAML.load(source, aliases: true)
-    rescue ArgumentError
-      return YAML.load(source)
+      source = File.read(filepath)
+    rescue Errno::ENOENT
+      raise YamlLoadException.new(
+        reason: :not_found, source: filepath, original_error: nil,
+        message: "Could not find YAML file ⏩️ #{filepath}"
+      )
     end
+
+    load_string(source, source_label: filepath)
   end
 
-  def load_string(source)
-    begin
-      return YAML.load(source, aliases: true)
-    rescue ArgumentError
-      return YAML.load(source)
+  def load_string(source, source_label: '<inline YAML>')
+    if self.class.psych_safe_load_uses_keywords?
+      YAML.safe_load(source, permitted_classes: [Symbol], aliases: true, filename: source_label)
+    else
+      YAML.safe_load(source, [Symbol], [], true, source_label)
     end
+
+  # The YAML parsed fine syntactically, but it contains a tag/type (e.g. `!ruby/object:...`)
+  # that isn't on safe_load's permitted-class allowlist. This is Psych doing its safety job,
+  # not a content typo -- surfaced separately from :syntax so the user understands the fix is
+  # "remove this Ruby-object tag," not "fix a formatting mistake."
+  rescue Psych::DisallowedClass => e
+    raise YamlLoadException.new(
+      reason: :unsafe, source: source_label, original_error: e,
+      message: "YAML content in #{source_label} uses a Ruby type not permitted by safe YAML loading ⏩️ #{e.message}"
+    )
+
+  # Catches every other Psych::Exception subclass (Psych::SyntaxError, Psych::BadAlias,
+  # Psych::AnchorNotDefined, etc.) -- i.e. the YAML text itself is malformed: bad syntax,
+  # a dangling alias reference, and similar authoring mistakes the user needs to fix in
+  # the YAML source. Ordered after Psych::DisallowedClass, which is a subclass of
+  # Psych::Exception and needs its own more specific message.
+  rescue Psych::Exception => e
+    raise YamlLoadException.new(
+      reason: :syntax, source: source_label, original_error: e,
+      message: "Malformed YAML content in #{source_label} ⏩️ #{e.message}"
+    )
+
+  # Not a problem with the YAML content at all -- the installed Psych version rejected one
+  # of the arguments safe_load was called with. self.class.psych_safe_load_uses_keywords?
+  # already picks the right calling convention for the installed Psych, so this should be
+  # unreachable in practice; it exists as a last-resort safety net for an unanticipated
+  # Psych version/interface mismatch, reported distinctly so it isn't mistaken for a user
+  # YAML-authoring error.
+  rescue ArgumentError => e
+    raise YamlLoadException.new(
+      reason: :incompatible, source: source_label, original_error: e,
+      message: "Installed Psych YAML library (#{Psych::VERSION}) does not support a safe-loading feature Ceedling requires ⏩️ #{e.message}"
+    )
   end
 
   def dump(filepath, structure)

data/lib/ceedling.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 

data/lib/snapshot.rb

@@ -0,0 +1,43 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# snapshot.rb <config-file> <snapshot-dir>
+#
+# Copies versioned project files into <snapshot-dir> so that the mkdocs documentation
+# build can reference them with relative paths that are correct for each deployed version.
+#
+# <config-file>  Path to the YAML snapshot configuration file. Lists source files to copy
+#                as paths relative to the project root.
+# <snapshot-dir> Destination directory. Each file is written to <snapshot-dir>/<relative-path>,
+#                preserving directory structure.
+#
+# Invoked via `rake docs:snapshot` (or automatically by `rake docs:build`).
+# 
+# This script assumes the destination directory does not exist.
+
+require 'fileutils'
+require 'yaml'
+
+PROJECT_ROOT    = File.expand_path('..', __dir__)
+SNAPSHOT_CONFIG = ARGV[0] or abort("Usage: snapshot.rb <config-file> <snapshot-dir>")
+SNAPSHOT_DIR    = ARGV[1] or abort("Usage: snapshot.rb <config-file> <snapshot-dir>")
+
+config = YAML.load_file(SNAPSHOT_CONFIG)
+files  = config.fetch('files')
+
+files.each do |relative_path|
+  src  = File.join(PROJECT_ROOT, relative_path)
+  dest = File.join(SNAPSHOT_DIR, relative_path)
+
+  # Create the destnation directory
+  FileUtils.mkdir_p(File.dirname(dest))
+  # Copy the path, including recursive copying for directories
+  FileUtils.cp_r(src, dest)
+  puts "  snapshot: #{relative_path}"
+end
+
+puts "Snapshot complete — #{files.length} file(s) written to #{SNAPSHOT_DIR}"

data/lib/version.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -15,7 +15,7 @@
 module Ceedling
   module Version
     # Convenience constants for gem building, etc.
-    GEM = '1.0.0'
+    GEM = '1.1.0'
     TAG = GEM
 
     # If run as a script print Ceedling's version to $stdout

data/license.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/mkdocs.local.yml

@@ -0,0 +1,45 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# mkdocs uses a simple overwrite merge -- must rewrite entire sections to make small changes.
+INHERIT: mkdocs.yml
+
+# Produce index.html files with internal links for local HTML bundle.
+# The default is to produce directory URLs where a web server silently serves a directory index.html file
+use_directory_urls: false
+# Blank — prevents absolute URLs being baked in that point back to the live site.
+site_url: ''
+
+site_dir: site-local
+
+# Material theme configuration
+theme:
+  name: material
+  favicon: assets/images/favicon.png
+  palette:
+    - scheme: default
+      primary: green
+      accent: deep_purple
+  features:
+    # No navigation.instant for local site
+    - navigation.tabs        # Top-level nav rendered as tabs
+    - navigation.sections    # Sections rendered as groups in left sidebar
+    - navigation.top         # Back-to-top button
+    - navigation.indexes     # Section index pages (first item in section = section landing page)
+    - navigation.path        # Breadcrumb trail below page title
+    - search.suggest         # Autocomplete suggestions in search
+    - search.highlight       # Highlight search terms on result pages
+    - content.code.copy      # Copy button on code blocks
+    - content.code.annotate  # Inline annotation support in code blocks
+
+extra_css:
+  - assets/stylesheets/styling.css      # Custom style tweaks
+  - assets/stylesheets/admonitions.css  # Custom admonition types
+  - assets/stylesheets/fixes-local.css  # Local site styling overrides and layout fixes
+
+# Remove all the optional plugins that we run on the server, including "search" and "mike"
+plugins: []