diff --git a/Gemfile b/Gemfile index fccdd6ec9..9f4ab5fc8 100644 --- a/Gemfile +++ b/Gemfile @@ -19,7 +19,7 @@ group :test do gem "nokolexbor" gem "rack-test" gem "rspec-mocks" - gem "rubocop-bridgetown", "~> 0.4", require: false + gem "rubocop-bridgetown", "~> 0.6", require: false gem "shoulda" gem "simplecov" gem "terminal-table" diff --git a/Gemfile.lock b/Gemfile.lock index 04e606a08..7eb15fa07 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -108,7 +108,7 @@ GEM concurrent-ruby (~> 1.0) inclusive (1.0.0) jaro_winkler (1.6.0) - json (2.7.2) + json (2.7.5) kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) @@ -144,7 +144,7 @@ GEM nokolexbor (0.5.4-x86_64-darwin) nokolexbor (0.5.4-x86_64-linux) parallel (1.26.3) - parser (3.3.5.0) + parser (3.3.5.1) ast (~> 2.4.1) racc public_suffix (6.0.1) @@ -172,7 +172,7 @@ GEM diff-lcs (>= 1.2.0, < 2.0) rspec-support (~> 3.13.0) rspec-support (3.13.1) - rubocop (1.67.0) + rubocop (1.68.0) json (~> 2.3) language_server-protocol (>= 3.17.0) parallel (~> 1.10) @@ -182,9 +182,9 @@ GEM rubocop-ast (>= 1.32.2, < 2.0) ruby-progressbar (~> 1.7) unicode-display_width (>= 2.4.0, < 3.0) - rubocop-ast (1.32.3) + rubocop-ast (1.33.1) parser (>= 3.3.1.0) - rubocop-bridgetown (0.5.0) + rubocop-bridgetown (0.6.1) rubocop (~> 1.23) rubocop-performance (~> 1.12) rubocop-performance (1.22.1) @@ -262,7 +262,7 @@ DEPENDENCIES rack-test rake (~> 13.0) rspec-mocks - rubocop-bridgetown (~> 0.4) + rubocop-bridgetown (~> 0.6) shoulda simplecov solargraph diff --git a/bridgetown-core/.rubocop.yml b/bridgetown-core/.rubocop.yml index 814a251e6..544e4bc7f 100644 --- a/bridgetown-core/.rubocop.yml +++ b/bridgetown-core/.rubocop.yml @@ -44,5 +44,5 @@ Style/StringConcatenation: Exclude: - test/test_apply_command.rb -Style/MixinGrouping: - Enabled: false \ No newline at end of file +Style/SafeNavigationChainLength: + Enabled: false diff --git a/bridgetown-core/lib/bridgetown-core.rb b/bridgetown-core/lib/bridgetown-core.rb index ee12adcd0..3a9dba1de 100644 --- a/bridgetown-core/lib/bridgetown-core.rb +++ b/bridgetown-core/lib/bridgetown-core.rb @@ -35,7 +35,7 @@ def require_all(path) require "bridgetown-foundation" # 3rd party -require "active_support" # TODO: remove by the end of 2024 +require "active_support" # TODO: remove by the end of 2025 require "active_support/core_ext/object/blank" require "active_support/core_ext/string/inflections" require "active_support/core_ext/string/output_safety" @@ -76,7 +76,6 @@ module Bridgetown autoload :DefaultsReader, "bridgetown-core/readers/defaults_reader" autoload :Deprecator, "bridgetown-core/deprecator" autoload :EntryFilter, "bridgetown-core/entry_filter" - # TODO: we have too many errors! This is silly autoload :Errors, "bridgetown-core/errors" autoload :FrontMatter, "bridgetown-core/front_matter" autoload :GeneratedPage, "bridgetown-core/generated_page" diff --git a/bridgetown-core/lib/bridgetown-core/commands/build.rb b/bridgetown-core/lib/bridgetown-core/commands/build.rb index bf1ca2b27..d6d80243a 100644 --- a/bridgetown-core/lib/bridgetown-core/commands/build.rb +++ b/bridgetown-core/lib/bridgetown-core/commands/build.rb @@ -66,11 +66,7 @@ def build build_site(config_options) end - # TODO: remove this logic…I can't find "detach" anywhere - if config_options.fetch("detach", false) - Bridgetown.logger.info "Auto-regeneration:", - "disabled when running server detached." - elsif config_options.fetch("watch", false) + if config_options.fetch("watch", false) watch_site(config_options) else Bridgetown.logger.info "Auto-regeneration:", "disabled. Use --watch to enable." @@ -111,7 +107,6 @@ def display_folder_paths(config_options) Bridgetown.logger.info "Environment:", Bridgetown.environment.cyan Bridgetown.logger.info "Source:", source Bridgetown.logger.info "Destination:", destination - # TODO: work with arrays return unless config_options["plugins_dir"].is_a?(String) plugins_dir = File.expand_path(config_options["plugins_dir"]) diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/fast_refreshable.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/fast_refreshable.rb index 12d256c2a..2b896727a 100644 --- a/bridgetown-core/lib/bridgetown-core/concerns/site/fast_refreshable.rb +++ b/bridgetown-core/lib/bridgetown-core/concerns/site/fast_refreshable.rb @@ -10,15 +10,16 @@ def fast_refresh(paths = [], reload_if_needed: false) # rubocop:todo Metrics @fast_refresh_ordering = 0 full_abort = false found_gen_pages = false - paths.each do |path| - res = resources.find do |resource| + paths.each do |path| # rubocop:todo Metrics + found_res = resources.select do |resource| resource.id.start_with?("repo://") && in_source_dir(resource.relative_path) == path end layouts_to_reload = Set.new - locate_resource_layouts_and_partials_for_fash_refresh(path, layouts_to_reload) unless res + locate_resource_layouts_and_partials_for_fash_refresh(path, layouts_to_reload) unless + found_res.any? - locate_components_for_fast_refresh(path) unless res + locate_components_for_fast_refresh(path) unless found_res.any? pages = locate_layouts_and_pages_for_fast_refresh(path, layouts_to_reload) @@ -27,20 +28,22 @@ def fast_refresh(paths = [], reload_if_needed: false) # rubocop:todo Metrics self, layout.instance_variable_get(:@base), layout.name ) end - next unless res || !pages.empty? + next unless found_res.any? || pages.any? - unless pages.empty? + if pages.any? found_gen_pages = true mark_original_page_resources_for_fast_refresh(pages) next end - res.prepare_for_fast_refresh!.tap { full_abort = true unless _1 } - next unless res.collection.data? + found_res.each do |res| + res.prepare_for_fast_refresh!.tap { full_abort = true unless _1 } + next unless res.collection.data? - res.collection.merge_data_resources.each do |k, v| - data[k] = v - signals[k] = v + res.collection.merge_data_resources.each do |k, v| + data[k] = v + signals[k] = v + end end end @@ -134,7 +137,11 @@ def mark_original_page_resources_for_fast_refresh(pages) end def transform_resources_for_fast_refresh(marked_resources, found_gen_pages) - marked_resources.each { _1.transform!.write } + marked_resources.each do |res| + render_with_locale(res) do + res.transform!.write + end + end number_of_resources = marked_resources.length number_of_resources += 1 if found_gen_pages Bridgetown.logger.info( diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/ssr.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/ssr.rb index d853b4d97..305ace24e 100644 --- a/bridgetown-core/lib/bridgetown-core/concerns/site/ssr.rb +++ b/bridgetown-core/lib/bridgetown-core/concerns/site/ssr.rb @@ -45,7 +45,6 @@ def ssr_setup(&block) end def ssr_first_read - # TODO: this shouldn't be running twice, right?! Bridgetown::Hooks.trigger :site, :pre_read, self defaults_reader.tap do |d| d.path_defaults.clear diff --git a/bridgetown-core/lib/bridgetown-core/drops/drop.rb b/bridgetown-core/lib/bridgetown-core/drops/drop.rb index 0993a4e73..4b49a573d 100644 --- a/bridgetown-core/lib/bridgetown-core/drops/drop.rb +++ b/bridgetown-core/lib/bridgetown-core/drops/drop.rb @@ -49,25 +49,22 @@ def [](key) end alias_method :invoke_drop, :[] - # Set a field in the Drop. If mutable, sets in the mutations and - # returns. If not mutable, checks first if it's trying to override a - # Drop method and raises a DropMutationException if so. If not - # mutable and the key is not a method on the Drop, then it sets the - # key to the value in the underlying hash (e.g. document front - # matter) + # Set a field in the Drop. If mutable, sets in the mutations and returns. If not mutable, + # checks first if it's trying to override a Drop method and raises an exception if so. + # If not mutable and the key is not a method on the Drop, then it sets the key to the value + # in the underlying hash (e.g. document front matter) # # @param key [String] key whose value to set # @param val [Object] what to set the key's value to # @return [Object] the value the key was set to unless the Drop is not mutable - # and the key matches a method in which case it raises a - # DropMutationException. + # and the key matches a method in which case it raises an exception def []=(key, val) setter = "#{key}=" if respond_to?(setter) public_send(setter, val) elsif respond_to?(key.to_s) unless self.class.mutable? - raise Errors::DropMutationException, "Key #{key} cannot be set in the drop." + raise Errors::FatalException, "Key #{key} cannot be set in the drop." end mutations[key] = val diff --git a/bridgetown-core/lib/bridgetown-core/errors.rb b/bridgetown-core/lib/bridgetown-core/errors.rb index 2823e4c40..0ad078e6a 100644 --- a/bridgetown-core/lib/bridgetown-core/errors.rb +++ b/bridgetown-core/lib/bridgetown-core/errors.rb @@ -4,16 +4,10 @@ module Bridgetown module Errors FatalException = Class.new(::RuntimeError) - DropMutationException = Class.new(FatalException) - InvalidPermalinkError = Class.new(FatalException) - InvalidYAMLFrontMatterError = Class.new(FatalException) - MissingDependencyException = Class.new(FatalException) - + InvalidConfigurationError = Class.new(FatalException) InvalidDateError = Class.new(FatalException) - InvalidPostNameError = Class.new(FatalException) + InvalidYAMLFrontMatterError = Class.new(FatalException) PostURLError = Class.new(FatalException) - InvalidURLError = Class.new(FatalException) - InvalidConfigurationError = Class.new(FatalException) def self.print_build_error(exc, trace: false, logger: Bridgetown.logger, server: false) # rubocop:todo Metrics logger.error "Exception raised:", exc.class.to_s.bold diff --git a/bridgetown-core/lib/bridgetown-core/filters.rb b/bridgetown-core/lib/bridgetown-core/filters.rb index 1c03388be..83b4d86fc 100644 --- a/bridgetown-core/lib/bridgetown-core/filters.rb +++ b/bridgetown-core/lib/bridgetown-core/filters.rb @@ -192,7 +192,7 @@ def where(input, property, value) # rubocop:disable Metrics/CyclomaticComplexity def where_exp(input, variable, expression) return input unless input.respond_to?(:select) - input = input.values if input.is_a?(Hash) # FIXME + input = input.values if input.is_a?(Hash) condition = parse_condition(expression) @context.stack do diff --git a/bridgetown-core/lib/bridgetown-core/hooks.rb b/bridgetown-core/lib/bridgetown-core/hooks.rb index e198f9226..4d0a2da98 100644 --- a/bridgetown-core/lib/bridgetown-core/hooks.rb +++ b/bridgetown-core/lib/bridgetown-core/hooks.rb @@ -25,7 +25,6 @@ def to_s @registry = {} - NotAvailable = Class.new(RuntimeError) Uncallable = Class.new(RuntimeError) def self.priority_value(priority) diff --git a/bridgetown-core/lib/bridgetown-core/resource/base.rb b/bridgetown-core/lib/bridgetown-core/resource/base.rb index e9457b7a9..88c2d35a4 100644 --- a/bridgetown-core/lib/bridgetown-core/resource/base.rb +++ b/bridgetown-core/lib/bridgetown-core/resource/base.rb @@ -106,11 +106,7 @@ def data # # @param new_data [HashWithDotAccess::Hash] def data=(new_data) - if site.config.fast_refresh && write? - # TODO: investigate if this would be better: - # @data.value = front_matter_defaults - mark_for_fast_refresh! - end + mark_for_fast_refresh! if site.config.fast_refresh && write? Signalize.batch do @content_signal.value += 1 @@ -365,7 +361,10 @@ def prepare_for_fast_refresh! # rubocop:todo Metrics past_values = @data.peek.select do |key| key == "categories" || key == "tags" || site.taxonomy_types.keys.any?(key) end - model.attributes = model.origin.read + origin_data = model.origin.read + correct_locale = origin_data["locale"] || origin_data[:locale] || data.locale + model.attributes = origin_data + model.attributes.locale = correct_locale @relative_url = @absolute_url = nil # wipe memoizations read! tax_diff = past_values.any? { |k, v| @data.peek[k] != v } diff --git a/bridgetown-core/lib/bridgetown-core/ruby_template_view.rb b/bridgetown-core/lib/bridgetown-core/ruby_template_view.rb index 747b1a1a5..76e0cf463 100644 --- a/bridgetown-core/lib/bridgetown-core/ruby_template_view.rb +++ b/bridgetown-core/lib/bridgetown-core/ruby_template_view.rb @@ -131,7 +131,6 @@ def _liquid_context def _partial_path(partial_name, ext) partial_name = partial_name.split("/").tap { _1.last.prepend("_") }.join("/") - # TODO: see if there's a workaround for this to speed up performance site.in_source_dir(site.config[:partials_dir], "#{partial_name}.#{ext}") end end diff --git a/bridgetown-core/lib/bridgetown-core/tags/post_url.rb b/bridgetown-core/lib/bridgetown-core/tags/post_url.rb index e6ab658a9..95012d64e 100644 --- a/bridgetown-core/lib/bridgetown-core/tags/post_url.rb +++ b/bridgetown-core/lib/bridgetown-core/tags/post_url.rb @@ -12,7 +12,7 @@ def initialize(name) all, @path, @date, @slug = *name.sub(%r!^/!, "").match(MATCHER) unless all - raise Bridgetown::Errors::InvalidPostNameError, + raise Bridgetown::Errors::FatalException, "'#{name}' does not contain valid date and/or title." end diff --git a/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/object.rb b/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/object.rb index ac54c889f..a4ed8a2b5 100644 --- a/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/object.rb +++ b/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/object.rb @@ -54,7 +54,7 @@ def within?(other) # rubocop:disable Metrics # NOTE: if you _really_ need to preserve Active Support's `in?` functionality, you can just # require "active_support/core_ext/object/inclusion" def in?(...) = Bridgetown::Foundation.deprecation_warning( - self, :in?, :within?, 2024, 12 + self, :in?, :within?, 2025, 12 ).then { within?(...) } end end diff --git a/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/string.rb b/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/string.rb index bf9450b4d..c7135fe94 100644 --- a/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/string.rb +++ b/bridgetown-foundation/lib/bridgetown/foundation/refine_ext/string.rb @@ -23,7 +23,7 @@ def indent(indent_by, *args) def questionable = Bridgetown::Foundation::QuestionableString.new(self) def inquiry = Bridgetown::Foundation.deprecation_warning( - self, :inquiry, :questionable, 2024, 12 + self, :inquiry, :questionable, 2025, 12 ).then { questionable } end end diff --git a/bridgetown-website/Gemfile.lock b/bridgetown-website/Gemfile.lock index 42a4bf3fd..e554cecda 100644 --- a/bridgetown-website/Gemfile.lock +++ b/bridgetown-website/Gemfile.lock @@ -60,21 +60,24 @@ PATH GEM remote: https://rubygems.org/ specs: - activesupport (7.1.3.4) + activesupport (7.2.2) base64 + benchmark (>= 0.3) bigdecimal - concurrent-ruby (~> 1.0, >= 1.0.2) + concurrent-ruby (~> 1.0, >= 1.3.1) connection_pool (>= 2.2.5) drb i18n (>= 1.6, < 2) + logger (>= 1.4.2) minitest (>= 5.1) - mutex_m - tzinfo (~> 2.0) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) addressable (2.8.7) public_suffix (>= 2.0.2, < 7.0) amazing_print (1.6.0) ast (2.4.2) base64 (0.2.0) + benchmark (0.3.0) bigdecimal (3.1.8) bridgetown-feed (3.1.2) bridgetown (>= 1.2.0.beta2, < 2.0) @@ -85,26 +88,28 @@ GEM bridgetown-svg-inliner (2.0.0) bridgetown (>= 1.2.0, < 2.0) nokogiri - concurrent-ruby (1.3.3) + concurrent-ruby (1.3.4) connection_pool (2.4.1) csv (3.3.0) drb (2.2.1) dry-inflector (1.1.0) erubi (1.13.0) - faraday (2.10.0) - faraday-net_http (>= 2.0, < 3.2) + faraday (2.12.0) + faraday-net_http (>= 2.0, < 3.4) + json logger faraday-follow_redirects (0.3.0) faraday (>= 1, < 3) - faraday-net_http (3.1.1) + faraday-net_http (3.3.0) net-http ffi (1.17.0-arm64-darwin) ffi (1.17.0-x86_64-linux-gnu) gems (1.2.0) hash_with_dot_access (2.1.1) - i18n (1.14.5) + i18n (1.14.6) concurrent-ruby (~> 1.0) inclusive (1.0.0) + json (2.7.5) kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) @@ -113,42 +118,40 @@ GEM listen (3.9.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) - logger (1.6.0) - minitest (5.24.1) - mutex_m (0.2.0) + logger (1.6.1) + minitest (5.25.1) net-http (0.4.1) uri - nio4r (2.7.3) + nio4r (2.7.4) nokogiri (1.16.7-arm64-darwin) racc (~> 1.4) nokogiri (1.16.7-x86_64-linux) racc (~> 1.4) nokolexbor (0.5.4-arm64-darwin) nokolexbor (0.5.4-x86_64-linux) - parser (3.3.4.0) + parser (3.3.5.1) ast (~> 2.4.1) racc public_suffix (6.0.1) puma (6.4.3) nio4r (~> 2.0) racc (1.8.1) - rack (3.1.7) - rackup (2.1.0) + rack (3.1.8) + rackup (2.2.0) rack (>= 3) - webrick (~> 1.8) rake (13.2.1) rb-fsevent (0.11.2) rb-inotify (0.11.1) ffi (~> 1.0) regexp_parser (2.1.1) - rexml (3.3.2) - strscan - roda (3.82.0) + rexml (3.3.9) + roda (3.85.0) rack - rouge (4.3.0) + rouge (4.4.0) ruby2js (5.1.2) parser regexp_parser (~> 2.1.1) + securerandom (0.3.1) serbea (2.2.0) erubi (>= 1.10) tilt (~> 2.0) @@ -157,14 +160,12 @@ GEM streamlined (0.6.0) serbea (>= 2.1) zeitwerk (~> 2.5) - strscan (3.1.0) - thor (1.3.1) + thor (1.3.2) tilt (2.4.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) - uri (0.13.0) - webrick (1.8.2) - zeitwerk (2.6.17) + uri (0.13.1) + zeitwerk (2.7.1) PLATFORMS arm64-darwin-22 diff --git a/bridgetown-website/README.md b/bridgetown-website/README.md deleted file mode 100644 index 59525c4ab..000000000 --- a/bridgetown-website/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# New 2021 Website for Bridgetown - -TODO: build and launch a new website for Bridgetown! =) diff --git a/bridgetown-website/src/_docs/automations.md b/bridgetown-website/src/_docs/automations.md index 29f2032aa..aa4ea458d 100644 --- a/bridgetown-website/src/_docs/automations.md +++ b/bridgetown-website/src/_docs/automations.md @@ -14,7 +14,7 @@ They're uniquely powerful when combined with [plugins](/docs/plugins), as an automation can install and configure one or more plugins from a single script. You could also write an automation to run multiple additional automations, and -apply that to a brand-new site to set everything up just how you want it in a +apply that to a brand-new site to set everything up exactly how you want it in a repeatable and automatic fashion. Automations can be loaded from a local path, or they can be loaded from remote @@ -67,7 +67,7 @@ actions provided by Thor](https://github.com/erikhuda/thor/wiki/Actions), such as `run` to run a CLI executable, or `ask` to prompt the user for details, or `say_status` to provide helpful messages in the terminal. -Here's an example of a simple automation which creates a new file in a +Here's an example of an automation which creates a new file in a site repo: ```ruby @@ -157,5 +157,5 @@ end In summary, automations are a fantastic method of saving repeatable setup steps for you to reuse later in new projects, or you can share scripts with -the world at large. Use them for plugins, themes, or just quick one-off +the world at large. Use them for plugins, themes, or quick one-off scripts. diff --git a/bridgetown-website/src/_docs/bundled-configurations.md b/bridgetown-website/src/_docs/bundled-configurations.md index b6e66b174..cf2983776 100644 --- a/bridgetown-website/src/_docs/bundled-configurations.md +++ b/bridgetown-website/src/_docs/bundled-configurations.md @@ -42,7 +42,7 @@ Bundled configurations can also be run while creating a new Bridgetown project u {%@ Note type: :warning do %} #### Looking for Tailwind? - The bundled configuration for TailwindCSS has been [relocated to a separate community-maintained repo](https://github.com/bridgetownrb/tailwindcss-automation). The installation process remains just as simple. However, the Bridgetown core team recommends looking into options such as Open Props, Shoelace, and otherwise "vanilla" CSS (perhaps with a bit of help from PostCSS or Sass) as a best practice for "Use the Platform", future-compatible frontend development. + The bundled configuration for TailwindCSS has been [relocated to a separate community-maintained repo](https://github.com/bridgetownrb/tailwindcss-automation). However, the Bridgetown core team recommends looking into options such as Open Props, Shoelace, and otherwise "vanilla" CSS (perhaps with a bit of help from PostCSS or Sass) as a best practice for "Use the Platform", future-compatible frontend development. {% end %} ## Configuration Setup Details @@ -113,7 +113,7 @@ bin/bridgetown configure open-props 🔴 Installs [Ruby2JS](https://www.ruby2js.com), an extensible Ruby to modern JavaScript transpiler you can use in production today. It produces JavaScript that looks hand-crafted, rather than machine generated. You can convert Ruby-like syntax and semantics as cleanly and “natively” as possible. This means that (most of the time) you’ll get a line-by-line, 1:1 correlation between your source code and the JS output. -Simply write your files in `frontend/javascript` or in `src/_components` with a `.js.rb` extension and they'll be supported the same way as `.js` file by Bridgetown's frontend bundling pipeline. +Write your files in `frontend/javascript` or in `src/_components` with a `.js.rb` extension and they'll be supported the same way as `.js` file by Bridgetown's frontend bundling pipeline. 🛠 **Configure using:** diff --git a/bridgetown-website/src/_docs/collections.md b/bridgetown-website/src/_docs/collections.md index 62f2c86df..4f8ed9619 100644 --- a/bridgetown-website/src/_docs/collections.md +++ b/bridgetown-website/src/_docs/collections.md @@ -111,7 +111,7 @@ There are special [permalink variables for collections](/docs/content/permalinks ## Custom Metadata -It's also possible to add custom metadata to a collection. You simply add +It's also possible to add custom metadata to a collection. You add additional keys to the collection config and they'll be made available in templates. For example, if you specify this: ```yaml diff --git a/bridgetown-website/src/_docs/command-line-usage.md b/bridgetown-website/src/_docs/command-line-usage.md index d3089b2ff..fecf392f8 100644 --- a/bridgetown-website/src/_docs/command-line-usage.md +++ b/bridgetown-website/src/_docs/command-line-usage.md @@ -78,7 +78,7 @@ task :linthtml do # this is custom for the website project end ``` -As is shown in comments for the default Rakefile, you can add your own [automations](/docs/automations) directly inside of Rake tasks. In the provided example, you can see that a `site` object is available, and within an `automation` block you can call Thor actions just like in standard automation scripts: +As is shown in comments for the default Rakefile, you can add your own [automations](/docs/automations) directly inside of Rake tasks. In the provided example, you can see that a `site` object is available, and within an `automation` block you can call Thor actions like standard automation scripts: ```ruby task :my_task => :environment do @@ -99,7 +99,7 @@ Running `bin/bridgetown my_task` would result in printing out the root path of t When you run `bin/bridgetown console` or `c`, you have access to an instantiated `site` object which you can use to investigate its content and configuration. You can also call `collections` directly as a shorthand for `site.collections`, and you can run `reload!` anytime you want to reset/reload site content and plugins. -Besides those built-in console methods, you can add your own! Just define your own `ConsoleMethods` module and include that in Bridgetown's standard module. +Besides those built-in console methods, you can add your own! Define your own `ConsoleMethods` module and include that in Bridgetown's standard module. ```ruby module ConsoleMethods diff --git a/bridgetown-website/src/_docs/commands/plugins.md b/bridgetown-website/src/_docs/commands/plugins.md index 0093737ba..4896e5d7c 100644 --- a/bridgetown-website/src/_docs/commands/plugins.md +++ b/bridgetown-website/src/_docs/commands/plugins.md @@ -7,7 +7,7 @@ category: command-line-usage The `plugins` command allows you to display all custom or gem-based plugins you have loaded in the site along with other related infrastructure such as source manifests, generators, and builders. -Simply run `bridgetown plugins list` and you'll get a printout in your terminal that looks something like this: +Run `bridgetown plugins list` and you'll get a printout in your terminal that looks something like this: ``` @@ -52,9 +52,9 @@ bridgetown plugins cd / where `` is one of the source manifest origins (like the `SamplePlugin` example above), and `` is one of the folder names (like `Content` or `Layouts`). -The command drops you in a new temporary shell where you can access the files, and when you're done simply type `exit` to return to your site. In addition, you're given the `BRIDGETOWN_SITE` environment variable as a way to reference your site from the temporary shell. +The command drops you in a new temporary shell where you can access the files, and when you're done, type `exit` to return to your site. In addition, you're given the `BRIDGETOWN_SITE` environment variable as a way to reference your site from the temporary shell. -So for example if you wanted to copy all the layouts from a gem-based plugin into your own site layouts folder, it's as simple as running: +For example, if you wanted to copy all the layouts from a gem-based plugin into your own site layouts folder, run: ```sh bridgetown plugins cd AwesomePlugin/Layouts diff --git a/bridgetown-website/src/_docs/components.md b/bridgetown-website/src/_docs/components.md index af1393cd9..fd5bf7564 100644 --- a/bridgetown-website/src/_docs/components.md +++ b/bridgetown-website/src/_docs/components.md @@ -15,7 +15,7 @@ Just as a web page can be thought of as the interconnected product of the three ### [Liquid](/docs/components/liquid) -Use the [Liquid template engine](/docs/template-engines/liquid) to write simple components without a lot of custom logic or for maximum compatibility with all template engines. Liquid components are not recommended when complexity is required for frontend logic. +Use the [Liquid template engine](/docs/template-engines/liquid) to write basic components without a lot of custom logic or for maximum compatibility with all template engines. Liquid components are not recommended when complexity is required for frontend logic. ### [Ruby](/docs/components/ruby) @@ -33,7 +33,7 @@ An emerging technology which has the potential to change how we approach develop ## The Subtle Interplay of HTML, CSS, & JavaScript -As previously mentioned, a component will often encompass not just the output HTML coming from the component's logic/template, but styling via CSS, and client-side interactivity via JavaScript. +As previously mentioned, a component will often encompass styling via CSS and client-side interactivity via JavaScript, alongside the output HTML coming from the component's logic/template. In those cases, where you place your CSS and JS code will vary depending on the environment. For Liquid and Ruby components, you will write what are called "sidecar" files which live alongside your component classes/templates. In contrast, Lit components fall under the category of Single-File Components. The logic, template, and styling is all part of the same unit of code. Lit components can be written in either vanilla JavaScript or Ruby2JS (a Ruby-like syntax and set of idioms which then transpiles to JavaScript). However, with a smidge of extra configuration, you do have the option of splitting the CSS of a Lit component out to its own sidecar file if you so choose. diff --git a/bridgetown-website/src/_docs/components/liquid.md b/bridgetown-website/src/_docs/components/liquid.md index a2fa24199..4892eb001 100644 --- a/bridgetown-website/src/_docs/components/liquid.md +++ b/bridgetown-website/src/_docs/components/liquid.md @@ -15,7 +15,7 @@ Liquid components can be combined with front-end component strategies using **we ## Usage -Including a component within a content document or design template is done via a `render` tag or `rendercontent` tag. Here is a simple example: +Including a component within a content document or design template is done via a `render` tag or `rendercontent` tag. Here's an example: {% raw %} ```liquid diff --git a/bridgetown-website/src/_docs/components/lit.md b/bridgetown-website/src/_docs/components/lit.md index 6f9d15bc4..9254bbd2c 100644 --- a/bridgetown-website/src/_docs/components/lit.md +++ b/bridgetown-website/src/_docs/components/lit.md @@ -15,7 +15,7 @@ Through the use of Bridgetown's [Lit Renderer](https://www.github.com/bridgetown ## Installing Lit Renderer -Simply run the Bundled Configuration automation: +Run the Bundled Configuration automation: ```sh bin/bridgetown configure lit @@ -157,7 +157,7 @@ In order to separate the "globally-accessible" stylesheets you may have in `src/ * For global stylesheets, use the standard `.css` suffix. * For Lit component stylesheets, use a `.lit.css` suffix. -Bridgetown's bundled Lit configuration provides the building blocks for this setup. You'll need to edit a few lines in your `frontend/javascript/index.js` and `esbuild.config.js` files to opt into this (just look at the comments in the files). Once completed, you'll be able to write components such as this: +Bridgetown's bundled Lit configuration provides the building blocks for this setup. You'll need to edit a few lines in your `frontend/javascript/index.js` and `esbuild.config.js` files to opt into this (look at the comments in the files). Once completed, you'll be able to write components such as this: ```js // _src/components/my-nifty-tag.lit.js diff --git a/bridgetown-website/src/_docs/components/ruby.md b/bridgetown-website/src/_docs/components/ruby.md index e0859312d..d8a9110b0 100644 --- a/bridgetown-website/src/_docs/components/ruby.md +++ b/bridgetown-website/src/_docs/components/ruby.md @@ -32,7 +32,7 @@ end output: Hello from MyComponent! ``` -To pass variables along to a component, simply write an `initialize` method. You can also use Ruby's "squiggly heredoc" syntax as a kind of template language: +To pass variables along to a component, write an `initialize` method. You can also use Ruby's "squiggly heredoc" syntax as a kind of template language: ```ruby class FieldComponent @@ -150,7 +150,7 @@ The `slotted` helper can also provide default content should the slot not alread Multiple captures using the same slot name will be cumulative. The above `image` slot could be appended to by calling `slot :image` multiple times. If you wish to change this behavior, you can pass `replace: true` as a keyword argument to `slot` to clear any previous slot content. _Use with extreme caution!_ -For more control over slot content, you can use the `pre_render` hook. Builders can register hooks to transform slots in specific ways based on their name or context. This is perhaps not all that useful when you're writing both the content and the components, but for easy customization of third-party components it could come in handy. +For more control over slot content, you can use the `pre_render` hook. Builders can register hooks to transform slots in specific ways based on their name or context. This is perhaps not all that useful when you're writing both the content and the components, but for customization of third-party components it could come in handy. ```rb class Builders::FigureItOut < SiteBuilder @@ -178,7 +178,7 @@ end ### Helpers -As expected, helpers are available as well just like in standard templates: +As expected, helpers are available as well exactly like in standard templates: ```erb @@ -207,7 +207,7 @@ end ### Lifecycle -In addition to simply rendering a template for you, `Bridgetown::Component` provides a couple lifecycle hooks: +In addition to rendering a template for you, `Bridgetown::Component` provides a couple lifecycle hooks: * `render?` – if you define this method and return `false`, the component will not get rendered at all. * `before_render` – called right before the component is rendered when the view_context is known and all helpers available. diff --git a/bridgetown-website/src/_docs/configuration/initializers.md b/bridgetown-website/src/_docs/configuration/initializers.md index 686b87a53..39c75d78b 100644 --- a/bridgetown-website/src/_docs/configuration/initializers.md +++ b/bridgetown-website/src/_docs/configuration/initializers.md @@ -110,7 +110,7 @@ init :stripe do end ``` -Inside of the block, you can use the DSL just like in the main `configure` block. You can also reference keys that were previously set: +Inside of the block, you can use the same DSL as the main `configure` block. You can also reference keys that were previously set: ```rb init :some_initializer do @@ -119,7 +119,7 @@ init :some_initializer do end ``` -These configuration values will get passed directly to the initializer. But what if the plugin requires you to set values on the main config instead (as many legacy Bridgetown plugins will)? No problem! While it's not strictly necessary, you can still use the init block and just reference the main config object from enclosing scope for a clear visual grouping: +These configuration values will get passed directly to the initializer. But what if the plugin requires you to set values on the main config instead (as many legacy Bridgetown plugins will)? No problem! While it's not strictly necessary, you can still use the init block and reference the main config object from enclosing scope for a clear visual grouping: ```rb init :legacy_plugin do @@ -210,7 +210,7 @@ end While it's not strictly required that you place a Roda block inside of an `only :server do` block, it's probably a good idea that you do since Roda blocks aren't used in any other configuration context. {%@ Note do %} - As mentioned above, you can still add and configure plugins directly in your Roda class file (`server/roda_app.rb`) just like any standard Roda application, but using a Roda configuration block alongside your other initialization steps is a handy way to keep everything consolidated. Bear in mind that the Roda blocks are all executed prior to anything defined within the class-level code of `server/roda_app.rb`, so if you write any code in a Roda block that relies on state having already been defined in the app class directly, it will fail. Best to keep Roda block code self-contained, or reliant only on other settings in the Bridgetown initializers file. + As mentioned above, you can still add and configure plugins directly in your Roda class file (`server/roda_app.rb`) like any standard Roda application, but using a Roda configuration block alongside your other initialization steps is a handy way to keep everything consolidated. Bear in mind that the Roda blocks are all executed prior to anything defined within the class-level code of `server/roda_app.rb`, so if you write any code in a Roda block that relies on state having already been defined in the app class directly, it will fail. Best to keep Roda block code self-contained, or reliant only on other settings in the Bridgetown initializers file. {% end %} ### SSR & Dynamic Routes @@ -266,11 +266,11 @@ require_relative "../ruby_code_file.rb" ## Built-in Initializers -Bridgetown ships with several initializers you can add to your configuration. In future versions of Bridgetown, we expect to make our overall architecture a little more modular so you can use the initializer system to specify just those key features you need (and by omission which ones you don't!). +Bridgetown ships with several initializers you can add to your configuration. In future versions of Bridgetown, we expect to make our overall architecture a little more modular so you can use the initializer system to specify only those key features you need (and by omission which ones you don't!). ### Dotenv -The Dotenv gem provides a simple way to manage environment variables with your Bridgetown project. Simply add the gem to your Gemfile (`bundle add dotenv`), and then add the initializer to your configuration: +The Dotenv gem allows you to manage environment variables with your Bridgetown project. Add the gem to your Gemfile (`bundle add dotenv`), and then add the initializer to your configuration: ```rb init :dotenv diff --git a/bridgetown-website/src/_docs/content/dsd.md b/bridgetown-website/src/_docs/content/dsd.md index 315ff06d8..b4eb2548d 100644 --- a/bridgetown-website/src/_docs/content/dsd.md +++ b/bridgetown-website/src/_docs/content/dsd.md @@ -7,7 +7,7 @@ category: layouts _Welcome to the future!_ Declarative Shadow DOM ([DSD](https://konnorrogers.com/posts/2023/what-is-declarative-shadow-dom/)) represents a huge shift in the way we architect and promote modularity on a web page. You can use DSD in your [layouts](/docs/layouts), [components](/docs/components), and generally anywhere it would be beneficial to increase the separation between presentation logic & content and work with advanced scoped styling APIs. -Heads up: if you're upgrading from Bridgetown 1.2 or previous, you'll need to be using esbuild (not Webpack) and must update your base esbuild configuration. It's a snap! Just run: +Heads up: if you're upgrading from Bridgetown 1.2 or previous, you'll need to use esbuild (not Webpack) and update your base esbuild configuration: ```shell bin/bridgetown esbuild update @@ -47,7 +47,7 @@ It's helpful to describe the power and flexibility of DSD by comparing it to wha ``` -Oops, this isn't what we want. By simply styling the `header` tag, we've affected both the main header of the page and the header of an individual article block. Let's adding some selector-based scoping to remedy this: +Oops, this isn't what we want. By styling the `header` tag, we've affected both the main header of the page and the header of an individual article block. Let's adding some selector-based scoping to remedy this: ```html @@ -131,7 +131,7 @@ What's great about this approach is: 1. Only the element with a DSD template is affected by the associated styles. The `header` tag at the `body` level, and the `header` tag at the `article` level are separated from each other behind shadow boundaries. This provides what we like to call _encapsulation_ (borrowing terminology from object-oriented programming). Before all HTML + styles operated in a single global namespace called "the DOM". Now we can actually define encapsulated HTML + style DOM trees! 2. Scoping isn't just about styles…it works in JavaScript too! Consider `document.body.querySelectorAll("header")`. Normally, this would give you a list of all `header` tags across the entire webpage, no matter where they appear. But now, you could call `document.body.shadowRoot.querySelectorAll("header")` and get that single header in your DSD template. _Wut??_ Yep, it totally works. -3. By utilizing the [slots mechanism](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#adding_flexibility_with_slots) that's part of the shadow DOM spec, you can build your DSD template around various pieces of presentation logic, styled by the template accordingly, and then in the "light DOM" your content can reference those slots to make it *super obvious* what the content is and how it might get presented. Of course many server-side templating systems, Bridgetown included, can make this somewhat clear from a development standpoint by providing building blocks such as layouts and resources and components, but by the time it gets to the browser, you don't really have any sense how the content and the presentation logic are built out and modularized. **Everything just gets flatted into a tree of DOM nodes.** With shadow DOM, you can actually see at the markup and browser dev tools levels how everything gets composed together across your components and templates, making inspecting and debugging much easier. It's like HTML suddenly got super powers! +3. By utilizing the [slots mechanism](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#adding_flexibility_with_slots) that's part of the shadow DOM spec, you can build your DSD template around various pieces of presentation logic, styled by the template accordingly, and then in the "light DOM" your content can reference those slots to make it *super obvious* what the content is and how it might get presented. Of course many server-side templating systems, Bridgetown included, can make this somewhat clear from a development standpoint by providing building blocks such as layouts and resources and components, but by the time it gets to the browser, you don't really have any sense how the content and the presentation logic are built out and modularized. **Everything gets flatted into a tree of DOM nodes.** With shadow DOM, you can actually see at the markup and browser dev tools levels how everything gets composed together across your components and templates, making inspecting and debugging much easier. It's like HTML suddenly got super powers! In addition to the benefits above, you also have the ability to leverage [CSS Shadow Parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) (which only work when you have, er, shadow DOM—hence the name!). What's a shadow part? It's when you use the `part=` attribute on an element inside your DSD template, and by doing so it makes it styleable from the "outside". Defining parts and labeling them appropriately is a fantastic way to build up a true "style API" for each layout or component. diff --git a/bridgetown-website/src/_docs/content/front-matter-defaults.md b/bridgetown-website/src/_docs/content/front-matter-defaults.md index 72fe2e4ae..dcd1db8cd 100644 --- a/bridgetown-website/src/_docs/content/front-matter-defaults.md +++ b/bridgetown-website/src/_docs/content/front-matter-defaults.md @@ -15,7 +15,7 @@ There are two ways to accomplish this: the data cascade, and via your site's con You can add `_defaults.yml` (also `.yaml` or `.json`) files anywhere in your source tree, which will then cause a "data cascade". In other words, any resources in that folder or in a subfolder will use the front matter data contained in the defaults file. Defaults files in subfolders can also potentially overwrite values contained in parent folders (hence the term "cascade"). -For example, if you want all "posts" collection resources to have the layout "post" without having to repeatedly write `layout: post` front matter, simply add `_defaults.yml` to the `src/_posts` folder: +For example, if you want all "posts" collection resources to have the layout "post" without having to repeatedly write `layout: post` front matter, add `_defaults.yml` to the `src/_posts` folder: ```yaml layout: post @@ -34,13 +34,13 @@ Also, keep in mind these are "default" values, so if you were to add `layout: so {%@ Note do %} #### Trick out your collections - Defaults files work well for custom collections! Just add a `_defaults.yml` to the collection root folder to set layouts and other variables for your entire collection. + Defaults files work well for custom collections! Add a `_defaults.yml` to the collection root folder to set layouts and other variables for your entire collection. {% end %} {%@ Note do %} #### Think globally - You can also add a defaults file to `src` itself! For example, if you wanted every resource on your site to start off with a default thumbnail image, you could simply add `image: /images/thumbnail_image.jpg` to a defaults file in `src` and it would apply globally. + You can also add a defaults file to `src` itself! For example, if you wanted every resource on your site to start off with a default thumbnail image, you could add `image: /images/thumbnail_image.jpg` to a defaults file in `src` and it would apply globally. {% end %} ## Configuration-based Front Matter Defaults diff --git a/bridgetown-website/src/_docs/content/pagination.md b/bridgetown-website/src/_docs/content/pagination.md index 78796c9e1..9a9e02484 100644 --- a/bridgetown-website/src/_docs/content/pagination.md +++ b/bridgetown-website/src/_docs/content/pagination.md @@ -7,18 +7,16 @@ category: resources {%@ "docs/help_needed", resource: resource %} -Pagination support is built-in to Bridgetown, but it is not enabled by default. To enable it on your site, simply add: +Pagination support is built-in to Bridgetown, but it is not enabled by default. You can enable it in the config file using: ```yml pagination: enabled: true ``` -to your config file. - ## Page Configuration -To facilitate pagination on any given page (like `index.html`, `blog.md`, etc.) then simply include configuration in the resource's front matter to specify which collection you'd like to paginate through: +To facilitate pagination on any given page (like `index.html`, `blog.md`, etc.) then include configuration in the resource's front matter to specify which collection you'd like to paginate through: ``` yml --- @@ -65,7 +63,7 @@ exclude_from_pagination: true ## Pagination Links -To display pagination links, simply use the `paginator` Liquid object as follows: +To display pagination links, use the `paginator` Liquid object as follows: {% raw %} ``` html diff --git a/bridgetown-website/src/_docs/content/permalinks.md b/bridgetown-website/src/_docs/content/permalinks.md index 77b2413a7..1395f4a3e 100644 --- a/bridgetown-website/src/_docs/content/permalinks.md +++ b/bridgetown-website/src/_docs/content/permalinks.md @@ -5,7 +5,7 @@ top_section: Writing Content category: resources --- -A permalink is simply the determination of what the output URL of your [resource](/docs/resources) will be. Every resource uses a _permalink processer_ to figure out where to save your transformed resource in the output folder tree. +A permalink is the determination of what the output URL of your [resource](/docs/resources) will be. Every resource uses a _permalink processer_ to figure out where to save your transformed resource in the output folder tree. Resources in the **pages** collection are the most straightforward. The filenames and folder structure of your pages will result in matching output URLs. For example, a file saved at `src/_pages/this/is/great.md` would be output to `/this/is/great/`. @@ -18,7 +18,7 @@ The available styles are: * `simple`: `/[locale]/:categories/:slug/` * `simple_ext`: `[locale]/:categories/:slug.*` -(Including `.*` at the end simply means it will output the resource with its own slug and extension. Alternatively, `/` at the end will put the resource in a folder of that slug with `index.html` inside.) +(Including `.*` at the end means it will output the resource with its own slug and extension. Alternatively, `/` at the end will put the resource in a folder of that slug with `index.html` inside.) To set a permalink style or template for a **custom collection**, add it to your collection metadata in `bridgetown.config.yml`. For example: diff --git a/bridgetown-website/src/_docs/core-concepts.md b/bridgetown-website/src/_docs/core-concepts.md index 228959b8a..a720b3bc1 100644 --- a/bridgetown-website/src/_docs/core-concepts.md +++ b/bridgetown-website/src/_docs/core-concepts.md @@ -6,7 +6,7 @@ category: core_concepts next_page_order: 25 --- -It's easy to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed as atomic artifacts, but they can optionally provide dynamic routes via a secondary server process. This means the website your visitors will ultimately engage with was largely produced as a "snapshot in time"—the product of Bridgetown's build process. How does that process work? Let's find out! +We've made it as easy as we could to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed as atomic artifacts, but they can optionally provide dynamic routes via a secondary server process. This means the website your visitors will ultimately engage with was largely produced as a "snapshot in time"—the product of Bridgetown's build process. How does that process work? Let's find out! ## The Build Process @@ -74,6 +74,6 @@ Bridgetown provides a [full SSR pipeline powered by the Roda web toolkit](/docs/ There is detailed documentation available about each and every step mentioned above, so feel free to poke around and read up on the topics which interest you the -most. And as always, if you get stuck or have follow-up questions, just hop in one +most. And as always, if you get stuck or have follow-up questions, hop in one of our [community channels](/community) and a friendly Bridgetowner will endeavor to help you out! diff --git a/bridgetown-website/src/_docs/datafiles.md b/bridgetown-website/src/_docs/datafiles.md index 3a60e06ec..ccda88c9f 100644 --- a/bridgetown-website/src/_docs/datafiles.md +++ b/bridgetown-website/src/_docs/datafiles.md @@ -127,7 +127,7 @@ The organizations can then be accessed via `site.data.orgs`, followed by the fil New for Bridgetown 1.2: for easier access to data in your templates whether that data comes from the resource directly or from data files, you can use [front matter](/docs/front-matter/) to specify a data path for merging into the resource. -Just define a front matter variable in a resource like so: +Define a front matter variable in a resource like so: ```yaml --- @@ -136,7 +136,7 @@ projects: site.data.projects --- ``` -Now in your template you can reference `data.projects` just like you might `data.title` or any other front matter variable. You can even use [front matter defaults](/docs/content/front-matter-defaults/) to assign such a data variable to multiple resources at once. +Now in your template you can reference `data.projects` exactly like `data.title` or any other front matter variable. You can even use [front matter defaults](/docs/content/front-matter-defaults/) to assign such a data variable to multiple resources at once. ### Example: Accessing a Specific Author diff --git a/bridgetown-website/src/_docs/deployment.md b/bridgetown-website/src/_docs/deployment.md index e4b7afbc8..d4bb4f966 100644 --- a/bridgetown-website/src/_docs/deployment.md +++ b/bridgetown-website/src/_docs/deployment.md @@ -9,8 +9,7 @@ Bridgetown generates your site and saves it to the `output` directory by default transfer the contents of this directory to almost any hosting provider to make your site go live. -Bridgetown's included site template automatically provides a Rake task you can run to -build both your frontend bundle and your static website. Simply run +Bridgetown's included site template automatically provides a Rake task you can run to build both your frontend bundle and your static website: ```shell bin/bridgetown deploy @@ -34,7 +33,7 @@ Some popular services include: ### Render -[Render](https://render.com) provides the easiest cloud for all your static sites, APIs, databases, and containers. Render is a unified platform which can build and run apps and websites with free SSL, a global CDN, private networks, and auto deploys from Git. Use Render's simple admin dashboard or write an "infrastructure as code" YAML file to configure all your services at once. The choice is yours. +[Render](https://render.com) provides the easiest cloud for all your static sites, APIs, databases, and containers. Render is a unified platform which can build and run apps and websites with free SSL, a global CDN, private networks, and auto deploys from Git. Use Render's admin dashboard or write an "infrastructure as code" YAML file to configure all your services at once. The choice is yours. ### Vercel @@ -50,7 +49,7 @@ Some popular services include: ## Manual Deployment -For a simple method of deployment, you can simply transfer the contents of your `output` folder to any web server. You can use something like `scp` to securely copy the folder, or you can use a more advanced tool: +The most basic method of deployment is transferring the contents of your `output` folder to any web server. You can use something like `scp` to securely copy the folder, or you can use a more advanced tool: ### rsync @@ -60,11 +59,11 @@ rsync in the [Digital Ocean tutorial](https://www.digitalocean.com/community/tut ### Docker -Many modern hosting solutions support deploying with a `Dockerfile`. Building a Bridgetown site for one of these services is as easy as creating a `Dockerfile` in the root directory of your project. See the examples below. +Many modern hosting solutions support deploying with a `Dockerfile`. To build a Bridgetown site for one of these services, create a `Dockerfile` in the root directory of your project. See the examples below. #### Static Site -If you're simply looking to deploy a static version of your site. +If you're looking to deploy a static version of your site. ```Dockerfile # Build frontend JS and CSS assets using ESbuild @@ -202,7 +201,7 @@ This can be achieved by including a `script:` command like this in your pages: # Other directives script: - # Add this ligne just after apt update + # Add this ligne right after apt update - apt-get install -y brotli # Build the public/ directory first - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \; @@ -227,8 +226,6 @@ Make sure to update your repo's GitHub Pages Settings at `https://github.com/DSL. Any valid method call made directly in the block will translate to a front matter key. Let's rewrite the above example: +Besides using a `Hash`, you can also use the handy `front_matter` DSL. Any valid method call made directly in the block will translate to a front matter key. Let's rewrite the above example: ```md ~~~ruby diff --git a/bridgetown-website/src/_docs/frontend-assets.md b/bridgetown-website/src/_docs/frontend-assets.md index c8cae5606..7e063ac97 100644 --- a/bridgetown-website/src/_docs/frontend-assets.md +++ b/bridgetown-website/src/_docs/frontend-assets.md @@ -16,7 +16,7 @@ Bridgetown provides a fully-integrated frontend bundling system using esbuild. Y Files to be processed by esbuild are placed in the top-level `frontend` folder within your site root. This folder is entirely separate from the Bridgetown source folder where your content, templates, plugins, etc. live. However, using relative paths you can reference files in your frontend that live in the `src` folder (so you can place component-scoped JS/CSS files alongside Liquid or Ruby templates, for example). {%@ Note do %} -Wondering where to save images? Look at the `src/images` folder. You can reference them from both markup and CSS simply using a relative URL (for example, `/images/logo.svg`). Optionally, you can bundle images through esbuild and reference them with the `asset_path` helper (more information below). If you're interested in a full-featured image management solution with the ability to resize and optimize your media sizes, check out [Cloudinary](https://www.cloudinary.com) and the [bridgetown-cloudinary plugin](https://github.com/bridgetownrb/bridgetown-cloudinary). +Wondering where to save images? Look at the `src/images` folder. You can reference them from both markup and CSS using a relative URL (for example, `/images/logo.svg`). Optionally, you can bundle images through esbuild and reference them with the `asset_path` helper (more information below). If you're interested in a full-featured image management solution with the ability to resize and optimize your media sizes, check out [Cloudinary](https://www.cloudinary.com) and the [bridgetown-cloudinary plugin](https://github.com/bridgetownrb/bridgetown-cloudinary). {% end %} Bridgetown uses NPM to install and manage frontend-based packages and dependencies. [Gem-based plugins can instruct Bridgetown](/docs/plugins/gems-and-frontend/) to add a related NPM package whenever Bridgetown first loads the gem. @@ -32,7 +32,7 @@ Because Bridgetown utilizes standard ES bundler functionality, you can trick out {%@ Note do %} #### What about TypeScript? - TypeScript is one of the many transpile-to-JavaScript languages available today. TypeScript code isn't directly compatible with native JavaScript environments and always requires a build step. It's main selling point is static type-checking. However, it's possible to use type-checking and gain the secondary benefits of documentation popups and project navigation using JSDoc in vanilla JavaScript! In fact, simply by adding `// @ts-check` to the top of a `.js` file, VSCode for example will immediately provide TypeScript-like features as you author your code. + TypeScript is one of the many transpile-to-JavaScript languages available today. TypeScript code isn't directly compatible with native JavaScript environments and always requires a build step. It's main selling point is static type-checking. However, it's possible to use type-checking and gain the secondary benefits of documentation popups and project navigation using JSDoc in vanilla JavaScript! In fact, by adding `// @ts-check` to the top of a `.js` file, VSCode for example will immediately provide TypeScript-like features as you author your code. Bridgetown happily endorses JSDoc-enhanced JavaScript for a 100% ES spec-compatible development environment. [You can learn more about this approach on the TypeScript website.](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html) {% end %} @@ -61,19 +61,19 @@ There's also a [Bundled Configuration](/docs/bundled-configurations#bridgetown-r The starting place for Sass code lives at `frontend/styles/index.scss`. -Importing common CSS frameworks such as Bootstrap, Foundation, Bulma and so forth is often as easy as running: +To import common CSS frameworks such as Bootstrap, Foundation, Bulma and so forth, you can run: ```shell npm install name-of-css-framework ``` -And then adding: +And then add: ```css @import "~css-framework/css-framework"; ``` -to `index.scss`. For example, to add [Bulma](https://bulma.io) which is a modern CSS-only (no JavaScript) framework built around Flexbox, you'd simply run: +to `index.scss`. For example, to add [Bulma](https://bulma.io) which is a modern CSS-only (no JavaScript) framework built around Flexbox, you'd run: ```shell npm install bulma @@ -101,7 +101,7 @@ npm install bootstrap Bridgetown's default esbuild configuration is set up to place all compiled output into the `_bridgetown` folder in your `output` folder. Bridgetown knows when it regenerates a website not to touch anything in `_bridgetown` as that comes solely from the frontend bundler. It is recommended you do not use the site source folder to add anything to `_bridgetown` as that will not get cleaned and updated by Bridgetown's generation process across multiple builds. -To reference the compiled JS and CSS files from the frontend bundler in your site template, simply add the `asset_path` Liquid tag or Ruby helper to your HTML ``. For example: +To reference the compiled JS and CSS files from the frontend bundler in your site template, add the `asset_path` Liquid tag or Ruby helper to your HTML ``. For example: {% raw %} ```liquid @@ -125,7 +125,7 @@ There's a catch with regard to how this works, because you'll also want to be ab **So here's what you'll want to do:** -* For any files saved inside of `src`, use server-relative paths. For example: `background: url(/images/photo.jpg)` in a frontend CSS file would simply point to what is saved at `src/images/photo.jpg`. +* For any files saved inside of `src`, use server-relative paths. For example: `background: url(/images/photo.jpg)` in a frontend CSS file would point to what is saved at `src/images/photo.jpg`. * For any files saved inside of `frontend`, use filesystem-relative paths. For example: `background: url("../images/photo.jpg")` in `frontend/styles/index.css` will look for `frontend/images/photo.jpg`. If the file can't be found, esbuild will throw an error. You can use the `asset_path` Liquid tag/Ruby helper to reference assets within the `frontend` folder: diff --git a/bridgetown-website/src/_docs/index.md b/bridgetown-website/src/_docs/index.md index ff381ce26..e66b9e91a 100644 --- a/bridgetown-website/src/_docs/index.md +++ b/bridgetown-website/src/_docs/index.md @@ -74,6 +74,6 @@ Bridgetown is sometimes called a "static site generator" or a "Jamstack" web fra Bridgetown works best as part of a version-controlled repository powered by Git. You'll likely want to store your repository on a service like [GitHub](https://github.com) so that you and everyone else working on the website (plus your hosting provider) all have direct, secure access to the latest website content and design files. -During the development process, you'll run Bridgetown from the command line on your local development machine (or perhaps a remote staging server). Once content is ready to publish, you'll want to commit your website codebase to the Git repository and use an automated build tool to generate and upload the final output to a server or CDN (Content Delivery Network). [Render](https://www.render.com) is a popular service for this, but there are many others. You can also just literally copy the generated files contained in the `output` folder to any HTTP web server and it should Just Work. 😊 +During the development process, you'll run Bridgetown from the command line on your local development machine (or perhaps a remote staging server). Once content is ready to publish, you'll want to commit your website codebase to the Git repository and use an automated build tool to generate and upload the final output to a server or CDN (Content Delivery Network). [Render](https://www.render.com) is a popular service for this, but there are many others. You can also copy the generated files contained in the `output` folder to any HTTP web server and it should Just Work. 😊 For more details on how the Bridgetown build process works and what goes into creating a site, continue on to read our **Core Concepts** guide. diff --git a/bridgetown-website/src/_docs/installation/macos.md b/bridgetown-website/src/_docs/installation/macos.md index 2316b446e..8447972ad 100644 --- a/bridgetown-website/src/_docs/installation/macos.md +++ b/bridgetown-website/src/_docs/installation/macos.md @@ -37,7 +37,7 @@ ruby -v > ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [arm64-darwin20] ``` -(If for some reason `bundler` isn't installed automatically, just run `gem install bundler -N`) +(If for some reason `bundler` isn't installed automatically, run `gem install bundler -N`) And that's it! Check out [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects. diff --git a/bridgetown-website/src/_docs/installation/ubuntu.md b/bridgetown-website/src/_docs/installation/ubuntu.md index 28b0326df..cd988a680 100644 --- a/bridgetown-website/src/_docs/installation/ubuntu.md +++ b/bridgetown-website/src/_docs/installation/ubuntu.md @@ -78,7 +78,7 @@ ruby -v > ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [aarch64-linux] ``` -(If for some reason `bundler` isn't installed automatically, just run `gem install bundler -N`) +(If for some reason `bundler` isn't installed automatically, run `gem install bundler -N`) And that's it! Check out [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects. diff --git a/bridgetown-website/src/_docs/installation/upgrade.md b/bridgetown-website/src/_docs/installation/upgrade.md index 57733d0ca..66cc03b39 100644 --- a/bridgetown-website/src/_docs/installation/upgrade.md +++ b/bridgetown-website/src/_docs/installation/upgrade.md @@ -19,7 +19,7 @@ The first thing to know is that there are new minimum versions of both Ruby and * Ruby 3.1.4 (⚠️ there's a bug in earlier versions of Ruby 3.1 which will prevent Bridgetown to run) * Node 20.6 (⚠️ earlier versions of Node aren't compatible with esbuild's ESM-based config) -Sometimes that's as simple as changing your version dotfiles (for example `.ruby-version` and `.nvmrc`). We do recommend switching to the latest versions (Ruby 3.3 and Node 22 LTS or 23 as of the time of this writing) if possible. +If you use versioning dotfiles (for example `.ruby-version` and `.nvmrc`), you'll want to update those in your projects. We do recommend switching to the latest versions (Ruby 3.3 and Node 22 LTS or 23 as of the time of this writing) if possible. To upgrade to Bridgetown 2.0, edit your `Gemfile` to update the version numbers in the argument for the `bridgetown` and `bridgetown-routes` (if applicable) gem to `2.0.0.beta2` and then run `bundle update bridgetown`. @@ -33,7 +33,9 @@ Only update your esbuild configuration if you're also willing to switch to ESMod ### Switching from Yarn to NPM 📦 -Bridgetown uses NPM now by default, rather than Yarn, for frontend package managing. You may continue to use Yarn on your existing projects, but if you'd like to switch to NPM, you can simply delete your `yarn.lock` file, run `npm install` (shorthand: `npm i`), and check in `package-lock.json` instead. You can also use [pnpm](https://pnpm.io) if you prefer. Bridgetown is now compatible with all three package managers. +Bridgetown uses NPM now by default, rather than Yarn, for frontend package managing. You may continue to use Yarn on your existing projects, but if you'd like to switch to NPM, you can delete your `yarn.lock` file, run `npm install` (shorthand: `npm i`), and check in `package-lock.json` instead. You can also use [pnpm](https://pnpm.io) if you prefer. Bridgetown is now compatible with all three package managers. + +You'll also need to update the `:frontend` tasks in your project's `Rakefile` to use your preferred package manager. ### Specifying Liquid (if necessary) 💧 @@ -63,6 +65,16 @@ class RodaApp < Roda end ``` +Additionally, you may also hit the following error: + +``` +Exception raised: Errno::ENOENT +No such file or directory @ rb_sysopen - /tmp/pids/aux.pid +``` + +In which case, refer to the above fix for configuring your Roda server. + + ### Supporting Active Support Support 😏 Bridgetown v2 has removed a number of dependencies in the codebase on the Active Support gem (provided by the Rails framework). If that ends up causing problems with your codebase, you may need to require Active Support manually (and even Action View) in your `config/initializers.rb` file. [Here's a thread on GitHub](https://github.com/bridgetownrb/bridgetown/pull/881#issuecomment-2228693932) referencing this situation. diff --git a/bridgetown-website/src/_docs/internationalization.md b/bridgetown-website/src/_docs/internationalization.md index 442c35f2e..73a12845e 100644 --- a/bridgetown-website/src/_docs/internationalization.md +++ b/bridgetown-website/src/_docs/internationalization.md @@ -132,18 +132,18 @@ en: There are many other useful features of the **i18n** gem, so feel free to peruse the [Rails Guide to Internationalization](https://guides.rubyonrails.org/i18n.html) for additional documentation. {%@ Note do %} -In Ruby, the `t` helper is simply shorthand for `I18n.t`, so if you find yourself in a context where `t` is not available—perhaps in a plugin—you can write `I18n.t` directly. +In Ruby, the `t` helper is shorthand for `I18n.t`, so if you find yourself in a context where `t` is not available—perhaps in a plugin—you can write `I18n.t` directly. {% end %} ## Localizing dates -To ensure dates are displayed using the active locale, you'll need to localize them using `I18n.l`, or use the provided shortcut: `l` (just like you would in a Rails project). +To ensure dates are displayed using the active locale, you'll need to localize them using `I18n.l`, or use the provided shortcut: `l`. -By simply adding `gem "rails-i18n"` to your `Gemfile`, you'll get localized month and day names, along with standard date and time formats in each locale supported by that gem. +By adding `gem "rails-i18n"` to your `Gemfile`, you'll get localized month and day names, along with standard date and time formats in each locale supported by that gem. You can also define your own localization for date and time. {%@ Note do %} -In Ruby, the `l` helper is simply shorthand for `I18n.l`, so if you find yourself in a context where `l` is not available—perhaps in a plugin—you can write `I18n.l` directly. +In Ruby, the `l` helper is shorthand for `I18n.l`, so if you find yourself in a context where `l` is not available—perhaps in a plugin—you can write `I18n.l` directly. {% end %} ## Localizing Your Resources and Templates diff --git a/bridgetown-website/src/_docs/islands.md b/bridgetown-website/src/_docs/islands.md index 780e7010b..828454d18 100644 --- a/bridgetown-website/src/_docs/islands.md +++ b/bridgetown-website/src/_docs/islands.md @@ -15,7 +15,7 @@ Islands architecture is constantly evolving, so your feedback is crucial as we i ## Creating Your First Island -If you've just created a new Bridgetown project, you're ready to take it to the next level. If you're upgrading from Bridgetown 1.2 or previous, you'll need to be using esbuild (not Webpack) and must update your base esbuild configuration. It's a snap! Just run: +If you've just created a new Bridgetown project, you're ready to take it to the next level. If you're upgrading from Bridgetown 1.2 or previous, you'll need to use esbuild (not Webpack) and update your base esbuild configuration: ```shell bin/bridgetown esbuild update @@ -53,7 +53,7 @@ With ``, of course! ## Installing the Island -Bridgetown comes with a [bundled configuration](/docs/bundled-configurations) to set up the `` web component, [a tiny package](https://is-land.11ty.dev) which lets you _lazy-load_ islands just as they become visible on-screen or are interacted with (aka clicked). +Bridgetown comes with a [bundled configuration](/docs/bundled-configurations) to set up the `` web component, [a tiny package](https://is-land.11ty.dev) which lets you _lazy-load_ islands when they become visible on-screen or are interacted with (aka clicked). Run this command to add it to your main JavaScript bundle: @@ -75,7 +75,7 @@ Let's break this down: 1. The `` tag gets set up to import the new `breezy.js` island you've created once it's visible to the reader. 2. At first the `` element will be undefined, but once the island loads, it will be upgraded/hydrated. -3. Once that moment occurs, the "Approaching…" text will get replaced with "Welcome…". That's just a simple example—more likely you'd want to write your island JavaScript to set up event handlers, or display more up-to-the-second data pulled from an API, etc. +3. Once that moment occurs, the "Approaching…" text will get replaced with "Welcome…". That's a simple example. You'd likely want to write your island JavaScript to set up event handlers, or display more up-to-the-second data pulled from an API, etc. ## Rendering Island Components in Ruby @@ -101,7 +101,7 @@ And then define our `element.erb` template: ``` -Now in our original page template code, we can simply render the component and that's that. +Now in our original page template code, we can render the component and that's that. ```erb @@ -151,4 +151,4 @@ Sidecar CSS files processed through the `dsd_style` helper do not get run throug ## Routes in Islands -When using the `bridgetown-routes` plugin for server rendering, you can put file-based routes inside of islands. Just add a `routes` folder inside of an island folder (like the `src/_islands/breezy_day` example above), and then any routes inside will resolve to a URL of the island name plus the route name. Read our [Routes documentation](/docs/routes) for more information. +When using the `bridgetown-routes` plugin for server rendering, you can put file-based routes inside of islands. Add a `routes` folder inside of an island folder (like the `src/_islands/breezy_day` example above), and then any routes inside will resolve to a URL of the island name plus the route name. Read our [Routes documentation](/docs/routes) for more information. diff --git a/bridgetown-website/src/_docs/layouts.md b/bridgetown-website/src/_docs/layouts.md index 3290ae1dc..ea763c115 100644 --- a/bridgetown-website/src/_docs/layouts.md +++ b/bridgetown-website/src/_docs/layouts.md @@ -109,7 +109,7 @@ Now posts can use this layout while the rest of the resources use the default. ## Variables -You can set front matter in layouts as well. Just use the `layout` variable instead of `resource`. For example: +You can set front matter in layouts as well. Use the `layout` variable instead of `resource`. For example: {% raw %} ```liquid diff --git a/bridgetown-website/src/_docs/migrating/jekyll.md b/bridgetown-website/src/_docs/migrating/jekyll.md index 2ce1d78a6..d822fb3ef 100644 --- a/bridgetown-website/src/_docs/migrating/jekyll.md +++ b/bridgetown-website/src/_docs/migrating/jekyll.md @@ -6,9 +6,9 @@ back_to: migrating-from order: 0 --- -While Bridgetown still bears conceptual similarities to Jekyll at first glance, quite a lot has changed. ([Just read this rundown of 40 new and enhanced features!](/docs/migrating/features-since-jekyll)) The default folder structure of a Bridgetown website is a bit different as well. Our recommendation is that, rather than try to transform an existing Jekyll repo into a Bridgetown one, you **create a new Bridgetown site from scratch** and then copy various files and content over from your Jekyll project in a systematic fashion. +While Bridgetown still bears conceptual similarities to Jekyll at first glance, quite a lot has changed. ([Read this rundown of 40 new and enhanced features!](/docs/migrating/features-since-jekyll)) The default folder structure of a Bridgetown website is a bit different as well. Our recommendation is that, rather than try to transform an existing Jekyll repo into a Bridgetown one, you **create a new Bridgetown site from scratch** and then copy various files and content over from your Jekyll project in a systematic fashion. -Here are some steps you can take to do just that: +Here are some steps you can take to do exactly that: 1. **Create your project.** After [installing Bridgetown](/docs/installation), run `bridgetown new` to create your blank repo. The `frontend` folder is for saving frontend assets (CSS, JavaScript, fonts, and possibly images), the `src` folder is for content and static files (which also may include images), and the `plugins` folder is for any custom Ruby plugins you want to add. If much of your content is primarily in Markdown or HTML file, you shouldn't have much difficulty loading them in with Bridgetown. We also support data files (YAML, JSON, CSV) in a similar fashion. [More docs here.](/docs/structure) 2. **Set up your metadata.** For metadata like your site title, email address, seo defaults, whatever, you'll generally want to put those in `src/_data/site_metadata.yml` rather than in the main config file. The bonus is, you can change these values and live reload will allow you to preview your changes in real-time. [More docs here.](/docs/datafiles) @@ -18,13 +18,13 @@ Here are some steps you can take to do just that: 6. **Update your includes.** Jekyll includes will need to be converted to Liquid components inside of `src/_components` which are accessed via the `render` tag. [More docs here.](/docs/components/liquid) 7. **Update your plugins.** Plugins will need to be updated to use Bridgetown APIs. Some "legacy" APIs are still supported (like generators) and hooks work in a similar fashion. Be sure to use the right class names and module namespaces so that your code is compatible with the Zeitwerk autoloader. [More docs here.](/docs/plugins) 8. **Find equivalent plugin gems.** For some third-party gems you might be using in your Jekyll project, there could be Bridgetown equivalents (jekyll-feed -> bridgetown-feed). [View the plugins directory.](/plugins/) -9. **Still stuck?** If you run into major roadblocks and just can't seem to get past the initial migration effort, we encourage you to [take advantage of our community support channels](/community) to help get you unstuck. Note that it's always much easier if you're able to share a repo link so someone can try to reproduce your issue and offer useful advice. +9. **Still stuck?** If you run into major roadblocks, we encourage you to [take advantage of our community support channels](/community) to help get you unstuck. Note that it's always much easier if you're able to share a repo link so someone can try to reproduce your issue and offer useful advice. ## Additional Points to Consider: **Learn new commands.** To build a Bridgetown site, run `bin/bridgetown build` (`bin/bt b` for short). To start a server, run `bin/bridgetown start` (`bin/bt s` for short). And for deployment builds, you'll want to run `bin/bridgetown deploy` and make sure the `BRIDGETOWN_ENV` environment variable is set to `production`. And a very cool feature you'll be introduced to with Bridgetown: you can run `bin/bridgetown console` (`bin/bt c` for short) to boot up an IRB-based REPL where you can inspect your collections and data, interact with plugins, and test out various bits of Ruby code right there in your terminal. [More docs here.](/docs/command-line-usage) -**What about drafts?** There's no special "drafts" folder or draft mode for content in Bridgetown. You can simply set certain items to `published: false`, and in order to see those items locally in order to preview, pass the `--unpublished` or `-U` command line option. +**What about drafts?** There's no special "drafts" folder or draft mode for content in Bridgetown. You can set certain items to `published: false`, and in order to see those items locally in order to preview, pass the `--unpublished` or `-U` command line option. **Content is less confusing.** The behavior of pages vs. posts vs. custom collection items is much closer and more predictable due to the revamped "resource" content engine in Bridgetown. There's literally a `pages` collection now (you can either store pages directly in the `src` folder or within the `_pages` subfolder), and you can configure custom collections to behave identically to the `posts` collection if you so with. Custom collection items can contribute categories and tags to the overall site (they're not posts-only). [Read more about collections.](/docs/collections) diff --git a/bridgetown-website/src/_docs/plugins.md b/bridgetown-website/src/_docs/plugins.md index 3465dac39..eb10130b7 100644 --- a/bridgetown-website/src/_docs/plugins.md +++ b/bridgetown-website/src/_docs/plugins.md @@ -238,14 +238,14 @@ plugins/my_plugin/woo/zoo.rb -> MyPlugin::Woo::Zoo You can read more about [Zeitwerk's file conventions here](https://github.com/fxn/zeitwerk#file-structure). -In addition to the `plugins` folder provided by default, **you can add your own folders** with autoloading support! Simply add to the `autoload_paths` setting in your config YAML: +In addition to the `plugins` folder provided by default, **you can add your own folders** with autoloading support! Add to the `autoload_paths` setting in your config YAML: ```yaml autoload_paths: - loadme ``` -Now any Ruby file in your project's `./loadme` folder will be autoloaded. By default, files in your custom folders not "eager loaded", meaning that the Ruby code isn't actually processed unless/until you access the class or module name of the file somewhere in your code elsewhere. This can improve performance in certain cases. However, if you need to rely on the fact that your Ruby code is always loaded when the site is instantiated, simply set `eager` to true in your config: +Now any Ruby file in your project's `./loadme` folder will be autoloaded. By default, files in your custom folders not "eager loaded", meaning that the Ruby code isn't actually processed unless/until you access the class or module name of the file somewhere in your code elsewhere. This can improve performance in certain cases. However, if you need to rely on the fact that your Ruby code is always loaded when the site is instantiated, set `eager` to true in your config: ```yaml autoload_paths: diff --git a/bridgetown-website/src/_docs/plugins/cache-api.md b/bridgetown-website/src/_docs/plugins/cache-api.md index 935ec7aa3..8fab3b157 100644 --- a/bridgetown-website/src/_docs/plugins/cache-api.md +++ b/bridgetown-website/src/_docs/plugins/cache-api.md @@ -94,7 +94,7 @@ Returns nothing. ## Temporary In-Memory Cache -The `site` object (available from within most code paths, or you can use `Bridgetown::Current.site`) exposes a `tmp_cache` hash (of type `HashWithDotAccess::Hash`). You can use this to save and recall data. Using memoization makes this quite easy: +The `site` object (available from within most code paths, or you can use `Bridgetown::Current.site`) exposes a `tmp_cache` hash (of type `HashWithDotAccess::Hash`). You can use this to save and recall data: ```ruby temporary_value = site.tmp_cache[:temporary_value] ||= do_expensive_stuff diff --git a/bridgetown-website/src/_docs/plugins/commands.md b/bridgetown-website/src/_docs/plugins/commands.md index db0bc5216..5ca85e3a2 100644 --- a/bridgetown-website/src/_docs/plugins/commands.md +++ b/bridgetown-website/src/_docs/plugins/commands.md @@ -15,7 +15,7 @@ Rails, Bundler, and Middleman. In Bridgetown 1.2, plugin gems which provide new commands won't work unless they're required within a boot file (aka `config/boot.rb`). This is likely to change in a future version of Bridgetown. In the meantime, you'll want to clarify that fact in your plugin gem's README. [More information is available here.](/docs/configuration/initializers#low-level-boot-customization) {% end %} -Simply subclass `Thor` in your plugin and use a registration block to notify +Subclass `Thor` in your plugin and use a registration block to notify Bridgetown how to include your command. Commands are written in a `command [subcommand]` format, so if your base command is `river`, your logic will be contained within one or more subcommands: diff --git a/bridgetown-website/src/_docs/plugins/external-apis.md b/bridgetown-website/src/_docs/plugins/external-apis.md index df84c5731..438c5266e 100644 --- a/bridgetown-website/src/_docs/plugins/external-apis.md +++ b/bridgetown-website/src/_docs/plugins/external-apis.md @@ -31,7 +31,7 @@ end ## Making a Request -To make a request, simply call the `get` method inside of `build` in your builder class: +To make a request, call the `get` method inside of `build` in your builder class: ```ruby def build @@ -77,7 +77,7 @@ end ## Customizing the Connection Object -Bridgetown uses the [Faraday gem](https://lostisland.github.io/faraday/) under the hood to make web requests. If you need to customize the default usage of Faraday—perhaps to set additional defaults or inject middleware to adjust the request or response logic—simply override the `connection` method in your builder class. +Bridgetown uses the [Faraday gem](https://lostisland.github.io/faraday/) under the hood to make web requests. If you need to customize the default usage of Faraday—perhaps to set additional defaults or inject middleware to adjust the request or response logic, override the `connection` method in your builder class. Here's an example of using Retry middleware to ensure requests are attempted multiple times before admitting defeat: @@ -106,9 +106,9 @@ Bridgetown comes with the [Faraday Middleware gem](https://github.com/lostisland ## The Resource Builder -Adding content from an API to the `site.data` object is certainly useful, but an even more powerful feature is the Resource Builder. All you need to do is call the `add_resource` method to generate resources which function in exactly the same way as if those files were already stored in your repository. It uses a special DSL, similar to [Ruby Front Matter](/docs/front-matter), to make assigning front matter and content very simple. +Adding content from an API to the `site.data` object is certainly useful, but an even more powerful feature is the Resource Builder. Call the `add_resource` method to generate resources which function in exactly the same way as if those files were already stored in your repository. It uses a special DSL, similar to [Ruby Front Matter](/docs/front-matter). -Here's a simple example of creating a new blog post: +Here's an example of creating a new blog post: ```ruby def build @@ -190,7 +190,7 @@ add_resource :posts, "post.html" do end ``` -This is great when you have data coming in from external APIs and you'd just like to inject all of that data into the front matter with a single method call. +This is great when you have data coming in from external APIs and you'd like to inject all of that data into the front matter with a single method call. Bear in mind that this doesn't include your `content` variable. So you'll still need to set that separately when using the `___` method, for example: @@ -222,7 +222,7 @@ end The reason it won't work is because in this example, `title` is actually interpreted as a method call within the DSL block, which means `string_value` is a similar call. That would be fine if you'd already added `string_value` as a front matter key, in which case `string_value` would return that front matter variable. But in this case, you want to use the `string_value` method of your plugin. -To accomplish that, simply provide a lambda using the `from: -> { }` syntax. Let's rewrite the above example to work as expected: +To accomplish that, provide a lambda using the `from: -> { }` syntax. Let's rewrite the above example to work as expected: ```ruby def string_value @@ -272,4 +272,4 @@ end ## Conclusion -As you've seen from these examples, using data from external APIs to create new content for your Bridgetown website is easy and straightforward with the `get` and `add_resource` methods provided by the Builder API. While there are numerous benefits to storing content directly in your site repository, Bridgetown gives you the best of both worlds—leaving you simply to decide where you want your content to live and how you'll put it to good use as you build your site. +As you've seen from these examples, you can use data from external APIs to create new content for your Bridgetown website with the `get` and `add_resource` methods provided by the Builder API. While there are numerous benefits to storing content directly in your site repository, Bridgetown gives you the best of both worlds—leaving you to decide where you want your content to live and how you'll put it to good use as you build your site. diff --git a/bridgetown-website/src/_docs/plugins/filters.md b/bridgetown-website/src/_docs/plugins/filters.md index 1b4c83406..2592a4ccd 100644 --- a/bridgetown-website/src/_docs/plugins/filters.md +++ b/bridgetown-website/src/_docs/plugins/filters.md @@ -5,7 +5,7 @@ top_section: Configuration category: plugins --- -Filters are simple Ruby methods you can provide to [Liquid templates](/docs/template-engines/liquid) to transform input data in various ways. +Filters are Ruby methods you can provide to [Liquid templates](/docs/template-engines/liquid) to transform input data in various ways. All methods take at least one argument which represents the input of the filter, and you can also support multiple method arguments (and even optional ones). The return value will be the output of the filter. @@ -34,7 +34,7 @@ http://www.example.com/mydynamicfile.js?1586194585 ## Supporting Arguments -You can accept multiple arguments to your filter by simply adding them to your block or method, and optional ones are simply specified with a default value (perhaps `nil` or `false`). For example: +You can accept multiple arguments to your filter by adding them to your block or method, and optional ones are specified with a default value (perhaps `nil` or `false`). For example: ```ruby class Builders::Filters < SiteBuilder @@ -47,7 +47,7 @@ class Builders::Filters < SiteBuilder end ``` -Then just use it like this: +You can then use it as: ```liquid {% raw %} @@ -107,7 +107,7 @@ You also have access to the Liquid context via `filters_context`, which provides ## When to use a Filter vs. a Tag -Filters are great when you want to transform input data from one format to another and potentially allow multiple transformations to be chained together. If instead you simply want to _insert_ a customized piece of content/HTML code into a page, then it's probably better to write a [Tag](/docs/plugins/tags/). +Filters are great when you want to transform input data from one format to another and potentially allow multiple transformations to be chained together. If instead you want to _insert_ a customized piece of content/HTML code into a page, then it's probably better to write a [Tag](/docs/plugins/tags/). {%@ Note do %} If you prefer to use the Legacy API (aka `Liquid::Template.register_filter `) to construct Liquid filters, refer to the [Liquid documentation](https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers) here. diff --git a/bridgetown-website/src/_docs/plugins/generators.md b/bridgetown-website/src/_docs/plugins/generators.md index e5a49b70c..3a6efefaf 100644 --- a/bridgetown-website/src/_docs/plugins/generators.md +++ b/bridgetown-website/src/_docs/plugins/generators.md @@ -13,7 +13,7 @@ You can write a generator when you need Bridgetown to add data to existing conte ## Builder API -Simply add a `generator` call to your `build` method. You can supply a block or pass in a method name as a symbol. +Add a `generator` call to your `build` method. You can supply a block or pass in a method name as a symbol. ```ruby def build diff --git a/bridgetown-website/src/_docs/plugins/helpers.md b/bridgetown-website/src/_docs/plugins/helpers.md index 1928e805f..7631577ca 100644 --- a/bridgetown-website/src/_docs/plugins/helpers.md +++ b/bridgetown-website/src/_docs/plugins/helpers.md @@ -31,7 +31,7 @@ http://www.example.com/mydynamicfile.js?1586194585 ## Supporting Arguments -You can accept multiple arguments to your helper by simply adding them to your block or method, and optional ones are simply specified with a default value (perhaps `nil` or `false`). For example: +You can accept multiple arguments to your helper by adding them to your block or method, and optional ones are specified with a default value (perhaps `nil` or `false`). For example: ```ruby class Builders::Helpers < SiteBuilder @@ -44,7 +44,7 @@ class Builders::Helpers < SiteBuilder end ``` -Then just use it like this: +Then use it like this: ```erb 5 times 10 equals <%= multiply_and_optionally_add 5, 10 %> @@ -111,7 +111,7 @@ end ``` -Now just call that helper in your template and use the `label` argument: +And then, call that helper in your template and use the `label` argument: ```eruby <%= capture_and_upcase do |label| %> diff --git a/bridgetown-website/src/_docs/plugins/hooks.md b/bridgetown-website/src/_docs/plugins/hooks.md index 3efa22b8c..11fc26e22 100644 --- a/bridgetown-website/src/_docs/plugins/hooks.md +++ b/bridgetown-website/src/_docs/plugins/hooks.md @@ -94,7 +94,7 @@ end

