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

History.markdown

@@ -3,6 +3,8 @@
 ### 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
 
@@ -11,6 +13,15 @@
   * 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
 

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 %}

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/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/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(
+        @post_date ||= Utils.parse_date(date, "Path '#{name}' does not contain valid date.")
-          date,
-          "'#{date}' does not contain valid date and/or title."
-        )
       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
+        @markup = markup.strip
-        begin
+        @template = Liquid::Template.parse(@markup) if @markup.include?("{{")
-          @post = PostComparer.new(@orig_post)
+
-        rescue StandardError => e
+        # Deprecated instance_variables.
-          raise Jekyll::Errors::PostURLError, <<~MSG
+        # To be removed in Jekyll v5.0.
-            Could not parse name of post "#{@orig_post}" in tag 'post_url'.
+        @orig_post = @markup
-             Make sure the post exists and the name is correct.
+        @post = nil
-             #{e.class}: #{e.message}
-          MSG
-        end
       end
 
       def render(context)
         @context = context
+        @resolved_markup = @template&.render(@context) || @markup
         site = context.registers[:site]
 
-        site.posts.docs.each do |document|
+        begin
-          return relative_url(document) if @post == document
+          @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
+        # First pass-through did not yield the requested post. Search again using legacy matching
-        # with deprecation warning if this matches
+        # 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|
+          log_legacy_usage_deprecation
-          next unless @post.deprecated_equality document
+          return relative_url(post)
-
-          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)
         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'.
+          Could not parse name of post #{@resolved_markup.inspect} in tag 'post_url'.
-          Make sure the post exists and the name is correct.
+          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