releasehx 0.1.1 → 0.2.0

data/lib/releasehx/cli.rb

@@ -688,23 +688,32 @@ module ReleaseHx
     end
 
     def create_rhyml_from_source source_path, version
-      # Determine source type from configuration, not just file extension
-      configured_source_type = @settings.dig('origin', 'source') || 'json'
-
-      # Handle different source types based on configuration
-      case configured_source_type
-      when 'rhyml'
+      # First check if source_path is actually a file (overrides config)
+      if version_or_file(source_path) == :file && File.exist?(source_path)
         # Load RHYML data directly from YAML file
+        ReleaseHx.logger.debug "Loading RHYML from file: #{source_path}" if options[:verbose]
         rhyml_data = SchemaGraphy::Loader.load_yaml_with_tags(source_path)
         release_data = rhyml_data['releases'] ? rhyml_data['releases'].first : rhyml_data
 
         # Convert hash keys to keyword arguments for Release constructor
-        ReleaseHx::RHYML::Release.new(
+        return ReleaseHx::RHYML::Release.new(
           code: release_data['code'] || version,
           date: release_data['date'],
           hash: release_data['hash'],
           memo: release_data['memo'],
           changes: release_data['changes'] || [])
+      end
+
+      # Determine source type from configuration
+      configured_source_type = @settings.dig('origin', 'source') || 'json'
+
+      # Handle different source types based on configuration
+      case configured_source_type
+      when 'rhyml'
+        # Config says rhyml but source_path is not a file - error
+        raise Thor::Error,
+              "ERROR: origin.source is 'rhyml' but no YAML file provided. " \
+              'Specify a YAML file path as the first argument.'
       when 'json'
         # For json type, only use local files (never API calls)
         if options[:api_data]
@@ -744,12 +753,14 @@ module ReleaseHx
       @settings['modes'] ||= {}
 
       unless options[:wrap].nil?
-        @settings['modes']['wrapped'] = options[:wrap]
+        @settings['modes']['html_wrap'] = options[:wrap]
         ReleaseHx.logger.info "✓ Changed HTML wrapping to: #{options[:wrap]}" if options[:verbose]
       end
 
       return if options[:frontmatter].nil?
 
+      @settings['modes']['markdown_frontmatter'] = options[:frontmatter]
+      @settings['modes']['asciidoc_frontmatter'] = options[:frontmatter]
       @settings['modes']['html_frontmatter'] = options[:frontmatter]
       ReleaseHx.logger.info "✓ Changed frontmatter inclusion to: #{options[:frontmatter]}" if options[:verbose]
     end
@@ -831,8 +842,9 @@ module ReleaseHx
 
       # Extract issues array if client config specifies root_issues_path: "issues"
       # This matches what the API client does when fetching live data
+      # BUT: Skip extraction if a custom mapping is provided, as it handles extraction itself
       origin_source = @settings.dig('origin', 'source')
-      if origin_source && payload.is_a?(Hash) && payload.key?('issues')
+      if origin_source && payload.is_a?(Hash) && payload.key?('issues') && !options[:mapping]
         client_path = find_api_client_config(origin_source)
         if client_path
           client_def = SchemaGraphy::Loader.load_yaml_with_tags(client_path)

data/lib/releasehx/configuration.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'psych'
-require_relative '../schemagraphy/loader'
 
 module ReleaseHx
   # Manages the application's configuration by loading and merging settings

data/lib/releasehx/generated.rb

@@ -2,7 +2,7 @@
 # Auto-generated by Sourcerer::Builder
 
 module ReleaseHx
-  ATTRIBUTES = {:globals=>{"attribute-undefined"=>"drop-line", "attribute-missing"=>"skip", "appendix-caption"=>"Appendix", "appendix-refsig"=>"Appendix", "caution-caption"=>"Caution", "chapter-refsig"=>"Chapter", "example-caption"=>"Example", "figure-caption"=>"Figure", "important-caption"=>"Important", "last-update-label"=>"Last updated", "note-caption"=>"Note", "part-refsig"=>"Part", "prewrap"=>"", "sectids"=>"", "section-refsig"=>"Section", "table-caption"=>"Table", "tip-caption"=>"Tip", "toc-placement"=>"macro", "toc-title"=>"Table of Contents", "untitled-label"=>"Untitled", "version-label"=>"Version", "warning-caption"=>"Warning", "notitle"=>"", "docfile"=>"/home/brian/Documents/work/releasehx/README.adoc", "docdir"=>"/home/brian/Documents/work/releasehx", "docfilesuffix"=>".adoc", "docname"=>"README", "embedded"=>"", "asciidoctor"=>"", "asciidoctor-version"=>"2.0.23", "safe-mode-name"=>"unsafe", "safe-mode-unsafe"=>"", "safe-mode-level"=>0, "max-include-depth"=>64, "user-home"=>"/home/brian", "doctype"=>"article", "htmlsyntax"=>"html", "backend-html5-doctype-article"=>"", "doctype-article"=>"", "backend-html5"=>"", "backend"=>"html5", "outfilesuffix"=>".html", "filetype"=>"html", "filetype-html"=>"", "basebackend-html-doctype-article"=>"", "basebackend-html"=>"", "basebackend"=>"html", "stylesdir"=>".", "iconsdir"=>"./images/icons", "localdate"=>"2026-01-01", "localyear"=>"2026", "localtime"=>"13:42:59 -0500", "localdatetime"=>"2026-01-01 13:42:59 -0500", "docdate"=>"2026-01-01", "docyear"=>"2026", "doctime"=>"13:41:27 -0500", "docdatetime"=>"2026-01-01 13:41:27 -0500", "page-layout"=>"default", "page-permalink"=>"/docs", "page-nav_order"=>"1", "doctitle"=>"ReleaseHx", "docopslab_git_www"=>"https://github.com/DocOps", "this_prod_slug"=>"releasehx", "releasehx_prod_repo"=>"https://github.com/DocOps/releasehx", "releasehx_demo_repo"=>"https://github.com/DocOps/releasehx-demo", "this_prod_repo"=>"https://github.com/DocOps/releasehx", "this_prod_vrsn_major"=>"0", "this_prod_vrsn_minor"=>"1", "this_prod_vrsn_major-minor"=>"0.1", "this_prod_vrsn_patch"=>"1", "this_prod_vrsn"=>"0.1.1", "next_prod_vrsn"=>"0.2.0", "tagline"=>"Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.", "description"=>"CLI utility and Ruby API for generating structured release notes and changelog documents from various issue-tracking platforms or YAML definitions into plaintext drafts (<strong>AsciiDoc</strong>, <strong>Markdown</strong>, <strong>YAML</strong>) and rich-text output (<strong>HTML</strong> and <strong>PDF</strong>).", "gem_config_definition_path"=>"./specs/data/config-def.yml", "app_default_config_path"=>"./.releasehx.yml", "default_markup"=>"markdown", "default_slug_type"=>"kebab", "default_tplt_lang"=>"liquid", "default_drafts_dir"=>"_drafts", "default_enrich_dir"=>"_publish", "default_output_dir"=>".", "default_payloads_dir"=>"_payloads", "default_templates_dir"=>"_templates", "default_mappings_dir"=>"_mappings", "default_api_clients_dir"=>"_apis", "default_cache_dir"=>".releasehx/cache", "default_api_cred_env"=>"RELEASEHX_API_CRED", "default_api_key_env"=>"RELEASEHX_API_KEY", "default_api_user_env"=>"RELEASEHX_API_USER", "default_api_org_env"=>"RELEASEHX_API_ORG", "markdown_extensions"=>".md, .markdown", "asciidoc_extensions"=>".adoc, .ad, .asciidoc", "yaml_extensions"=>".yml, .yaml, .rhyml", "draft_source_file_types"=>"AsciiDoc, Markdown, YAML", "draft_source_extensions"=>".md, .markdown, .adoc, .ad, .asciidoc, .yml, .yaml, .rhyml", "enrich_file_types"=>"HTML, PDF", "enrich_extensions"=>".html, .pdf", "docker_base_command"=>"docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir docopslab/releasehx rhx", "this_prod_repo_branch"=>"https://github.com/DocOps/releasehx/tree/release/0.1", "docs_extn"=>"", "toc"=>"", "toclevels"=>"3", "authorcount"=>0, "toc-position"=>"content"}}
+  ATTRIBUTES = {:globals=>{"attribute-undefined"=>"drop-line", "attribute-missing"=>"skip", "appendix-caption"=>"Appendix", "appendix-refsig"=>"Appendix", "caution-caption"=>"Caution", "chapter-refsig"=>"Chapter", "example-caption"=>"Example", "figure-caption"=>"Figure", "important-caption"=>"Important", "last-update-label"=>"Last updated", "note-caption"=>"Note", "part-refsig"=>"Part", "prewrap"=>"", "sectids"=>"", "section-refsig"=>"Section", "table-caption"=>"Table", "tip-caption"=>"Tip", "toc-placement"=>"macro", "toc-title"=>"Table of Contents", "untitled-label"=>"Untitled", "version-label"=>"Version", "warning-caption"=>"Warning", "notitle"=>"", "docfile"=>"/home/brian/Documents/work/releasehx/README.adoc", "docdir"=>"/home/brian/Documents/work/releasehx", "docfilesuffix"=>".adoc", "docname"=>"README", "embedded"=>"", "asciidoctor"=>"", "asciidoctor-version"=>"2.0.26", "safe-mode-name"=>"unsafe", "safe-mode-unsafe"=>"", "safe-mode-level"=>0, "max-include-depth"=>64, "user-home"=>"/home/brian", "doctype"=>"article", "htmlsyntax"=>"html", "backend-html5-doctype-article"=>"", "doctype-article"=>"", "backend-html5"=>"", "backend"=>"html5", "outfilesuffix"=>".html", "filetype"=>"html", "filetype-html"=>"", "basebackend-html-doctype-article"=>"", "basebackend-html"=>"", "basebackend"=>"html", "stylesdir"=>".", "iconsdir"=>"./images/icons", "localdate"=>"2026-05-27", "localyear"=>"2026", "localtime"=>"11:16:48 -0400", "localdatetime"=>"2026-05-27 11:16:48 -0400", "docdate"=>"2026-05-27", "docyear"=>"2026", "doctime"=>"10:37:27 -0400", "docdatetime"=>"2026-05-27 10:37:27 -0400", "page-layout"=>"default", "page-permalink"=>"/docs/", "page-title"=>"ReleaseHx Docs", "page-nav_order"=>"1", "doctitle"=>"ReleaseHx", "this_proj_slug"=>"releasehx", "this_proj_name"=>"ReleaseHx", "docopslab_src_www_url"=>"https://raw.githubusercontent.com/DocOps", "docopslab_domain"=>"docopslab.org", "docopslab_www_url"=>"https://docopslab.org", "docopslab_io_www_url"=>"https://docopslab.github.io", "docopslab_ruby_version"=>"3.2.7", "docopslab_git_src_uri"=>"git@github.com:DocOps", "this_proj_src_www_url"=>"https://raw.githubusercontent.com/DocOps/releasehx", "this_proj_src_raw_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/main", "this_proj_src_main_files_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/blob/main", "this_proj_src_main_edit_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/edit/main", "this_proj_src_git_uri"=>"git@github.com:DocOps/releasehx.git", "this_proj_ruby_version"=>"3.2.7", "extn"=>"", "releasehx_demo_repo"=>"https://raw.githubusercontent.com/DocOps/releasehx-demo", "this_prod_slug"=>"releasehx", "this_prod_vrsn_major"=>"0", "this_prod_vrsn_minor"=>"2", "this_prod_vrsn_majmin"=>"0.2", "this_prod_vrsn_patch"=>"0", "this_prod_vrsn"=>"0.2.0", "next_prod_vrsn"=>"0.3.0", "next_prod_vrsn_majmin"=>"0.3", "tagline"=>"Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.", "description"=>"CLI utility and Ruby API for generating structured release notes and changelog documents from various issue-tracking platforms or YAML definitions into plaintext drafts (<strong>AsciiDoc</strong>, <strong>Markdown</strong>, <strong>YAML</strong>) and rich-text output (<strong>HTML</strong> and <strong>PDF</strong>).", "gem_config_definition_path"=>"./specs/data/config-def.yml", "app_default_config_path"=>"./.releasehx.yml", "docker_run_command"=>"docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir docopslab/releasehx rhx", "default_markup"=>"markdown", "default_slug_type"=>"kebab", "default_tplt_lang"=>"liquid", "default_drafts_dir"=>"_drafts", "default_enrich_dir"=>"_publish", "default_output_dir"=>".", "default_payloads_dir"=>"_payloads", "default_templates_dir"=>"_templates", "default_mappings_dir"=>"_mappings", "default_api_clients_dir"=>"_apis", "default_cache_dir"=>".releasehx/cache", "default_api_cred_env"=>"RELEASEHX_API_CRED", "default_api_key_env"=>"RELEASEHX_API_KEY", "default_api_user_env"=>"RELEASEHX_API_USER", "default_api_org_env"=>"RELEASEHX_API_ORG", "markdown_extensions"=>".md, .markdown", "asciidoc_extensions"=>".adoc, .ad, .asciidoc", "yaml_extensions"=>".yml, .yaml, .rhyml", "draft_source_file_types"=>"AsciiDoc, Markdown, YAML", "draft_source_extensions"=>".md, .markdown, .adoc, .ad, .asciidoc, .yml, .yaml, .rhyml", "enrich_file_types"=>"HTML, PDF", "enrich_extensions"=>".html, .pdf", "asciisourcerer_www_url"=>"https://raw.githubusercontent.com/DocOps/asciisourcerer", "schemagraphy_www_url"=>"https://raw.githubusercontent.com/DocOps/schemagraphy", "toc"=>"", "toclevels"=>"3", "authorcount"=>0, "toc-position"=>"content"}}
 
   SNIPPET_LOOKUP = {"helpscreen"=>"helpscreen.txt"}
 

data/lib/releasehx/mcp/assets/agent-config-guide.md

@@ -137,7 +137,7 @@ Use `releasehx://config/schema` when:
 ## Potentially unintuitive principles
 
 - **“Frontmatter” is controlled in two places (toggle vs template).**  
-  If you’re trying to *turn frontmatter on/off*, look under `modes.*_frontmatter`. If you’re trying to *change what frontmatter contains*, look under `templates.*_frontmatter` (Markdown/AsciiDoc/HTML each have their own). Also note `modes.wrapped` affects HTML wrapping, which can look like a frontmatter problem when it’s really wrapping/boilerplate.
+  If you're trying to *turn frontmatter on/off*, look under `modes.*_frontmatter`. If you're trying to *change what frontmatter contains*, look under `templates.*_frontmatter` (Markdown/AsciiDoc/HTML each have their own). Also note `modes.html_wrap` affects HTML wrapping, which can look like a frontmatter problem when it's really wrapping/boilerplate.
 
 - **Links require both a template and an enable switch.**  
   Defining URL templates under `links.web.href` / `links.git.href` does nothing by itself. You must also enable display under `history.items.show_issue_links` / `history.items.show_git_links` (or the per-section overrides under changelog/notes items, if present). If a user says “I set the link template but no links appear,” check the `history.*items*` flags.

data/lib/releasehx/mcp/assets/config-def.yml

@@ -165,6 +165,7 @@ properties:
           Must be `issue_body`, `custom_field`, or `commit_message`.
 
           Defaults to `issue_body` for GitHub and GitLab, but to `custom_field` for Jira.
+        dflt: issue_body
       note_custom_field:
         type: String
         desc: |
@@ -182,7 +183,8 @@ properties:
           Uses Capture group `note` in the Regular Expression to establish the entire note content.
 
           See the `conversions.head_pattern` property for details on extracting a heading (`head` in RHYML) from the `note` content.
-        dflt: '/^((#|=)+ (Draft )?Release Note.*)|(<!-- (draft )?release note -->)\n(?<note>\w(.|\n)+)/gmi'
+        dflt: '/^(((#|=)+ (Draft )?Release Note.*?)|(<!-- (draft )?release note -->))\n+(?<note>(.|
+)+)/gmi'
       head_pattern:
         type: RegExp
         desc: |
