asciisourcerer 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c7773a8343dbad45adce3b1c32d959ed8e8da23afb1779e308999801eb32404
-  data.tar.gz: a9ff1c4838338f0302e9dbb202092309254be9c73dfe245f6ea61594a38e966e
+  metadata.gz: e85e0efc612880e0a0e62bef37b836015007d18074a74f890edc9db56791772c
+  data.tar.gz: 3fc912495515ae3b1a42016e3b5de6fd2a136533e53f981d42a14b5860a5038f
 SHA512:
-  metadata.gz: e49749d692bd70ce7196fb54312e016b0daf5074d3949c49a4586e3c7f3da7e85d9e3c9b0d50013c3d8c8e8a14a9353323cd0f195cda0255956657aee42bf441
-  data.tar.gz: 9d10b6d87d315d5d5d254103cc82a3491b43f11fb784da16dc0516ee4697373e5b45d75a2aec29b4bab90d70e74d32f48ee5194108d576b5e7f4cd4f206506f9
+  metadata.gz: d2f3ed3a3b52950034965fa3edde7bf7159c7a907885e90b74e1a1e623b7996b9d7e4f03b72bf9f4cc7bfd8dc8cb7179deed2f38e8cf3adca04b5e34f0753bde
+  data.tar.gz: b859463483fb45eb5d84d326301b4c44adf2716f719cfdb77ecd4293d92dc23b3e9c8dc4128129ec84287d08d94761a250d9b629d451ac7b9fb77eddbbcbb08b

data/README.adoc

@@ -37,12 +37,13 @@ endif::[]
 :this_prod_name: {this_proj_name}
 // end::universal-settings[]
 :this_prod_vrsn_major: 0
-:this_prod_vrsn_minor: 3
+:this_prod_vrsn_minor: 4
 :this_prod_vrsn_majmin: {this_prod_vrsn_major}.{this_prod_vrsn_minor}
-:this_prod_vrsn_patch: 1
+:this_prod_vrsn_patch: 0
 :this_prod_vrsn: {this_prod_vrsn_majmin}.{this_prod_vrsn_patch}
-:next_prod_vrsn: 0.4.0
+:next_prod_vrsn: 0.5.0
 // end::global-settings[]
+// end::ai-prompt[]
 :toc: macro
 :toclevels: 4
 :this_prod_repo_files_path: {this_proj_src_www_url}/tree/main
@@ -89,7 +90,7 @@ Initialize a Jekyll-routed Liquid runtime with DocOps Lab filters and tags, so J
 See <<templating-liquid-runtime>>.
 
 Build-time generation::
-Generate prebuild artifacts (attributes, snippets, regions) for downstream builds and runtime access.
+Generate pre-build artifacts (attributes, snippets, regions) for downstream builds and runtime access.
 See <<pipelines>>.
 
 AsciiDoc-to-manpage conversion::
@@ -144,7 +145,7 @@ The most common workflows are summarized below.
 Basic render flow::
 Load YAML data, optionally enrich it with AsciiDoc attributes, render a template, and write output to a file.
 
-Prebuild flow::
+Pre-build flow::
 Extract attributes and tagged content from AsciiDoc into artifacts that are loaded at runtime.
 
 Converter flow::
@@ -329,7 +330,7 @@ NOTE: Only blocks marked `_skip` are not carried over.
 sync::
 Ongoing operation that scans for canonical blocks, replaces their content with the prime version (after optional Liquid rendering), and leaves everything else verbatim.
 
-dry_run: true::
+`dry_run: true`::
 Pass `dry_run: true` to either operation to compute the result without writing any file.
 The `result.diff` file contains the rendered content (`init`) or a unified diff (`sync`).
 
@@ -394,10 +395,10 @@ If you are building a Jekyll-compatible templating pipeline, prefer Liquid.
 If you want a low-friction Ruby template for internal tooling, ERB is available.
 
 [[pipelines]]
-=== Prebuild and Rendering Pipelines
+=== Pre-build and Rendering Pipelines
 
-Sourcerer's rendering pipeline is optimized for build tooling and prebuild steps.
-A typical prebuild might load attributes from `README.adoc`, extract tagged snippets into `build/snippets/`, and render YAML plus Liquid templates into `build/docs/`.
+Sourcerer's rendering pipeline is optimized for build tooling and pre-build steps.
+A typical pre-build might load attributes from `README.adoc`, extract tagged snippets into `build/snippets/`, and render YAML plus Liquid templates into `build/docs/`.
 
 The API is intentionally small.
 Sourcerer focuses on producing artifacts, not managing a broader build lifecycle.
