Add target config setting and front matter variables so one could create multiple outputs from a single site codebase with various target site included files

Merge pull request 9850

.github/actions/spelling/allow.txt

@@ -1,3 +1,4 @@
+azion
 builtins
 github
 hakiri
@@ -7,6 +8,7 @@ Microsoft
 ssh
 Statictastic
 statictastic
+supranode
 ubuntu
 Wikipedia
 workaround

History.markdown

@@ -1,3 +1,28 @@
+## HEAD
+
+### Bug Fixes
+
+  * Avoid caching resource when called via `include_relative` tag (#9784)
+  * Fix logs containing IPv6 URLs (#9813)
+  * Do not treat colons in `url_placeholders` as URI delimiters (#9850)
+
+### Documentation
+
+  * Improve documentation on collections in step-by-step walkthrough (#9803)
+  * Add `https://form.taxi` as a third-party resource for forms (#9802)
+  * Add Supranode to third-party deployment guide (#9786)
+  * Document the need for a `Gemfile` in deployment step of step-by-step walkthrough (#9805)
+  * Add Azion to the 3rd party deployment docs (#9811)
+  * Add ruby-erb prerequisite for Arch Linux installations (#9832)
+
+### Development Fixes
+
+  * Improve readability of `post_url` tag (#9829)
+
+### Minor Enhancements
+
+  * feat: Allowing post_url tag to receive liquid variables (#9776)
+
 ## 4.4.1 / 2025-01-29
 
 ### Bug Fixes

docs/_docs/deployment/third-party.md

@@ -70,7 +70,17 @@ Read this [Jekyll step-by-step guide](https://www.21yunbox.com/docs/#/deploy-jek
 [Layer0](https://www.layer0.co) is an all-in-one platform to develop, deploy, preview, experiment on, monitor, and run your headless frontend. It is focused on large, dynamic websites and best-in-class performance through EdgeJS (a JavaScript-based Content Delivery Network), predictive prefetching, and performance monitoring. Layer0 offers a free tier. Get started in just a few minutes by following [Layer0's guide to deploying Jekyll](https://docs.layer0.co/guides/jekyll).
 
 ## Kinsta Application Hosting
+
 [Kinsta Application Hosting](https://kinsta.com/application-hosting) is a Cloud Platform designed to help your company and dev teams ship web projects faster and more efficiently. You can host your apps, databases, and sites all in one place. Easily connect with GitHub and automate deployments and get 24/7 support for all your favorite languages and frameworks.
 
 Read [this guide](https://kinsta.com/docs/jekyll-static-site-example/) to learn how to deploy Jekyll site on Kinsta.
 
+## Supranode
+
+[Supranode](https://supranode.com) offers customizable continuous deployment for static websites, featuring automatic HTTPS, a high-performance CDN, secret management, deployment previews, password protection, and more.
+
+## Azion
+
+[Azion](https://www.azion.com/en/) is an web platform that provides a wide range of services. It allows you to host static sites, including Jekyll-powered websites, with features like automatic HTTPS, custom domains, and real-time analytics. Azion's platform is designed for performance and scalability, making it an excellent choice for hosting global websites.
+
+In [this guide](https://www.azion.com/en/documentation/products/guides/jekyll-boilerplate/) you can learn how to deploy a Jekyll site on Azion.

docs/_docs/installation/other-linux.md

@@ -40,7 +40,7 @@ sudo emerge --ask --verbose jekyll
 ### ArchLinux
 
 ```sh
-sudo pacman -S ruby base-devel
+sudo pacman -S ruby base-devel ruby-erb
 ```
 
 ### OpenSUSE

docs/_docs/liquid/tags.md

@@ -188,3 +188,25 @@ You can also use this tag to create a link to a post in Markdown as follows:
 [Name of Link]({% post_url 2010-07-21-name-of-post %})
 ```
 {% endraw %}
+
+Now lets say you have a [datafile]({{ '/docs/datafiles/' | relative_url }}) `_data/cool_posts.yaml` used to keep track
+of certain posts that you intend to be listed as say *Cool Posts*:
+
+```yaml
+- title: "An Awesome Post"
+  slug: "2010-07-21-name-of-post"
+- title: "Another Awesome Post"
+  slug: "2016-07-26-name-of-post"
+```
+
+You may list such posts using the `post_url` tag as well (from {%- include docs_version_badge.html version="4.5.0" -%}):
+
+{% raw %}
+```liquid
+Cool posts:
+
+{%- for cool_post in site.data.cool_posts %}
+- [{{ cool_post.title }}]({% post_url {{ cool_post.slug }} %})
+{%- endfor %}
+```
+{% endraw %}

docs/_docs/step-by-step/09-collections.md

@@ -57,7 +57,7 @@ Ted has been eating fruit since he was baby.
 Let's add a page which lists all the authors on the site. Jekyll makes the
 collection available at `site.authors`.
 
-Create `staff.html` and iterate over `site.authors` to output all the staff:
+Create `staff.html` in the root directory and iterate over `site.authors` to output all the staff:
 
 {% raw %}
 ```liquid

docs/_docs/step-by-step/10-deployment.md

@@ -11,7 +11,7 @@ It's good practice to have a [Gemfile](/docs/ruby-101/#gemfile) for your site.
 This ensures the version of Jekyll and other gems remains consistent across
 different environments.
 
-Create a `Gemfile` in the root. 
+If you completed step one in this tutorial, you have already created a Gemfile. If you skipped step one, create a `Gemfile` in the root. 
 The file should be called 'Gemfile' and should *not* have any extension. 
 You can create a Gemfile with Bundler and then add the `jekyll` gem:
 
@@ -20,7 +20,7 @@ bundle init
 bundle add jekyll
 ```
 
-Your file should look something like:
+Your `Gemfile` should look something like:
 
 ```ruby
 # frozen_string_literal: true

docs/pages/resources.md

@@ -62,6 +62,7 @@ Use a SaaS service as a backend for functionality on your Jekyll site
   - [Formspark](https://formspark.io/)
   - [Formspree (open source)](https://formspree.io/)
   - [formX](https://formx.stream)
+  - [Form.taxi](https://form.taxi/en/backend)
   - [Simple Form](https://getsimpleform.com/)
   - [SmartForms](https://smartforms.dev/)
   - [Typeform](https://www.typeform.com/templates/c/forms/)

features/include_relative_tag.feature

@@ -58,3 +58,22 @@ Feature: include_relative Tag
     Then I should get a zero exit status
     And the _site directory should exist
     And I should see "Welcome back Dear Reader!" in "_site/index.html"
+
+  Scenario: Include multiple files relative to a page at root
+    Given I have an "apple.md" page with foo "bar" that contains "{{ page.path }}, {{ page.foo }}"
+    And I have an "banana.md" page with content:
+      """
+        {% include_relative apple.md %}
+        {% include_relative cherry.md %}
+
+        {{ page.path }}
+      """
+    And I have an "cherry.md" page with foo "lipsum" that contains "{{ page.path }}, {{ page.foo }}"
+    When I run jekyll build
+    Then I should get a zero exit status
+    And the _site directory should exist
+    And I should see "<p>apple.md, bar</p>" in "_site/apple.html"
+    And I should see "<hr />\n<p>foo: bar" in "_site/banana.html"
+    And I should see "<hr />\n<p>foo: lipsum" in "_site/banana.html"
+    And I should see "<p>cherry.md, lipsum</p>" in "_site/cherry.html"
+    But I should not see "foo: lipsum" in "_site/cherry.html"

features/post_url_tag.feature

@@ -157,3 +157,37 @@ Feature: PostUrl Tag
     But the _site directory should exist
     And I should see "<p><a href=\"/cats%20and%20dogs/2019/02/04/hello-world.html\">Post 1</a></p>" in "_site/index.html"
     And I should see "<p><a href=\"/2019/02/05/hello-again.html\">Post 2</a></p>" in "_site/index.html"
+
+  Scenario: Calling for a post via a liquid variable
+    Given I have a _posts directory
+    And I have the following post:
+      | title       | date       | content           |
+      | Hello World | 2019-02-04 | Lorem ipsum dolor |
+    And I have an "index.md" page with content:
+      """
+      {% assign value='2019-02-04-hello-world' %}
+      [Welcome]({% post_url {{ value }} %})
+      """
+    When I run jekyll build
+    Then I should get a zero exit status
+    And the _site directory should exist
+    And I should see "<p><a href=\"/2019/02/04/hello-world.html\">Welcome</a></p>" in "_site/index.html"
+
+  Scenario: Calling for posts via a liquid variable in a for tag
+    Given I have a _posts directory
+    And I have the following post:
+      | title         | date       | content           |
+      | Hello World   | 2019-02-04 | Lorem ipsum dolor |
+      | We Meet Again | 2019-02-05 | Alpha beta gamma  |
+    And I have an "index.md" page with content:
+      """
+      {% assign posts = '2019-02-04-hello-world;2019-02-05-we-meet-again' | split: ';' %}
+      {%- for slug in posts -%}
+        [{{ slug }}]({% post_url {{ slug }} %})
+      {%- endfor %}
+      """
+    When I run jekyll build
+    Then I should get a zero exit status
+    And the _site directory should exist
+    And I should see "<a href=\"/2019/02/04/hello-world.html\">2019-02-04-hello-world</a>" in "_site/index.html"
+    And I should see "<a href=\"/2019/02/05/we-meet-again.html\">2019-02-05-we-meet-again</a>" in "_site/index.html"

lib/jekyll/collection.rb

@@ -185,7 +185,8 @@ module Jekyll
     #
     # Returns true if the 'write' metadata is true, false otherwise.
     def write?
-      !!metadata.fetch("output", false)
+      !!metadata.fetch("output", false) &&
+        (site.target == metadata.fetch("target", site.target))
     end
 
     # The URL template to render collection's documents at.

lib/jekyll/commands/serve.rb

@@ -243,7 +243,7 @@ module Jekyll
         def format_url(ssl_enabled, address, port, baseurl = nil)
           format("%<prefix>s://%<address>s:%<port>i%<baseurl>s",
                  :prefix  => ssl_enabled ? "https" : "http",
-                 :address => address,
+                 :address => address.include?(":") ? "[#{address}]" : address,
                  :port    => port,
                  :baseurl => baseurl ? "#{baseurl}/" : "")
         end

lib/jekyll/commands/serve/live_reload_reactor.rb

@@ -55,8 +55,9 @@ module Jekyll
               EM.schedule { @started_event.set }
               EM.add_shutdown_hook { @stopped_event.set }
 
+              host = opts["host"].include?(":") ? "[#{opts["host"]}]" : opts["host"]
               Jekyll.logger.info "LiveReload address:",
-                                 "http://#{opts["host"]}:#{opts["livereload_port"]}"
+                                 "http://#{host}:#{opts["livereload_port"]}"
             end
           end
           @thread.abort_on_exception = true

lib/jekyll/configuration.rb

@@ -30,6 +30,7 @@ module Jekyll
       "limit_posts"         => 0,
       "future"              => false,
       "unpublished"         => false,
+      "target"              => "default",
 
       # Plugins
       "whitelist"           => [],

lib/jekyll/document.rb

@@ -348,17 +348,20 @@ module Jekyll
     end
 
     # Determine whether this document should be written.
-    # Based on the Collection to which it belongs.
+    # Based on the Collection to which it belongs
+    # and site and document target.
     #
     # True if the document has a collection and if that collection's #write?
-    # method returns true, and if the site's Publisher will publish the document.
+    # method returns true, and if the site's Publisher will publish the document,
+    # and if the document's target matches the site target or is undefined.
     # False otherwise.
     #
     # rubocop:disable Naming/MemoizedInstanceVariableName
     def write?
       return @write_p if defined?(@write_p)
 
-      @write_p = collection&.write? && site.publisher.publish?(self)
+      @write_p = collection&.write? && site.publisher.publish?(self) &&
+        (site.target == data.fetch("target", site.target))
     end
     # rubocop:enable Naming/MemoizedInstanceVariableName
 

lib/jekyll/drops/document_drop.rb

@@ -15,7 +15,7 @@ module Jekyll
       private delegate_method_as :data, :fallback_data
 
       delegate_methods :id, :output, :content, :to_s, :relative_path, :url, :date
-      data_delegators "title", "categories", "tags"
+      data_delegators "title", "categories", "tags", :target
 
       def collection
         @obj.collection.label

lib/jekyll/page.rb

@@ -180,7 +180,7 @@ module Jekyll
     end
 
     def write?
-      true
+      site.config["target"] == data.fetch("target", site.config["target"])
     end
 
     def excerpt_separator

lib/jekyll/site.rb

@@ -6,7 +6,7 @@ module Jekyll
                   :file_read_opts, :future, :gems, :generators, :highlighter,
                   :include, :inclusions, :keep_files, :layouts, :limit_posts,
                   :lsi, :pages, :permalink_style, :plugin_manager, :plugins,
-                  :reader, :safe, :show_drafts, :static_files, :theme, :time,
+                  :reader, :safe, :target, :show_drafts, :static_files, :theme, :time,
                   :unpublished
 
     attr_reader :cache_dir, :config, :dest, :filter_cache, :includes_load_paths,
@@ -47,7 +47,7 @@ module Jekyll
     def config=(config)
       @config = config.clone
 
-      %w(safe lsi highlighter baseurl exclude include future unpublished
+      %w(safe lsi highlighter baseurl exclude include future unpublished target
          show_drafts limit_posts keep_files).each do |opt|
         send(:"#{opt}=", config[opt])
       end
@@ -360,7 +360,7 @@ module Jekyll
     end
 
     def each_site_file
-      pages.each { |page| yield page }
+      pages.each { |page| yield (page) if page.write? }
       static_files.each { |file| yield(file) if file.write? }
       collections.each_value { |coll| coll.docs.each { |doc| yield(doc) if doc.write? } }
     end

lib/jekyll/tags/include.rb

@@ -249,6 +249,11 @@ module Jekyll
     end
 
     class IncludeRelativeTag < IncludeTag
+      def load_cached_partial(path, context)
+        context.registers[:cached_partials] ||= {}
+        context.registers[:cached_partials][path] ||= parse_partial(path, context)
+      end
+
       def tag_includes_dirs(context)
         Array(page_path(context)).freeze
       end
@@ -267,6 +272,17 @@ module Jekyll
         path = File.join(site.config["collections_dir"], path) if page["collection"]
         path.delete_suffix("/#excerpt")
       end
+
+      # Since Jekyll 4 caches convertibles based on their path within the only instance of
+      # `LiquidRenderer`, initialize a new LiquidRenderer instance on every render of this
+      # tag to bypass caching rendered output of page / document.
+      def parse_partial(path, context)
+        LiquidRenderer.new(context.registers[:site]).file(path).parse(read_file(path, context))
+      rescue Liquid::Error => e
+        e.template_name = path
+        e.markup_context = "included " if e.markup_context.nil?
+        raise e
+      end
     end
   end
 end

lib/jekyll/tags/post_url.rb

@@ -3,34 +3,39 @@
 module Jekyll
   module Tags
     class PostComparer
+      # Deprecated (soft; No interpreter warnings).
+      # To be removed in v5.0.
+      # Use private constant `POST_PATH_MATCHER` instead.
       MATCHER = %r!^(.+/)*(\d+-\d+-\d+)-(.*)$!.freeze
 
+      POST_PATH_MATCHER = %r!\A(.+/)*?(\d{2,4}-\d{1,2}-\d{1,2})-([^/]*)\z!.freeze
+      private_constant :POST_PATH_MATCHER
+
       attr_reader :path, :date, :slug, :name
 
       def initialize(name)
         @name = name
 
-        all, @path, @date, @slug = *name.sub(%r!^/!, "").match(MATCHER)
+        all, @path, @date, @slug = *name.delete_prefix("/").match(POST_PATH_MATCHER)
         unless all
           raise Jekyll::Errors::InvalidPostNameError,
                 "'#{name}' does not contain valid date and/or title."
         end
 
         basename_pattern = "#{date}-#{Regexp.escape(slug)}\\.[^.]+"
-        @name_regex = %r!^_posts/#{path}#{basename_pattern}|^#{path}_posts/?#{basename_pattern}!
+        @name_regex = %r!\A_posts/#{path}#{basename_pattern}|\A#{path}_posts/?#{basename_pattern}!
       end
 
       def post_date
-        @post_date ||= Utils.parse_date(
-          date,
-          "'#{date}' does not contain valid date and/or title."
-        )
+        @post_date ||= Utils.parse_date(date, "Path '#{name}' does not contain valid date.")
       end
 
+      # Returns `MatchData` or `nil`.
       def ==(other)
         other.relative_path.match(@name_regex)
       end
 
+      # Deprecated. To be removed in v5.0.
       def deprecated_equality(other)
         slug == post_slug(other) &&
           post_date.year  == other.date.year &&
@@ -40,9 +45,9 @@ module Jekyll
 
       private
 
-      # Construct the directory-aware post slug for a Jekyll::Post
+      # Construct the directory-aware post slug for a Jekyll::Document object.
       #
-      # other - the Jekyll::Post
+      # other - the Jekyll::Document object.
       #
       # Returns the post slug with the subdirectory (relative to _posts)
       def post_slug(other)
@@ -58,47 +63,71 @@ module Jekyll
     class PostUrl < Liquid::Tag
       include Jekyll::Filters::URLFilters
 
-      def initialize(tag_name, post, tokens)
+      def initialize(tag_name, markup, tokens)
         super
-        @orig_post = post.strip
-        begin
-          @post = PostComparer.new(@orig_post)
-        rescue StandardError => e
-          raise Jekyll::Errors::PostURLError, <<~MSG
-            Could not parse name of post "#{@orig_post}" in tag 'post_url'.
-             Make sure the post exists and the name is correct.
-             #{e.class}: #{e.message}
-          MSG
-        end
+        @markup = markup.strip
+        @template = Liquid::Template.parse(@markup) if @markup.include?("{{")
+
+        # Deprecated instance_variables.
+        # To be removed in Jekyll v5.0.
+        @orig_post = @markup
+        @post = nil
       end
 
       def render(context)
         @context = context
+        @resolved_markup = @template&.render(@context) || @markup
         site = context.registers[:site]
 
-        site.posts.docs.each do |document|
-          return relative_url(document) if @post == document
+        begin
+          @post_comparer = PostComparer.new(@resolved_markup)
+        rescue StandardError
+          raise_markup_parse_error
+        end
+        # For backwards compatibility only; deprecated instance_variable.
+        # To be removed in Jekyll v5.0.
+        @post = @post_comparer
+
+        # First pass-through.
+        site.posts.docs.each do |post|
+          return relative_url(post) if @post_comparer == post
         end
 
-        # New matching method did not match, fall back to old method
-        # with deprecation warning if this matches
+        # First pass-through did not yield the requested post. Search again using legacy matching
+        # method. Log deprecation warning if a post is detected via this round.
+        site.posts.docs.each do |post|
+          next unless @post_comparer.deprecated_equality(post)
 
-        site.posts.docs.each do |document|
-          next unless @post.deprecated_equality document
-
-          Jekyll::Deprecator.deprecation_message(
-            "A call to '{% post_url #{@post.name} %}' did not match a post using the new " \
-            "matching method of checking name (path-date-slug) equality. Please make sure " \
-            "that you change this tag to match the post's name exactly."
-          )
-          return relative_url(document)
+          log_legacy_usage_deprecation
+          return relative_url(post)
         end
 
+        raise_post_not_found_error
+      end
+
+      private
+
+      def raise_markup_parse_error
         raise Jekyll::Errors::PostURLError, <<~MSG
-          Could not find post "#{@orig_post}" in tag 'post_url'.
-          Make sure the post exists and the name is correct.
+          Could not parse name of post #{@resolved_markup.inspect} in tag 'post_url'.
+          Make sure the correct name is given to the tag.
         MSG
       end
+
+      def raise_post_not_found_error
+        raise Jekyll::Errors::PostURLError, <<~MSG
+          Could not find post #{@resolved_markup.inspect} in tag 'post_url'.
+          Make sure the post exists and the correct name is given to the tag.
+        MSG
+      end
+
+      def log_legacy_usage_deprecation
+        Jekyll::Deprecator.deprecation_message(
+          "A call to '{% post_url #{@resolved_markup} %}' did not match a post using the new " \
+          "matching method of checking name (path-date-slug) equality. Please make sure that " \
+          "you change this tag to match the post's name exactly."
+        )
+      end
     end
   end
 end

lib/jekyll/url.rb

@@ -144,7 +144,13 @@ module Jekyll
       #   pct-encoded   = "%" HEXDIG HEXDIG
       #   sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
       #                 / "*" / "+" / "," / ";" / "="
-      Addressable::URI.encode(path).encode("utf-8").sub("#", "%23")
+      #
+      # `Addressable::URI::CharacterClassesRegexps::PATH` is used to encode
+      # non-alphanumeric characters such as "[", "]", etc.
+      Addressable::URI.encode_component(
+        path,
+        Addressable::URI::CharacterClassesRegexps::PATH
+      ).encode("utf-8").sub("#", "%23")
     end
 
     # Unescapes a URL path segment

test/test_url.rb

@@ -80,5 +80,16 @@ class TestURL < JekyllUnitTest
         ).to_s
       end
     end
+
+    should "not treat colons in placeholders as uri delimiters" do
+      assert_equal "/foo/foo%20bar:foobar/", URL.new(
+        :template     => "/:x/:y/",
+        :placeholders => { :x => "foo", :y => "foo bar:foobar" }
+      ).to_s
+    end
+
+    should "unescape urls with colons" do
+      assert_equal "/foo/foo bar:foobar/", Jekyll::URL.unescape_path("/foo/foo%20bar:foobar/")
+    end
   end
 end