@@ -201,12 +203,59 @@ properties:
           The origin markup format for notes.
           May be `markdown` or `asciidoc`.
         dflt: markdown
-      engine:
-        type: String
+      engines:
         desc: |
-          The markup converter to use for the issues.
-          Defaults to `asciidoctor` for AsciiDoc and `redcarpet` for Markdown.
-          Options include `asciidoctor`, `redcarpet`, `commonmarker`, `kramdown`, or `pandoc`.
+          Specifies the conversion engines to use when enriching to various output formats.
+          
+          These settings determine which tool processes the conversion from draft formats to rich output.
+          Intelligent defaults are applied based on source format when engines are not explicitly configured.
+        properties:
+          html:
+            type: String
+            desc: |
+              Engine for converting to HTML format.
+              
+              Valid engines:
+              
+              [horizontal]
+              `asciidoctor-html5`:: Standard Asciidoctor HTML5 backend (nested div structure)
+              `asciidoctor-html5s`:: Semantic HTML5 backend (cleaner section-based markup)
+              `kramdown`:: Kramdown Markdown converter (for Markdown sources)
+              `pandoc`:: Universal document converter (if available)
+              
+              When not specified, intelligent defaults apply:
+              
+              - AsciiDoc → HTML: `asciidoctor-html5s` (semantic HTML5)
+              - Markdown → HTML: `kramdown`
+              - RHYML → HTML: Liquid templates (no engine needed)
+            docs: |
+              The html5s backend produces cleaner, more semantic HTML with `<section>` elements
+              instead of nested `<div class="sect1"><div class="sectionbody">` structures.
+              
+              This is particularly useful when you want to apply custom CSS or when generating
+              HTML that will be further processed or embedded in other systems.
+              
+              For backwards compatibility or when you need the traditional Asciidoctor structure,
+              use `asciidoctor-html5`.
+          pdf:
+            type: String
+            desc: |
+              Engine for converting to PDF format.
+              
+              Valid engines:
+              
+              [horizontal]
+              `asciidoctor-pdf`:: Asciidoctor PDF converter (default for AsciiDoc)
+              `asciidoctor-web-pdf`:: Web-based PDF converter using headless Chrome
+              `pandoc`:: Universal document converter (if available)
+              
+              When not specified, intelligent defaults apply:
+              
+              - AsciiDoc → PDF: `asciidoctor-pdf`
+              - Markdown → PDF: `pandoc` (if available)
+            docs: |
+              The default `asciidoctor-pdf` engine provides excellent typography and layout
+              for technical documentation with support for themes, fonts, and advanced formatting.
 
   extensions:
     desc: Default file extensions.