@@ -518,18 +519,18 @@ Sourcerer::Util::ListAmend.apply(default_list, custom_list, normalize: nil) -> A
 ----
 
 Behavior::
-  `nil` / empty custom:::
-    Returns `default_list` (stringified) unchanged.
-  Fixed-list mode:::
-    If `custom_list` contains *no* tokens starting with `+` or `-`, it fully replaces `default_list`.
-  Amendment mode:::
-    If `custom_list` contains *any* `+`/`-` token:
-    `-slug` removes `slug` from the working set (or no-op if absent). +
-    `+slug` adds `slug` if not already present. +
-    bare `slug` is treated as `+slug`.
+`nil` / empty custom:::
+  Returns `default_list` (stringified) unchanged.
+Fixed-list mode:::
+  If `custom_list` contains *no* tokens starting with `+` or `-`, it fully replaces `default_list`.
+Amendment mode:::
+  If `custom_list` contains *any* `+`/`-` token:
+  `-slug` removes `slug` from the working set (or no-op if absent). +
+  `+slug` adds `slug` if not already present. +
+  bare `slug` is treated as `+slug`.
 
 `normalize` (optional)::
-  A callable used to compare items during deduplication and removal, for example `->(s) { s.downcase }`.
+A callable used to compare items during de-duplication and removal, for example `->(s) { s.downcase }`.
 
 .Examples
 [source,ruby]
@@ -573,7 +574,7 @@ result = Sourcerer::Util::Pathifier.match(input, recursive: true, include_dirs:
 Classification rules::
 `:file`:::    `File.file?(input)` is true.
 `:dir`:::     `File.directory?(input)` is true.
-`:glob`:::    Input contains glob metacharacters (`* ? [ ] { }`).
+`:glob`:::    Input contains glob meta-characters (`* ? [ ] { }`).
 `:missing`::: None of the above.
 
 Options::
@@ -621,7 +622,7 @@ Sourcerer provides it with primitives such as YAML loading, templating, and Liqu
 SchemaGraphy depends on AsciiSourcerer for these primitives, not the other way around.
 
 https://github.com/DocOps/releasehx[ReleaseHx]::
-The ReleaseHx API and `rhx` CLI uses Sourcerer for generating source files during a prebuild stage, and at runtime for YAML ingest and template rendering.
+The ReleaseHx API and `rhx` CLI uses Sourcerer for generating source files during a pre-build stage, and at runtime for YAML ingest and template rendering.
 
 LiquiDoc::
 Secondary to SchemaGraphy, the scriptable template-rendering build utility LiquiDoc will use SchemaGraphy and AsciiSourcerer at runtime.

data/lib/sourcerer/asciidoc.rb

@@ -115,7 +115,7 @@ module Sourcerer
 
       tags = [tag] if tag
       raise ArgumentError, 'at least one tag must be specified' if tags.empty?
-      raise ArgumentError, 'tags must all be strings' unless tags.all? { |item| item.is_a?(String) }
+      raise ArgumentError, 'tags must all be strings' unless tags.all?(String)
 
       tags
     end
@@ -198,6 +198,7 @@ module Sourcerer
     # @param include_frontmatter [Boolean] Whether to prepend markdown YAML front matter.
     # @param markdown_options [Hash] Options passed to markdown converter.
     # @param markdown_converter [#call] Callable that accepts `(html, markdown_options)`.
+    # @param convert_tables_to_markdown [Boolean] Convert all tables to markdown UNLESS they have .no-markdown class.
     # @return [Hash] Conversion result containing markdown, frontmatter, and backend info.
     def self.mark_down_grade source_path, markdown_output_path=nil, markdown_converter:, **options
       options = normalize_mark_down_grade_options(options)
@@ -223,7 +224,17 @@ module Sourcerer
       end
 
       frontmatter_block, html_for_markdown = split_frontmatter_block(html_with_frontmatter)
-      markdown_body = markdown_converter.call(html_for_markdown, options[:markdown_options])
+      # Build options for markdown converter, including table conversion mode
+      converter_options = options[:markdown_options].dup
+      # Pass frontmatter table conversion setting through converter_options
+      if options.key?(:convert_tables_to_markdown)
+        converter_options[:convert_tables_to_markdown] =
+          options[:convert_tables_to_markdown]
+      end
+      if converter_options[:convert_tables_to_markdown].nil? && frontmatter.key?('tables-to-markdown')
+        converter_options[:convert_tables_to_markdown] = frontmatter['tables-to-markdown']
+      end
+      markdown_body = markdown_converter.call(html_for_markdown, converter_options)
       markdown = frontmatter_block ? "#{frontmatter_block}\n\n#{markdown_body}" : markdown_body
 
       if markdown_output_path
@@ -241,7 +252,8 @@ module Sourcerer
 
     # @api private
     def self.normalize_mark_down_grade_options options
-      supported_option_keys = %i[html_output_path backend header_footer include_frontmatter markdown_options attributes]
+      supported_option_keys = %i[html_output_path backend header_footer include_frontmatter markdown_options attributes
+                                 convert_tables_to_markdown]
       unknown_option_keys = options.keys - supported_option_keys
       raise ArgumentError, "unknown option(s): #{unknown_option_keys.join(', ')}" unless unknown_option_keys.empty?
 
@@ -251,7 +263,8 @@ module Sourcerer
         header_footer: options.fetch(:header_footer, false),
         include_frontmatter: options.fetch(:include_frontmatter, true),
         markdown_options: options.fetch(:markdown_options, { github_flavored: true }),
-        attributes: options.fetch(:attributes, {})
+        attributes: options.fetch(:attributes, {}),
+        convert_tables_to_markdown: options[:convert_tables_to_markdown]
       }
     end
 