:after_init

-

Just after the site initializes, but before setup & render. Good +

Right after the site initializes, but before setup & render. Good for modifying the configuration of the site.

@@ -106,7 +106,7 @@ end

:after_reset

-

Just after site reset and all internal data structures are in a pristine state. Not run during SSR (see below).

+

Right after site reset and all internal data structures are in a pristine state. Not run during SSR (see below).

@@ -150,7 +150,7 @@ end

:pre_render

-

Just before rendering the whole site

+

Right before rendering the whole site

@@ -183,7 +183,7 @@ end

:pre_reload

-

Just before reloading site plugins and Zeitwerk autoloaders during the watch process or in the console

+

Right before reloading site plugins and Zeitwerk autoloaders during the watch process or in the console

@@ -227,7 +227,7 @@ end

:pre_render

-

Just before rendering a resource

+

Right before rendering a resource

@@ -271,7 +271,7 @@ end

:pre_render

-

Just before rendering a page

+

Right before rendering a page

diff --git a/bridgetown-website/src/_docs/plugins/inspectors.md b/bridgetown-website/src/_docs/plugins/inspectors.md index 9e78d5632..9731d8dce 100644 --- a/bridgetown-website/src/_docs/plugins/inspectors.md +++ b/bridgetown-website/src/_docs/plugins/inspectors.md @@ -17,7 +17,7 @@ Bridgetown doesn't directly install the Nokogiri or Nokolexbor gems, so if that ## Your First Inspector -Let's add an oft-requested feature to our site: automatic `target="_blank"` attributes on all outgoing links. It's easy with an HTML Inspector. +Let's add an oft-requested feature to our site: automatic `target="_blank"` attributes on all outgoing links. We'll create a new builder plugin and use the `inspect_html` method to access the document and update all the relevant links. @@ -43,7 +43,7 @@ Note that `query_selector_all` is an alias for Nokogiri/Nokolexbor's `css` metho In the example above, we loop through all `a` tags, skip the tag if it already has a target or is not a true external link, otherwise we set the target attribute to `_blank`. -Another example of a feature you might want to add is to append "#" links to the ends of headings in your content so that people can copy a permalink to that particular heading. It's easy with this HTML Inspector: +Another example of a feature you might want to add is to append "#" links to the ends of headings in your content so that people can copy a permalink to that particular heading: ```ruby inspect_html do |document| @@ -66,7 +66,7 @@ You can see this in action right on this very page! ## Works with XML Too -If you need to work with XML files such as feeds or sitemaps, you can do this as well with the `inspect_xml` method. It works just like `inspect_html`, except that it can optionally take an extension argument (the default is `xml`). +If you need to work with XML files such as feeds or sitemaps, you can do this as well with the `inspect_xml` method. It works exactly like `inspect_html`, except that it can optionally take an extension argument (the default is `xml`). ```ruby inspect_xml do |document, resource| diff --git a/bridgetown-website/src/_docs/plugins/placeholders.md b/bridgetown-website/src/_docs/plugins/placeholders.md index 4ff7a6e5c..76f5cf9a2 100644 --- a/bridgetown-website/src/_docs/plugins/placeholders.md +++ b/bridgetown-website/src/_docs/plugins/placeholders.md @@ -9,7 +9,7 @@ Resources make use of a [permalink](/docs/content/permalinks) processor to deter Placeholders start with a colon `:`. You can only have one placeholder within a path segment—in other words, `/my_path/:my_placeholder/` is valid, but `/my_path/:my_placeholder-and:another_placeholder/` is not. -To define new placeholders within a plugin, simply use the `permalink_placeholder` method of your builder. For example, if you wanted a placeholder to resolve a resource data, you could add: +To define new placeholders within a plugin, use the `permalink_placeholder` method of your builder. For example, if you wanted a placeholder to resolve a resource data, you could add: ```ruby def build diff --git a/bridgetown-website/src/_docs/plugins/resource-extensions.md b/bridgetown-website/src/_docs/plugins/resource-extensions.md index ffc7ae61f..0222825ea 100644 --- a/bridgetown-website/src/_docs/plugins/resource-extensions.md +++ b/bridgetown-website/src/_docs/plugins/resource-extensions.md @@ -5,7 +5,7 @@ top_section: Configuration category: plugins --- -This API allows you or a third-party gem to augment resources with new methods. There are two ways to use it: in a Builder via a DSL method, or by defining your own modules to register as an extension. The Builder way works just with Ruby-based templates (ERB, etc.), whereas the module way can work with the Resource Liquid Drop as well. +This API allows you or a third-party gem to augment resources with new methods. There are two ways to use it: in a Builder via a DSL method, or by defining your own modules to register as an extension. The Builder way only works with Ruby-based templates (ERB, etc.), whereas the module way can work with the Resource Liquid Drop as well. There's also a summary extension point which can allow a plugin to provide enhanced summaries for resource content. diff --git a/bridgetown-website/src/_docs/plugins/source-manifests.md b/bridgetown-website/src/_docs/plugins/source-manifests.md index d4f6e4c4b..ad238840c 100644 --- a/bridgetown-website/src/_docs/plugins/source-manifests.md +++ b/bridgetown-website/src/_docs/plugins/source-manifests.md @@ -27,7 +27,7 @@ but all others are optional. What this does is allow you to create top-level folders in your gem, for example `./layouts`, and Bridgetown will load content from whichever folders you specify in your -manifest. So if you had the file `layouts/fancy.html`, a site could simply +manifest. So if you had the file `layouts/fancy.html`, a site could reference that layout with `layout: fancy` front matter. ### Namespacing Your Content diff --git a/bridgetown-website/src/_docs/plugins/tags.md b/bridgetown-website/src/_docs/plugins/tags.md index 264fc35ee..80e2547a4 100644 --- a/bridgetown-website/src/_docs/plugins/tags.md +++ b/bridgetown-website/src/_docs/plugins/tags.md @@ -5,7 +5,7 @@ top_section: Configuration category: plugins --- -It's easy to add new [Liquid](/docs/template-engines/liquid/) tags (sometimes called "shortcodes") to your site. Tags provide extra functionality you can use inside of your Markdown content and any HTML template. Built-in examples added by Bridgetown include the `post_url` and `asset_path` tags. Below is an example of a custom Liquid tag that will output the time the page was rendered: +[Liquid](/docs/template-engines/liquid/) tags (sometimes called "shortcodes") provide extra functionality you can use inside of your Markdown content and any HTML template. Built-in examples added by Bridgetown include the `post_url` and `asset_path` tags. Below is an example of a custom Liquid tag that will output the time the page was rendered: ```ruby class RenderTime < SiteBuilder @@ -96,8 +96,7 @@ output: `I AM UPPER CASE` ## Supporting Multiple Attributes and Accessing Template Variables -If you'd like your tag to support multiple attributes separated by a comma, that's -easy to do with the following statement: +If you'd like your tag to support multiple attributes separated by a comma: ```ruby param1, param2 = attributes.split(",").map(&:strip) @@ -123,7 +122,7 @@ tag.context["page"]["title"] # returns "My Exciting Webpage" ## When to use a Tag vs. a Filter -Tags and Tag Blocks are great when you simply want to insert a customized piece of +Tags and Tag Blocks are great when you want to insert a customized piece of content/HTML code into a page. If instead you want to _transform_ input data from one format to another and potentially allow multiple transformations to be chained together, then it's probably better to write a [Filter](/docs/plugins/filters/). diff --git a/bridgetown-website/src/_docs/prototype-pages.md b/bridgetown-website/src/_docs/prototype-pages.md index 99bf1db3f..957fb7ec6 100644 --- a/bridgetown-website/src/_docs/prototype-pages.md +++ b/bridgetown-website/src/_docs/prototype-pages.md @@ -34,7 +34,7 @@ pagination automatically, so you can use `paginator.resources` to loop through t posts like on any normal paginated page. Using `:prototype-term` in the page title will automatically put each archive page's term (aka the category name) in the output title. -You can do the same thing with tags—just use `term: tag` and create a `tags/tag.html` +You can do the same thing with tags. Use `term: tag` and create a `tags/tag.html` file. The exact folder/filename doesn't actually matter—you could create `my-super-awesome-tagged-content/groovy.html` and it would still work. (The filename always gets replaced by the search term itself.) diff --git a/bridgetown-website/src/_docs/resources.md b/bridgetown-website/src/_docs/resources.md index 39b9bfea9..3cd02815b 100644 --- a/bridgetown-website/src/_docs/resources.md +++ b/bridgetown-website/src/_docs/resources.md @@ -30,7 +30,7 @@ In this example, the [layout](/docs/layouts) of the resource is specified as `pa You can save resources as files within your source tree, and you can also [generate resources programatically](/docs/plugins/external-apis) via a builder plugin—perhaps based on data from a headless CMS or other third-party APIs. -Every resource you create is part of a [collection](/docs/collections). Bridgetown comes with two built-in collections, **posts** and **pages**, as well as a no-output **data** collection. You can easily create custom collections to group related content and facilitate easy pagination and archiving functionality. +Every resource you create is part of a [collection](/docs/collections). Bridgetown comes with two built-in collections, **posts** and **pages**, as well as a no-output **data** collection. You can easily create custom collections to group related content and facilitate pagination and archiving functionality. Want to learn more about how to use resources effectively in your website structure and content strategy? Read on! @@ -139,7 +139,7 @@ tags: - super awesome ``` -In addition to the builtin taxonomies, you can define your own taxonomies. For example, if you were setting up a website all about music, you could create a "genre" taxonomy. Just set it up in the config: +In addition to the built-in taxonomies, you can define your own taxonomies in the config. For example, if you were setting up a website all about music, you could create a "genre" taxonomy: ```yaml # bridgetown.config.yml @@ -159,7 +159,7 @@ genres: - Big Band ``` -Accessing taxonomies for resources in your templates is pretty straightforward. +You can access taxonomies for resources in your templates as: ```liquid Title: {{ site.taxonomy_types.genres.metadata.title }} @@ -266,7 +266,7 @@ When writing out your resource content and you're using a Ruby-based template la For advanced use cases where you wish to generate dynamic values for front matter variables, you can use Ruby Front Matter. [Read the documentation here.](/docs/front-matter#the-power-of-ruby-in-front-matter) -In addition, you can add all-Ruby page templates to your site besides just the typical Markdown/Liquid/ERB options. Yes, you're reading that right: put `.rb` files directly in your `src` folder! As long as the final statement in your code returns a string or can be converted to a string via `to_s`, you're golden. Ruby templates are evaluated in a `Bridgetown::ERBView` context (even though they aren't actually ERB), so all the usual Ruby template helpers are available. +In addition, you can add all-Ruby page templates to your site besides the typical Markdown/Liquid/ERB options. Yes, you're reading that right: put `.rb` files directly in your `src` folder! As long as the final statement in your code returns a string or can be converted to a string via `to_s`, you're golden. Ruby templates are evaluated in a `Bridgetown::ERBView` context (even though they aren't actually ERB), so all the usual Ruby template helpers are available. For example, if we were to convert the out-of-the-box `about.md` page to `about.rb`, it would look something like this: @@ -309,13 +309,13 @@ This API allows you or a third-party gem to augment resources with new methods ( Prior to Bridgetown 1.0, a different content engine based on Jekyll was used which you may be familiar with if you have older Bridgetown sites in production or in progress. * The most obvious differences are what you use in templates (Liquid or ERB). For example, instead of `site.posts` in Liquid or `site.posts.docs` in ERB, you'd use `collections.posts.resources` (in both Liquid and ERB). (`site.collection_name_here` syntax is no longer available.) Pages are just another collection now so you can iterate through them as well via `collections.pages.resources`. -* Front matter data is now accessed in Liquid through the `data` variable just like in ERB and skipping `data` is deprecated. Use `{{ post.data.description }}` instead of just `{{ post.description }}`. +* Front matter data is now accessed in Liquid through the `data` variable just like in ERB and skipping `data` is deprecated. Use `{{ post.data.description }}` instead of `{{ post.description }}`. * In addition, instead of referencing the current "page" through `page` (aka `page.data.title`), you can use `resource` instead: `resource.data.title`. * Resources don't have a `url` variable. Your templates/plugins will need to reference either `relative_url` or `absolute_url`. Also, the site's `base_path` (if configured) is built into both values, so you won't need to prepend it manually. * Permalink formats have changed somewhat, so please refer to the latest [permalink](/docs/content/permalinks) docs for how to use the new permalink styles and placeholders. * Whereas the `id` of a document is the relative destination URL, the `id` of a resource is its origin id. You can define an id in front matter separately however, which would be available as `resource.data.id`. * The paginator items are now accessed via `paginator.resources` instead of `paginator.documents`. -* Instead of `pagination:\n enabled: true` in your front matter for a paginated page, you'll put the collection name instead. Also you can use the term `paginate` instead of `pagination`. So to paginate through posts, just add `paginate:\n collection: posts` to your front matter. +* Instead of `pagination:\n enabled: true` in your front matter for a paginated page, you'll put the collection name instead. Also you can use the term `paginate` instead of `pagination`. So to paginate through posts, add `paginate:\n collection: posts` to your front matter. * Prototype pages no longer assume the `posts` collection by default. Make sure you add a `collection` key to the `prototype` front matter. * Categories and tags are collated from all collections (even pages!), so if you used category/tag front matter manually before outside of posts, you may get a lot more site-wide category/tag data than expected. * Since user-authored pages are no longer loaded as `Page` objects and everything formerly loaded as `Document` will now be a `Resource::Base`, plugins will need to be adapted accordingly. The `Page` class has been renamed to `GeneratedPage` to indicate it is only used for specialized content generated by plugins. diff --git a/bridgetown-website/src/_docs/routes.md b/bridgetown-website/src/_docs/routes.md index 28a336236..78c2e765a 100644 --- a/bridgetown-website/src/_docs/routes.md +++ b/bridgetown-website/src/_docs/routes.md @@ -9,13 +9,13 @@ Bridgetown comes with a production-ready web server based on the battle-hardened Bridgetown lets you create your own Roda-based API routes in the `server/routes` folder. An example ships in each new Bridgetown project for you to examine (`server/routes/hello.rb.sample`). These routes provide the standard features you may be accustomed to if you've used Roda standalone. -However, to take full advantage of all the Bridgetown has to offer, we recommend you load up our SSR and Dynamic Routes plugins. Simply add to your configuration in `config/initializers.rb`: +However, to take full advantage of all the Bridgetown has to offer, we recommend you load up our SSR and Dynamic Routes plugins. Add to your configuration in `config/initializers.rb`: ```rb init :ssr init :"bridgetown-routes" -# …or you can just init the routes, which will init :ssr automatically: +# …or you can init the routes, which will init :ssr automatically: init :"bridgetown-routes" ``` @@ -55,13 +55,13 @@ class Routes::Preview < Bridgetown::Rack::Routes end ``` -This route handles any `/preview/:collection/:path` URLs which are accessed just like any other statically-generated resource. It will find a content item via a repo origin ID and render that item as HTML. For example: `/preview/posts/_posts%2F2022-01-10-hello-world.md` would SSR the Markdown content located in `src/_posts/2022-01-10-hello-world.md`. +This route handles any `/preview/:collection/:path` URLs which are accessed like any other statically-generated resource. It will find a content item via a repo origin ID and render that item as HTML. For example: `/preview/posts/_posts%2F2022-01-10-hello-world.md` would SSR the Markdown content located in `src/_posts/2022-01-10-hello-world.md`. {%@ Note do %} If you're wondering "but, uh, where's the HTML rendering part?!", the Bridgetown Roda configuration automatically handles the rendering of any models or resources which are returned in a route block. This is based on a "callable" interface which you can also use for your own custom objects! More on that down below. {% end %} -SSR is great for generating preview content on-the-fly, but you can use it for any number of instances where it’s not feasible to pre-build your content. In addition, you can use SSR to “refresh” stale content…for example, you could pre-build all your product pages statically, but then request a newer version of the page (or better yet, just a fragment of it) whenever the static page is viewed which would then contain the up-to-date pricing (perhaps coming from a PostgreSQL database or some other external data source). And if you cache _that_ data using Redis in, say, 10-minute increments, you’ve just built yourself an extremely performant e-commerce solution. This is only a single example! +SSR is great for generating preview content on-the-fly, but you can use it for any number of instances where it’s not feasible to pre-build your content. In addition, you can use SSR to “refresh” stale content…for example, you could pre-build all your product pages statically, but then request a newer version of the page (or better yet, just a fragment of it) whenever the static page is viewed which would then contain the up-to-date pricing (perhaps coming from a PostgreSQL database or some other external data source). And if you cache _that_ data using Redis in, say, 10-minute increments, you’ve built yourself an extremely performant e-commerce solution. This is only a single example! ### Priority Flag @@ -107,7 +107,7 @@ You can return a resource at the end of any Roda block to have it render out aut By default, all available collections are read in when the Roda server boots up. This might not be a big deal in production since it's a one-time procedure, but bear in mind that on large sites, having all that data loaded in memory could prove costly. In addition, in development, any time you make a change to a file and the site rebuilds, resources are re-read into memory. - You can configure collections, including even the built-in pages and posts collections, to be skipped when your site's running in SSR mode. Just set `skip_for_ssr` to `true` for collection metadata in your config file. For example, to skip reading posts in `config/initializers.rb`: + You can configure collections, including even the built-in pages and posts collections, to be skipped when your site's running in SSR mode. Set `skip_for_ssr` to `true` for collection metadata in your config file. For example, to skip reading posts in `config/initializers.rb`: ```ruby Bridgetown.configure do @@ -201,7 +201,7 @@ This is a contrived example of course, but you can easily imagine loading a spec You can even use placeholders in folder names! A route saved to `src/_routes/books/[id]/chapter/[chapter_id].erb` would match to something like `/books/234259/chapter/5` and let you access `r.params[:id]` and `r.params[:chapter_id]`. Pretty nifty. ### Route Template Delimiters, Front Matter Syntax @@ -220,7 +220,7 @@ render_with(data: hsh) Note that if you use that syntax, additional local variables will _not_ be copied down to the view template. -Finally, Bridgetown lets you simplify your code even more if your block doesn't need to include any special `get`/`post` etc. casing and you just want to use local variables for front matter by letting you omit `render_with` entirely: +Finally, if you only need to use local variables within your front matter, you can omit `render_with` entirely: ```eruby ---<% @@ -237,7 +237,7 @@ title = "Thank You!" ### Routes in Islands Architecture -You can add routes folders inside of one or more islands. For example, you could add a route file at `src/_islands/paradise/routes/dreamy.erb`, and the URL would then resolve to the island name plus the route name (`/paradise/dreamy`). If you name your route file `index.(ext)`, then the route path would be just the island name (`/paradise`). +You can add routes folders inside of one or more islands. For example, you could add a route file at `src/_islands/paradise/routes/dreamy.erb`, and the URL would then resolve to the island name plus the route name (`/paradise/dreamy`). If you name your route file `index.(ext)`, then the route path would be only the island name (`/paradise`). For more information about islands, read our [Islands Architecture documentation](/docs/islands). diff --git a/bridgetown-website/src/_docs/static-files.md b/bridgetown-website/src/_docs/static-files.md index 227fde97a..2a1157071 100644 --- a/bridgetown-website/src/_docs/static-files.md +++ b/bridgetown-website/src/_docs/static-files.md @@ -8,7 +8,7 @@ category: static-files A static file is a file that does not contain any front matter. These include images, PDFs, and other un-rendered content. -You can save static files in any subfolder or directly within the source folder (`src`). A common place to save images specifically is the `src/images` folder. You can reference them from both markup and CSS simply using a relative URL (for example, `/images/logo.svg`). +You can save static files in any subfolder or directly within the source folder (`src`). A common place to save images specifically is the `src/images` folder. You can reference them from both markup and CSS using a relative URL (for example, `/images/logo.svg`). {%@ Note do %} Optionally, you can [bundle images through esbuild](/docs/frontend-assets) and reference them with the `asset_path` helper. Or if you're interested in a full-featured image management solution with the ability to resize and optimize your media sizes, check out [Cloudinary](https://www.cloudinary.com) and the [bridgetown-cloudinary plugin](https://github.com/bridgetownrb/bridgetown-cloudinary). diff --git a/bridgetown-website/src/_docs/template-engines.md b/bridgetown-website/src/_docs/template-engines.md index da8734da4..d2bd7d86b 100644 --- a/bridgetown-website/src/_docs/template-engines.md +++ b/bridgetown-website/src/_docs/template-engines.md @@ -7,7 +7,7 @@ category: template-engines Bridgetown's default configured template language is **Liquid**. Liquid's simple syntax and safe execution context make it ideal for designer-led template creation. -However, you can use a variety of different template engines within Bridgetown simply by using the appropriate file extension (aka `.erb`), or by specifying the template engine in your resource's front matter. Out of the box, Bridgetown provides support for both **ERB** and **Serbea**, and you can also use Haml or Slim by installing additional plugins. +However, you can use a variety of different template engines within Bridgetown by using the appropriate file extension (aka `.erb`), or by specifying the template engine in your resource's front matter. Out of the box, Bridgetown provides support for both **ERB** and **Serbea**, and you can also use Haml or Slim by installing additional plugins. To configure a new Bridgetown site to use a language other than Liquid as the default template engine regardless of file extension, use the `-t`/`--templates` option when running `bridgetown new`. @@ -46,11 +46,11 @@ So instead of doing that, you can switch template engines directly. All you need ## Front Matter Defaults -Besides adding `template_engine` directly in your file's front matter, you could use [front matter defaults](/docs/content/front-matter-defaults) to specify a template engine for a folder or folder tree or files which match a particular "glob pattern". That way you could, say, use Liquid for most of the site but use ERB just for a certain group of files. +Besides adding `template_engine` directly in your file's front matter, you could use [front matter defaults](/docs/content/front-matter-defaults) to specify a template engine for a folder or folder tree or files which match a particular "glob pattern". That way you could, say, use Liquid for most of the site but use ERB only for a certain group of files. ## Site-wide Configuration -Most likely, however, you'll want to switch your site wholesale from one engine to another. That's where `bridgetown.config.yml` comes in. Simply add `template_engine: erb` right in your config, and suddenly *everything* will get processed through ERB regardless of file extension. (This will have been done for you if you used the `-t` option when running `bridgetown new`.) Serbea works in the same manner: `template_engine: serbea`. Write HTML, XML, Markdown, JSON, CSV, whatever you like—and _still_ access the full power of your Ruby template language of choice. You don't even need to give up on Liquid completely—just save files with `.liquid` or use `template_engine: liquid` front matter. +Most likely, however, you'll want to switch your site wholesale from one engine to another. That's where `bridgetown.config.yml` comes in. Add `template_engine: erb` right in your config, and suddenly *everything* will get processed through ERB regardless of file extension. (This will have been done for you if you used the `-t` option when running `bridgetown new`.) Serbea works in the same manner: `template_engine: serbea`. Write HTML, XML, Markdown, JSON, CSV, whatever you like—and _still_ access the full power of your Ruby template language of choice. You don't even need to give up on Liquid completely; set the file extension to `.liquid` or set `template_engine: liquid` in the front matter. It's worth noting that by combining Markdown, ERB/Serbea, components, and frontend JavaScript "sprinkles" (or "spices" as we like to say), you can author extremely sophisticated documents which boast stunning performance and SEO scores while at the same time providing impressive interactivity in the browser. This is quickly becoming a "best practice" in the web development industry, and Bridgetown will help get you there. diff --git a/bridgetown-website/src/_docs/template-engines/erb-and-beyond.md b/bridgetown-website/src/_docs/template-engines/erb-and-beyond.md index b76a8794d..b084ec769 100644 --- a/bridgetown-website/src/_docs/template-engines/erb-and-beyond.md +++ b/bridgetown-website/src/_docs/template-engines/erb-and-beyond.md @@ -8,17 +8,17 @@ template_engine: erb Bridgetown's implementation language, Ruby, has a rich history of providing [ERB](https://docs.ruby-lang.org/en/2.7.0/ERB.html) for templates and view layers across a wide variety of tools and frameworks. Other Ruby-based template languages such as [Haml](https://haml.info), [Slim](http://slim-lang.com), and [Serbea](https://www.serbea.dev) garner enthusiastic usage as well. -Bridgetown makes it easy to add both ERB-based and Serbea-based templates and components to any site. In additional, there are plugins you can easily install for Haml and Slim support. Under the hood, Bridgetown uses the [Tilt gem](https://github.com/rtomayko/tilt) to load and process these Ruby templates. +You can add both ERB-based and Serbea-based templates and components to any site. In additional, there are plugins you can easily install for Haml and Slim support. Under the hood, Bridgetown uses the [Tilt gem](https://github.com/rtomayko/tilt) to load and process these Ruby templates. <%= render Note.new do %> - Interested in switching your entire site to use ERB or Serbea by default? [It's possible to do that with just a simple configuration change.](/docs/template-engines#site-wide-configuration) + Interested in switching your entire site to use ERB or Serbea by default? [It's possible to do that with a configuration change.](/docs/template-engines#site-wide-configuration) <% end %> <%= toc %> ## Usage -For ERB, simply define a page/document with an `.erb` extension, rather than `.html`. You'll still need to add front matter to the top of the file (or at the very least two lines of triple dashes `---`) for the file to get processed. In the Ruby code you embed, you'll be interacting with the underlying Ruby API for Bridgetown objects (aka `Bridgetown::Page`, `Bridgetown::Site`, etc.). Here's an example: +For ERB, define a page/document with an `.erb` extension, rather than `.html`. You'll still need to add front matter to the top of the file (or at the very least two lines of triple dashes `---`) for the file to get processed. In the Ruby code you embed, you'll be interacting with the underlying Ruby API for Bridgetown objects (aka `Bridgetown::Page`, `Bridgetown::Site`, etc.). Here's an example: ```eruby --- @@ -228,7 +228,7 @@ layout: testing A standard Liquid page. {{ resource.data.layout }} ``` -If in your layout or a layout partial you need to output the paths to your frontend assets, you can do so with a `asset_path` helper just like with Liquid layouts: +If your layout or a layout partial needs to load your frontend assets, use the `asset_path` helper: ```eruby @@ -237,7 +237,7 @@ If in your layout or a layout partial you need to output the paths to your front ## Markdown -When authoring a document using ERB, you might find yourself wanting to embed some Markdown within the document content. That's easy to do using a `markdownify` block: +To embed markdown within an ERB template, you can use a `markdownify` block: ```eruby <%%= markdownify do %> @@ -324,7 +324,7 @@ In order to simplify more complex lists of HTML attributes you may also pass a h `link_to` uses [`html_attributes`](#html_attributes) under the hood to handle this converstion. -You can also pass relative or aboslute URLs to `link_to` and they'll just pass-through to the anchor tag without change: +You can also pass relative or aboslute URLs to `link_to` and they'll pass-through to the anchor tag without change: ```eruby <%%= link_to "Visit Bridgetown", "https://www.bridgetownrb.com" %> @@ -494,7 +494,7 @@ Liquid::Template.register_filter MyFilters Bridgetown::RubyTemplateView::Helpers.include MyFilters ``` -Usage is pretty straightforward: +And at the call site: ```eruby <%%= lowercase_string "WAY DOWN LOW" %> @@ -508,7 +508,7 @@ Usage is pretty straightforward: The ERB template engine uses a safe output buffer—[the same one used in Rails](https://guides.rubyonrails.org/active_support_core_extensions.html#output-safety). -That means that you'll sometimes find that if you simply output a front matter variable or some other string value that contains HTML tags and entities, the string will be "escaped" so that the actual angle brackets and so forth are displayed in the website content (rather than being interpreted as valid HTML tags). +That means that you'll sometimes find that if you output a front matter variable or some other string value that contains HTML tags and entities, the string will be "escaped" so that the actual angle brackets and so forth are displayed in the website content (rather than being interpreted as valid HTML tags). Often that's the right call for [security purposes to avoid XSS attacks](https://guides.rubyonrails.org/security.html#cross-site-scripting-xss) or to bypass potential markup errors. However, to explicitly mark a string as safe, you can use the `html_safe` method. Bridgetown provides the `raw` or `safe` helpers as well. You can also use a double-equals sign to bypass escaping entirely. diff --git a/bridgetown-website/src/_docs/testing.md b/bridgetown-website/src/_docs/testing.md index bb45fa2a4..c08374ba8 100644 --- a/bridgetown-website/src/_docs/testing.md +++ b/bridgetown-website/src/_docs/testing.md @@ -25,7 +25,7 @@ bin/bridgetown configure minitesting This will set up the plugin, test gems, and an example test suite in the `test` folder. -The tests you write will be simple DOM selection assertions that operate on the output HTML that's in memory after the site has been rendered, so they run extremely fast. You use the native Ruby APIs provided by Bridgetown to find pages to test, and use assertions you may be familiar with from the Ruby on Rails framework (such as `assert_select` and `assert_dom_equal`). Here's an example of such a test: +The tests you write will be DOM selection assertions that operate on the output HTML that's in memory after the site has been rendered, so they run extremely fast. You use the native Ruby APIs provided by Bridgetown to find pages to test, and use assertions you may be familiar with from the Ruby on Rails framework (such as `assert_select` and `assert_dom_equal`). Here's an example of such a test: ```ruby require_relative "./helper" @@ -56,7 +56,7 @@ As part of the automation setup mentioned above, you should now have new scripts ## Headless Browser Testing with Cypress -You can install Cypress using a [bundled configuration](/docs/bundled-configurations). Just run: +You can install Cypress using a [bundled configuration](/docs/bundled-configurations): ```sh bin/bridgetown configure cypress diff --git a/bridgetown-website/src/_docs/themes.md b/bridgetown-website/src/_docs/themes.md index f90e81b45..073301a6c 100644 --- a/bridgetown-website/src/_docs/themes.md +++ b/bridgetown-website/src/_docs/themes.md @@ -22,7 +22,7 @@ and adding `init :"really-cool-theme"` to your initializers file, or by applying bin/bridgetown apply https://github.com/super-great-themes/theme-one ``` -The theme creator will typically provide some simple instructions on how to use +The theme creator will typically provide instructions on how to use the provided theme files and enhancements. Perhaps you'll use some stylesheets or JavaScript modules provided by the theme. Perhaps the theme will include components such as navbars or slideshows or ways to display new content types @@ -31,7 +31,7 @@ you can assign to your content such as posts or collection documents. Sometimes you might want to copy files out of a theme and into your site repo directly. The [`bridgetown plugins cd` command](/docs/commands/plugins#copying-files-out-of-plugin-source-folders) -will help you do just that. +will help you do exactly that. {%@ Note do %} Looking for a theme to install on your site? @@ -41,7 +41,7 @@ and other useful plugins! ## Creating a Theme -To design a theme to distribute to others, simply [create a standard gem-based plugin](/docs/plugins#creating-a-gem) using the `bridgetown plugins new NAME` command. Follow that link for more on live testing strategies and how to release and publish your theme. +To design a theme to distribute to others, [create a standard gem-based plugin](/docs/plugins#creating-a-gem) using the `bridgetown plugins new NAME` command. Follow that link for more on live testing strategies and how to release and publish your theme. You'll need to use a [Source Manifest](/docs/plugins/source-manifests/) to instruct the Bridgetown build process where to find your theme files. diff --git a/rubocop/bridgetown/assert_equal_literal_actual.rb b/rubocop/bridgetown/assert_equal_literal_actual.rb index ce16b3ea6..be8fcfb28 100644 --- a/rubocop/bridgetown/assert_equal_literal_actual.rb +++ b/rubocop/bridgetown/assert_equal_literal_actual.rb @@ -26,7 +26,7 @@ module Bridgetown # @alpha.omega # ) # - class AssertEqualLiteralActual < Cop + class AssertEqualLiteralActual < Base MSG = "Provide the 'expected value' as the first argument to `assert_equal`.".freeze SIMPLE_LITERALS = %i( @@ -61,7 +61,7 @@ class AssertEqualLiteralActual < Cop def on_send(node) return unless literal_actual?(node) || literal_actual_with_msg?(node) - add_offense(node, location: :expression) + add_offense(node) end def autocorrect(node)