@@ -835,7 +884,7 @@ properties:
     desc: |
       Default settings for `rhx` command executions.
     properties:
-      wrapped:
+      html_wrap:
         type: Boolean
         desc: |
           Include (or exclude) head, header, and footer elements when enriching to HTML.
@@ -860,6 +909,7 @@ properties:
           Include frontmatter in AsciiDoc drafts.
 
           Uses the `templates.asciidoc_frontmatter` template.
+        dflt: false
       fetch:
         type: String
         desc: |
@@ -1041,6 +1091,74 @@ properties:
 
           It may include `{{ title }}`, `{{ version }}`, `{{ date }}`, as well as any `vars`-scoped variables as you pass in.
         dflt: *markdown_frontmatter_tplt
+      html_framework:
+        type: String
+        desc: |
+          The HTML framework to use when enriching to HTML.
+
+          Valid entries:
+          
+          [horizontal]
+          `bare`:: minimal HTML structure
+          `bootstrap4`:: Bootstrap 4 framework
+          `bootstrap5`:: Bootstrap 5 framework
+        dflt: bare
+      styling:
+        desc: |
+          Configuration options for HTML styling and CSS framework integration.
+        properties:
+          mode:
+            type: String
+            desc: |
+              The HTML styling approach to use when generating wrapped HTML output.
+
+              Valid options:
+
+              * `minimal` -- Basic semantic HTML with minimal inline styles
+              * `embedded` -- Include comprehensive CSS in `<style>` block 
+              * `external` -- Reference external stylesheet via `<link>` tag
+              * `framework` -- Use configured CSS framework only (Bootstrap, etc.)
+
+              When `mode: framework`, styling relies entirely on the configured CSS framework.
+              When `mode: embedded`, CSS is included inline for standalone HTML files.
+              When `mode: external`, a custom CSS file must be provided via `css_url`.
+            dflt: framework
+          theme:
+            type: String
+            desc: |
+              The visual theme variant to apply to HTML output.
+
+              Built-in themes:
+
+              * `default` -- Standard professional appearance
+              * `compact` -- Reduced spacing and condensed layout
+              * `detailed` -- Enhanced metadata display with expanded information
+
+              Theme selection affects spacing, typography, and metadata prominence.
+            dflt: default
+          embed_css:
+            type: Boolean
+            desc: |
+              Include comprehensive CSS directly in the HTML `<style>` block.
+
+              When enabled, generates standalone HTML files that display correctly
+              without external dependencies. CSS includes framework customizations,
+              responsive design rules, and print optimizations.
+
+              Automatically enabled when `mode: embedded`.
+            dflt: false
+          css_url:
+            type: String
+            desc: |
+              URL or path to external CSS stylesheet for custom styling.
+
+              When `mode: external`, this stylesheet is linked via `<link rel="stylesheet">`.
+              Can be a relative path, absolute URL, or CDN link.
+
+              Example: `assets/custom-releasehx.css` or `https://example.com/styles.css`
+
+              When provided, framework CSS and embedded CSS are disabled.
+            dflt: null
       items:
         desc: |
           Settings pertaining to displayed items across Changelog and Release Notes sections.