@@ -273,7 +286,7 @@ module Sourcerer
     def self.compose_frontmatter_block frontmatter
       return nil if frontmatter.nil? || frontmatter.empty?
 
-      yaml_payload = YAML.dump(frontmatter)
+      yaml_payload = Psych.dump(frontmatter, nil, { line_width: -1 })
       yaml_payload = yaml_payload.sub(/\A---\s*\n/, '')
       yaml_payload = yaml_payload.sub(/\n\.\.\.\s*\z/, "\n")
 
@@ -317,12 +330,33 @@ module Sourcerer
         next unless key.start_with?(prefix)
 
         normalized_key = key.sub(/\A#{Regexp.escape(prefix)}/, '')
-        attributes[normalized_key] = value.to_s
+        attributes[normalized_key] = coerce_page_attribute_value(value)
       end
 
       attributes
     end
 
+    # Coerce page attribute values to appropriate types (boolean, string, etc).
+    # Preserves boolean values and converts string representations to boolean where appropriate.
+    #
+    # @param value [Object] The attribute value from document.attributes.
+    # @return [Object] The coerced value.
+    def self.coerce_page_attribute_value value
+      # Preserve actual booleans
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      # Convert string representations of booleans
+      string_val = value.to_s.downcase.strip
+      case string_val
+      when 'true', '1', 'yes', 'on'
+        true
+      when 'false', '0', 'no', 'off'
+        false
+      else
+        value.to_s
+      end
+    end
+
     # Parse optional YAML front matter fenced with --- at the top of source content.
     #
     # @param source_text [String]
@@ -476,7 +510,8 @@ module Sourcerer
                          :normalize_extract_tagged_content_options,
                          :normalize_extract_tags,
                          :collect_tagged_content,
-                         :normalize_mark_down_grade_options
+                         :normalize_mark_down_grade_options,
+                         :coerce_page_attribute_value
 
     # Utilities for filtering and partitioning Asciidoctor document attributes.
     #

data/lib/sourcerer/jekyll/bootstrapper.rb

@@ -53,7 +53,7 @@ module Sourcerer
 
         site = ::Jekyll::Site.new(config)
 
-        include_paths = site.includes_load_paths || []
+        include_paths = site.config['includes_load_paths'] || []
         site.inclusions ||= {}
 
         include_paths.each do |dir|

data/lib/sourcerer/mark_down_grade.rb

@@ -21,7 +21,8 @@ module Sourcerer
 
     @config = {
       preserve_heading_ids: true,
-      strip_internal_links: false
+      strip_internal_links: false,
+      convert_tables_to_markdown: false
     }
 
     class << self
@@ -32,6 +33,7 @@ module Sourcerer
     # Options:
     #   preserve_heading_ids: (default: true) Include <a id="..."> anchors before headings
     #   strip_internal_links: (default: false) Remove href from internal anchor links, keeping only text
+    #   convert_tables_to_markdown: (default: false) Convert all tables to markdown UNLESS they have .no-markdown class
     def self.bootstrap! options={}
       @config.merge!(options)
 
@@ -421,9 +423,49 @@ module Sourcerer
     end
 
     # Passthrough Tables: preserve HTML tables as-is (except admonition internals handled elsewhere).
+    # Tables with "to-markdown" class are converted via ReverseMarkdown instead.
+    # Supports both html5 (class on <table>) and html5s (class on parent <div class="table-block">).
+    # Per-table classes (.to-markdown, .no-markdown) override the global conversion mode.
     class TablePassthrough < ReverseMarkdown::Converters::Base
-      def convert node, _state={}
-        "#{node.to_html}\n"
+      def initialize
+        super
+        @markdown_converter = ReverseMarkdown::Converters::Table.new
+      end
+
+      def convert node, state={}
+        global_mode = Thread.current[:sourcerer_table_conversion_mode] || false
+
+        # Check for per-table classes (on table or parent wrapper)
+        has_to_markdown = check_class_on_node(node, 'to-markdown')
+        has_no_markdown = check_class_on_node(node, 'no-markdown')
+
+        # Also check parent <div class="table-block"> wrapper (html5s backend)
+        parent_div = node.parent
+        if parent_div && parent_div.name == 'div'
+          has_to_markdown ||= check_class_on_node(parent_div, 'to-markdown')
+          has_no_markdown ||= check_class_on_node(parent_div, 'no-markdown')
+        end
+
+        # Determine whether to convert (per-table classes override global mode)
+        should_convert = if has_no_markdown
+                           false # .no-markdown always prevents conversion
+                         elsif has_to_markdown
+                           true  # .to-markdown always forces conversion
+                         else
+                           global_mode # Use global table conversion mode
+                         end
+
+        if should_convert
+          @markdown_converter.convert(node, state)
+        else
+          "#{node.to_html}\n"
+        end
+      end
+
+      private
+
+      def check_class_on_node node, class_name
+        node['class'].to_s.split.include?(class_name)
       end
     end
 
@@ -606,18 +648,28 @@ module Sourcerer
     end
 
     # Convert HTML into Markdown with MarkDownGrade converters.
+    # Options include:
+    #   convert_tables_to_markdown: Override global config for table conversion (true/false)
     def self.convert_html html, options={}
       bootstrap! unless @setup_complete
       @setup_complete = true
 
-      normalized_html = normalize_html_for_markdown(html.to_s)
-      markdown = ReverseMarkdown.convert(normalized_html, options)
-      markdown = markdown.gsub(/(\*\*[^\n]+\*\*  \n)\n+(?=\S)/, '\\1')
-      markdown = markdown.gsub(/<figcaption>\s+/, '<figcaption>')
-      markdown = markdown.gsub(%r{\s+</figcaption>}, '</figcaption>')
-
-      markdown.gsub('<!--CHECKBOX_CHECKED-->', '- [x]')
-              .gsub('<!--CHECKBOX_UNCHECKED-->', '- [ ]')
+      # Determine effective table conversion mode
+      effective_mode = determine_table_conversion_mode(html.to_s, options)
+      Thread.current[:sourcerer_table_conversion_mode] = effective_mode
+
+      begin
+        normalized_html = normalize_html_for_markdown(html.to_s)
+        markdown = ReverseMarkdown.convert(normalized_html, options)
+        markdown = markdown.gsub(/(\*\*[^\n]+\*\*  \n)\n+(?=\S)/, '\\1')
+        markdown = markdown.gsub(/<figcaption>\s+/, '<figcaption>')
+        markdown = markdown.gsub(%r{\s+</figcaption>}, '</figcaption>')
+
+        markdown.gsub('<!--CHECKBOX_CHECKED-->', '- [x]')
+                .gsub('<!--CHECKBOX_UNCHECKED-->', '- [ ]')
+      ensure
+        Thread.current[:sourcerer_table_conversion_mode] = nil
+      end
     end
 
     def self.convert html, options={}
@@ -629,6 +681,7 @@ module Sourcerer
       fragment = Nokogiri::HTML::DocumentFragment.parse(html_body)
       normalize_abstract_nodes!(fragment)
       normalize_footnote_nodes!(fragment)
+      clean_html5s_tables!(fragment)
       fragment.to_html
     end
 
@@ -682,10 +735,92 @@ module Sourcerer
       raw_id.empty? ? nil : raw_id
     end
 
+    # Clean HTML5s table artifacts: remove colgroup elements and class/style attributes from cells.
+    # This normalizes tables generated by the asciidoctor-html5s backend for safer Markdown conversion.
+    #
+    # @param fragment [Nokogiri::HTML::DocumentFragment] The HTML fragment to clean.
+    # @return [void] Modifies fragment in place.
+    def self.clean_html5s_tables! fragment
+      # Remove all colgroup elements
+      fragment.css('colgroup').each(&:remove)
+
+      # Remove class and style attributes from table cells and rows
+      fragment.css('td, th, tr').each do |cell|
+        cell.delete('class')
+        cell.delete('style')
+      end
+    end
+
+    # Determine the effective table conversion mode from options, frontmatter, or global config.
+    #
+    # Precedence:
+    # 1. Explicit convert_tables_to_markdown option in parameters
+    # 2. Document-level setting from frontmatter (YAML) or page attributes (AsciiDoc)
+    # 3. Global config setting
+    #
+    # @param html_body [String] The HTML document body.
+    # @param options [Hash] Optional override.
+    # @return [Boolean] Whether tables should be converted to markdown by default.
+    def self.determine_table_conversion_mode html_body, options
+      # Explicit option takes precedence
+      return options[:convert_tables_to_markdown] if options.key?(:convert_tables_to_markdown)
+
+      # Extract from document metadata
+      document_mode = extract_table_conversion_mode_from_html(html_body)
+      return document_mode unless document_mode.nil?
+
+      # Fall back to global config
+      @config[:convert_tables_to_markdown]
+    end
+
+    # Extract table conversion mode from document frontmatter or page attributes.
+    #
+    # Checks for:
+    # - YAML frontmatter key: tables-to-markdown
+    # - AsciiDoc page attribute: page-tables-to-markdown
+    #
+    # @param html_body [String] The HTML document body.
+    # @return [Boolean, nil] The setting if found, nil otherwise.
+    def self.extract_table_conversion_mode_from_html html_body
+      # Try to extract YAML frontmatter
+      frontmatter = Sourcerer::YamlFrontmatter.extract(html_body)
+      return string_to_boolean(frontmatter['tables-to-markdown']) if frontmatter.key?('tables-to-markdown')
+
+      # Try to find page-tables-to-markdown in HTML comments or metadata
+      # (This would be set by AsciiDoc's page attributes)
+      if html_body.include?('page-tables-to-markdown')
+        # Look for data attributes or comments that might encode this
+        if html_body.match?(/page-tables-to-markdown['"]?\s*[:=]\s*['"]*true/i)
+          return true
+        elsif html_body.match?(/page-tables-to-markdown['"]?\s*[:=]\s*['"]*false/i)
+          return false
+        end
+      end
+
+      nil
+    end
+
+    # Convert a string representation to a boolean value.
+    #
+    # @param value [String, Boolean, nil] The value to convert.
+    # @return [Boolean, nil] Boolean if value is truthy string, nil if unclear.
+    def self.string_to_boolean value
+      case value.to_s.downcase.strip
+      when 'true', '1', 'yes', 'on'
+        true
+      when 'false', '0', 'no', 'off', ''
+        false
+      end
+    end
+
     private_class_method :normalize_html_for_markdown,
                          :normalize_abstract_nodes!,
                          :normalize_footnote_nodes!,
-                         :canonical_footnote_anchor_id
+                         :canonical_footnote_anchor_id,
+                         :clean_html5s_tables!,
+                         :determine_table_conversion_mode,
+                         :extract_table_conversion_mode_from_html,
+                         :string_to_boolean
   end # module MarkDownGrade
 end # module Sourcerer
 

data/lib/sourcerer/rendering.rb

@@ -86,7 +86,7 @@ module Sourcerer
     # @return [void]
     def self.render_with_converter render_entry
       data_file = render_entry[:data]
-      out_file = render_entry[:out]
+      out_file  = render_entry[:out]
       raise ArgumentError, 'render entry missing :data' unless data_file
       raise ArgumentError, 'render entry missing :out' unless out_file
 

data/lib/sourcerer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sourcerer
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: asciisourcerer
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - DocOps Lab
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -153,7 +152,6 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -168,8 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: APIs for specialized handling of AsciiDoc, YAML, and Liquid documents.
 test_files: []