From e96c53bf25fc4efc337fc96c8d960e514bc2e2f1 Mon Sep 17 00:00:00 2001 From: Matt Kraai <36463918+mtkraai@users.noreply.github.com> Date: Fri, 24 Apr 2026 11:01:16 -0700 Subject: [PATCH 1/3] Expand delimiters if code contains backticks --- lib/puppet-strings/markdown/helpers.rb | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/lib/puppet-strings/markdown/helpers.rb b/lib/puppet-strings/markdown/helpers.rb index 40885e73..5d6c6366 100644 --- a/lib/puppet-strings/markdown/helpers.rb +++ b/lib/puppet-strings/markdown/helpers.rb @@ -4,18 +4,27 @@ module PuppetStrings::Markdown::Helpers # Formats code as either inline or a block. # - # Note that this does not do any escaping even if the code contains ` or ```. + # Delimiters are expanded if the code contains the default delimiter. # # @param [String] code The code to format. # @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby. - # @param [String] block_prefix String to insert before if it’s a block. - # @param [String] inline_prefix String to insert before if it’s inline. + # @param [String] block_prefix String to insert before if it's a block. + # @param [String] inline_prefix String to insert before if it's inline. # @returns [String] Markdown def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ') - if code.to_s.include?("\n") - "#{block_prefix}```#{type}\n#{code}\n```" + code_s = code.to_s + if code_s.include?("\n") || code_s.length > 70 + # Delimiter must be one backtick longer than the longest series of backticks + # beginning a line, minimum 3 (with some spaces allowed). + delim = (code_s.scan(/^ {0,3}``(`+)\s*$/) << '').flatten.max_by(&:length) + '```' + "#{block_prefix}#{delim}#{type}\n#{code_s}\n#{delim}" else - "#{inline_prefix}`#{code}`" + # Delimeter must be one backtick longer than the longest series of backticks + # in the string. + delim = code_s.scan(/`*/).max_by(&:length) + '`' + # Padding required if string starts or ends with a backtick + pad = (code_s[0] == '`' || code_s[-1] == '`') ? ' ' : '' + "#{inline_prefix}#{delim}#{pad}#{code_s}#{pad}#{delim}" end end end From 5e6222eef08181ae34ed6d100b987209155d0a9d Mon Sep 17 00:00:00 2001 From: Matt Kraai <36463918+mtkraai@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:27:30 -0700 Subject: [PATCH 2/3] Expand use of `code_maybe_block()` Use the `code_maybe_block()` function for all code strings that could possibly contain backticks. --- lib/puppet-strings/markdown/helpers.rb | 5 +++-- .../markdown/templates/classes_and_defines.erb | 8 +++----- .../markdown/templates/data_type.erb | 6 ++---- .../markdown/templates/data_type_function.erb | 10 ++++------ .../markdown/templates/function.erb | 14 +++++--------- .../markdown/templates/puppet_task.erb | 2 +- .../markdown/templates/resource_type.erb | 18 ++++++++---------- 7 files changed, 26 insertions(+), 37 deletions(-) diff --git a/lib/puppet-strings/markdown/helpers.rb b/lib/puppet-strings/markdown/helpers.rb index 5d6c6366..fb704ef4 100644 --- a/lib/puppet-strings/markdown/helpers.rb +++ b/lib/puppet-strings/markdown/helpers.rb @@ -10,10 +10,11 @@ module PuppetStrings::Markdown::Helpers # @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby. # @param [String] block_prefix String to insert before if it's a block. # @param [String] inline_prefix String to insert before if it's inline. + # @param [Symbol] whether to force a format (:inline, :block) or determine by content (:none). # @returns [String] Markdown - def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ') + def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ', force: :none) code_s = code.to_s - if code_s.include?("\n") || code_s.length > 70 + if (code_s.include?("\n") || code_s.length > 70 || force == :block) && force != :inline # Delimiter must be one backtick longer than the longest series of backticks # beginning a line, minimum 3 (with some spaces allowed). delim = (code_s.scan(/^ {0,3}``(`+)\s*$/) << '').flatten.max_by(&:length) + '```' diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index 636ab60c..61aa0e51 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -42,9 +42,7 @@ <% examples.each do |eg| -%> ##### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> @@ -61,7 +59,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>: ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type:<%= code_maybe_block(param[:types].join(', ')) %> +Data type:<%= param[:types].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> <% end -%> <%= param[:text] %> @@ -71,7 +69,7 @@ Options: <% options_for_param(param[:name]).each do |o| -%> <% if o[:opt_types] -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% else -%> * **<%= o[:opt_name] %>**: <%= o[:opt_text] %> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/data_type.erb b/lib/puppet-strings/markdown/templates/data_type.erb index 237ef6f2..f3ddd9b8 100644 --- a/lib/puppet-strings/markdown/templates/data_type.erb +++ b/lib/puppet-strings/markdown/templates/data_type.erb @@ -42,9 +42,7 @@ <% examples.each do |eg| -%> ##### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> @@ -74,7 +72,7 @@ Data type:<%= code_maybe_block(param[:types].join(', ')) %> Options: <% options_for_param(param[:name]).each do |o| -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% end -%> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/data_type_function.erb b/lib/puppet-strings/markdown/templates/data_type_function.erb index afb8cbd0..f60f6f06 100644 --- a/lib/puppet-strings/markdown/templates/data_type_function.erb +++ b/lib/puppet-strings/markdown/templates/data_type_function.erb @@ -1,6 +1,6 @@ ### `<%= name %>` -#### `<%= signature %>` +####<%= code_maybe_block(signature, force: :inline) %> <% if text -%> <%= text %> @@ -17,7 +17,7 @@ <% end -%> <% if return_type -%> -Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %> +Returns:<%= code_maybe_block(return_type, force: :inline) %><% if return_val %> <%= return_val %><% end %> <% end -%> <% if raises -%> @@ -33,9 +33,7 @@ Raises: <% examples.each do |eg| -%> ###### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> @@ -51,7 +49,7 @@ Data type:<%= code_maybe_block(param[:types][0]) %> Options: <% options_for_param(param[:name]).each do |o| -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% end -%> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/function.erb b/lib/puppet-strings/markdown/templates/function.erb index a07f0459..d587efd1 100644 --- a/lib/puppet-strings/markdown/templates/function.erb +++ b/lib/puppet-strings/markdown/templates/function.erb @@ -30,14 +30,12 @@ Type: <%= type %> <% examples.each do |eg| -%> ##### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> <% signatures.each do |sig| -%> -#### `<%= sig.signature %>` +####<%= code_maybe_block(sig.signature, force: :inline) %> <% if sig.text -%> <%= sig.text %> @@ -54,7 +52,7 @@ Type: <%= type %> <% end -%> <% if sig.return_type -%> -Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><% end %> +Returns:<%= code_maybe_block(sig.return_type, force: :inline) %><% if sig.return_val %> <%= sig.return_val %><% end %> <% end -%> <% if raises -%> @@ -71,9 +69,7 @@ Raises: <% sig.examples.each do |eg| -%> ###### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> @@ -89,7 +85,7 @@ Data type:<%= code_maybe_block(param[:types][0]) %> Options: <% sig.options_for_param(param[:name]).each do |o| -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% end -%> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/puppet_task.erb b/lib/puppet-strings/markdown/templates/puppet_task.erb index 1f9e2c5a..9628369a 100644 --- a/lib/puppet-strings/markdown/templates/puppet_task.erb +++ b/lib/puppet-strings/markdown/templates/puppet_task.erb @@ -19,7 +19,7 @@ ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type:<%= code_maybe_block(param[:types].join(', ')) %> +Valid values:<%= param[:types].map{|type| code_maybe_block(type, force: :inline)}.join(',') %> <% end -%> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index 4a10ac83..ab514324 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -42,9 +42,7 @@ <% examples.each do |eg| -%> ##### <%= eg[:name] %> -```puppet -<%= eg[:text] %> -``` +<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %> <% end -%> <% end -%> @@ -57,7 +55,7 @@ The following properties are available in the `<%= name %>` <%= @type %>. ##### `<%= prop[:name] %>` <% if prop[:values] -%> -Valid values: `<%= prop[:values].join('`, `') %>` +Valid values:<%= prop[:values].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> <% end -%> <% if prop[:isnamevar] -%> @@ -69,7 +67,7 @@ Aliases: `<%= prop[:aliases].to_s.delete('{').delete('}') %>` <% end -%> <% if prop[:data_type] -%> -Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(prop[:data_type]) %> +Data type:<%= code_maybe_block(prop[:data_type]) %> <% end -%> <%= prop[:description] %> @@ -78,7 +76,7 @@ Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex th Options: <% options_for_param(prop[:name]).each do |o| -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% end -%> <% end -%> @@ -109,7 +107,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>. ##### `<%= param[:name] %>` <% if param[:values] -%> -Valid values: `<%= param[:values].join('`, `') %>` +Valid values:<%= param[:values].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> <% end -%> <% if param[:isnamevar] -%> @@ -121,7 +119,7 @@ Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>` <% end -%> <% if param[:data_type] -%> -Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %> +Data type:<%= code_maybe_block(param[:data_type]) %> <% end -%> <% if param[:description] -%> @@ -132,7 +130,7 @@ Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex t Options: <% options_for_param(param[:name]).each do |o| -%> -* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> +* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %> <% end -%> <% end -%> @@ -145,7 +143,7 @@ Options: <% end -%> <% if param[:default] -%> -Default value: `<%= param[:default] %>` +Default value:<%= code_maybe_block(param[:default]) %> <% end -%> <% if param[:required_features] -%> From 9e7d403717ab2fdfaabd4dc8d6a8f86a74065b3e Mon Sep 17 00:00:00 2001 From: Matt Kraai <36463918+mtkraai@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:28:03 -0700 Subject: [PATCH 3/3] Restore previous format for certain arrays. --- lib/puppet-strings/markdown/templates/classes_and_defines.erb | 2 +- lib/puppet-strings/markdown/templates/puppet_task.erb | 2 +- lib/puppet-strings/markdown/templates/resource_type.erb | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index 61aa0e51..d33e6c6b 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -59,7 +59,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>: ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type:<%= param[:types].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> +Data type:<%= code_maybe_block(param[:types].join(', ')) %> <% end -%> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/puppet_task.erb b/lib/puppet-strings/markdown/templates/puppet_task.erb index 9628369a..1f9e2c5a 100644 --- a/lib/puppet-strings/markdown/templates/puppet_task.erb +++ b/lib/puppet-strings/markdown/templates/puppet_task.erb @@ -19,7 +19,7 @@ ##### `<%= param[:name] %>` <% if param[:types] -%> -Valid values:<%= param[:types].map{|type| code_maybe_block(type, force: :inline)}.join(',') %> +Data type:<%= code_maybe_block(param[:types].join(', ')) %> <% end -%> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index ab514324..cdc762db 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -55,7 +55,7 @@ The following properties are available in the `<%= name %>` <%= @type %>. ##### `<%= prop[:name] %>` <% if prop[:values] -%> -Valid values:<%= prop[:values].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> +Valid values: `<%= prop[:values].join('`, `') %>` <% end -%> <% if prop[:isnamevar] -%> @@ -107,7 +107,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>. ##### `<%= param[:name] %>` <% if param[:values] -%> -Valid values:<%= param[:values].map{|val| code_maybe_block(val, force: :inline)}.join(',') %> +Valid values: `<%= param[:values].join('`, `') %>` <% end -%> <% if param[:isnamevar] -%>