@@ -1162,7 +1280,7 @@ properties:
               The label to use for the _singular_ part/component affected by the change, when only one part is permitted.
 
               This value will apply either when <<conf_ppty_rhyml_max_parts>> is set to `1` or when the change has only one part _and_ <<conf_ppty_history_labeling_singularize_labels>> is `true`.
-            dflt: Part
+            dflt: Component
           parts_icon:
             type: String
             desc: |

data/lib/releasehx/mcp/assets/config-reference.adoc

@@ -1,7 +1,4 @@
-:page-layout: default
-:page-permalink: /config-reference/
-:page-nav_order: 2
-:page-title: Configuration Reference
+
 
 [[conf_ppty_DOLLARSIGN_meta,config.$meta]]
 $meta::
@@ -359,6 +356,9 @@ Defaults to `issue_body` for GitHub and GitLab, but to `custom_field` for Jira.
 
 [horizontal]
 type;; String
+default;;
++
+`+++issue_body+++`
 path;; `xref:conf_ppty_conversions_note[config.conversions.note]`
 --
 
@@ -395,7 +395,7 @@ type;; RegExp
 default;;
 +
 ....
-/^((#|=)+ (Draft )?Release Note.*)|(<!-- (draft )?release note -->)\n(?<note>\w(.|\n)+)/gmi
+/^(((#|=)+ (Draft )?Release Note.*?)|(<!-- (draft )?release note -->))\n+(?<note>(.| )+)/gmi
 ....
 path;; `xref:conf_ppty_conversions_note_pattern[config.conversions.note_pattern]`
 --
@@ -438,18 +438,80 @@ default;;
 path;; `xref:conf_ppty_conversions_markup[config.conversions.markup]`
 --
 
-[[conf_ppty_conversions_engine,config.conversions.engine]]
-conversions.engine:::
+[[conf_ppty_conversions_engines,config.conversions.engines]]
+conversions.engines:::
++
+--
+Specifies the conversion engines to use when enriching to various output formats.
+
+These settings determine which tool processes the conversion from draft formats to rich output.
+Intelligent defaults are applied based on source format when engines are not explicitly configured.
+
+
+[horizontal]
+path;; `xref:conf_ppty_conversions_engines[config.conversions.engines]`
+--
+
+[[conf_ppty_conversions_engines_html,config.conversions.engines.html]]
+conversions.engines.html::::
++
+--
+Engine for converting to HTML format.
+
+Valid engines:
+
+[horizontal]
+`asciidoctor-html5`:: Standard Asciidoctor HTML5 backend (nested div structure)
+`asciidoctor-html5s`:: Semantic HTML5 backend (cleaner section-based markup)
+`kramdown`:: Kramdown Markdown converter (for Markdown sources)
+`pandoc`:: Universal document converter (if available)
+
+When not specified, intelligent defaults apply:
+
+- AsciiDoc → HTML: `asciidoctor-html5s` (semantic HTML5)
+- Markdown → HTML: `kramdown`
+- RHYML → HTML: Liquid templates (no engine needed)
+
+The html5s backend produces cleaner, more semantic HTML with `<section>` elements
+instead of nested `<div class="sect1"><div class="sectionbody">` structures.
+
+This is particularly useful when you want to apply custom CSS or when generating
+HTML that will be further processed or embedded in other systems.
+
+For backwards compatibility or when you need the traditional Asciidoctor structure,
+use `asciidoctor-html5`.
+
+
+[horizontal]
+type;; String
+path;; `xref:conf_ppty_conversions_engines_html[config.conversions.engines.html]`
+--
+
+[[conf_ppty_conversions_engines_pdf,config.conversions.engines.pdf]]
+conversions.engines.pdf::::
 +
 --
-The markup converter to use for the issues.
-Defaults to `asciidoctor` for AsciiDoc and `redcarpet` for Markdown.
-Options include `asciidoctor`, `redcarpet`, `commonmarker`, `kramdown`, or `pandoc`.
+Engine for converting to PDF format.
+
+Valid engines:
+
+[horizontal]
+`asciidoctor-pdf`:: Asciidoctor PDF converter (default for AsciiDoc)
+`asciidoctor-web-pdf`:: Web-based PDF converter using headless Chrome
+`pandoc`:: Universal document converter (if available)
+
+When not specified, intelligent defaults apply:
+
+- AsciiDoc → PDF: `asciidoctor-pdf`
+- Markdown → PDF: `pandoc` (if available)
+
+The default `asciidoctor-pdf` engine provides excellent typography and layout
+for technical documentation with support for themes, fonts, and advanced formatting.
 
 
 [horizontal]
 type;; String
-path;; `xref:conf_ppty_conversions_engine[config.conversions.engine]`
+path;; `xref:conf_ppty_conversions_engines_pdf[config.conversions.engines.pdf]`
 --
 
 [[conf_ppty_extensions,config.extensions]]
@@ -2497,8 +2559,8 @@ Default settings for `rhx` command executions.
 path;; `xref:conf_ppty_modes[config.modes]`
 --
 
-[[conf_ppty_modes_wrapped,config.modes.wrapped]]
-modes.wrapped:::
+[[conf_ppty_modes_html_wrap,config.modes.html_wrap]]
+modes.html_wrap:::
 +
 --
 Include (or exclude) head, header, and footer elements when enriching to HTML.
@@ -2509,7 +2571,7 @@ type;; Boolean
 default;;
 +
 `+++false+++`
-path;; `xref:conf_ppty_modes_wrapped[config.modes.wrapped]`
+path;; `xref:conf_ppty_modes_html_wrap[config.modes.html_wrap]`
 --
 
 [[conf_ppty_modes_html_frontmatter,config.modes.html_frontmatter]]
@@ -2557,6 +2619,9 @@ Uses the `templates.asciidoc_frontmatter` template.
 
 [horizontal]
 type;; Boolean
+default;;
++
+`+++false+++`
 path;; `xref:conf_ppty_modes_asciidoc_frontmatter[config.modes.asciidoc_frontmatter]`
 --
 
@@ -2871,6 +2936,128 @@ date: {{ release.date }}
 path;; `xref:conf_ppty_history_html_frontmatter[config.history.html_frontmatter]`
 --
 
+[[conf_ppty_history_html_framework,config.history.html_framework]]
+history.html_framework:::
++
+--
+The HTML framework to use when enriching to HTML.
+
+Valid entries:
+
+[horizontal]
+`bare`:: minimal HTML structure
+`bootstrap4`:: Bootstrap 4 framework
+`bootstrap5`:: Bootstrap 5 framework
+
+
+[horizontal]
+type;; String
+default;;
++
+`+++bare+++`
+path;; `xref:conf_ppty_history_html_framework[config.history.html_framework]`
+--
+
+[[conf_ppty_history_styling,config.history.styling]]
+history.styling:::
++
+--
+Configuration options for HTML styling and CSS framework integration.
+
+
+[horizontal]
+path;; `xref:conf_ppty_history_styling[config.history.styling]`
+--
+
+[[conf_ppty_history_styling_mode,config.history.styling.mode]]
+history.styling.mode::::
++
+--
+The HTML styling approach to use when generating wrapped HTML output.
+
+Valid options:
+
+* `minimal` -- Basic semantic HTML with minimal inline styles
+* `embedded` -- Include comprehensive CSS in `<style>` block 
+* `external` -- Reference external stylesheet via `<link>` tag
+* `framework` -- Use configured CSS framework only (Bootstrap, etc.)
+
+When `mode: framework`, styling relies entirely on the configured CSS framework.
+When `mode: embedded`, CSS is included inline for standalone HTML files.
+When `mode: external`, a custom CSS file must be provided via `css_url`.
+
+
+[horizontal]
+type;; String
+default;;
++
+`+++framework+++`
+path;; `xref:conf_ppty_history_styling_mode[config.history.styling.mode]`
+--
+
+[[conf_ppty_history_styling_theme,config.history.styling.theme]]
+history.styling.theme::::
++
+--
+The visual theme variant to apply to HTML output.
+
+Built-in themes:
+
+* `default` -- Standard professional appearance
+* `compact` -- Reduced spacing and condensed layout
+* `detailed` -- Enhanced metadata display with expanded information
+
+Theme selection affects spacing, typography, and metadata prominence.
+
+
+[horizontal]
+type;; String
+default;;
++
+`+++default+++`
+path;; `xref:conf_ppty_history_styling_theme[config.history.styling.theme]`
+--
+
+[[conf_ppty_history_styling_embed_css,config.history.styling.embed_css]]
+history.styling.embed_css::::
++
+--
+Include comprehensive CSS directly in the HTML `<style>` block.
+
+When enabled, generates standalone HTML files that display correctly
+without external dependencies. CSS includes framework customizations,
+responsive design rules, and print optimizations.
+
+Automatically enabled when `mode: embedded`.
+
+
+[horizontal]
+type;; Boolean
+default;;
++
+`+++false+++`
+path;; `xref:conf_ppty_history_styling_embed_css[config.history.styling.embed_css]`
+--
+
+[[conf_ppty_history_styling_css_url,config.history.styling.css_url]]
+history.styling.css_url::::
++
+--
+URL or path to external CSS stylesheet for custom styling.
+
+When `mode: external`, this stylesheet is linked via `<link rel="stylesheet">`.
+Can be a relative path, absolute URL, or CDN link.
+
+Example: `assets/custom-releasehx.css` or `https://example.com/styles.css`
+
+When provided, framework CSS and embedded CSS are disabled.
+
+
+[horizontal]
+type;; String
+path;; `xref:conf_ppty_history_styling_css_url[config.history.styling.css_url]`
+--
+
 [[conf_ppty_history_items,config.history.items]]
 history.items:::
 +
@@ -3161,7 +3348,7 @@ This value will apply either when <<conf_ppty_rhyml_max_parts>> is set to `1` or
 type;; String
 default;;
 +
-`+++Part+++`
+`+++Component+++`
 path;; `xref:conf_ppty_history_labeling_part_label[config.history.labeling.part_label]`
 --
 
@@ -4101,4 +4288,4 @@ default;;
 +
 `+++false+++`
 path;; `xref:conf_ppty_notes_items_show_auths_label[config.notes.items.show_auths_label]`
---
+--