releasehx 0.1.2 → 0.2.0

data/build/docs/_config.yml

@@ -33,6 +33,7 @@ exclude:
   - payloads/
   - release/
   - yard/
+  - release-procedure.adoc
 
 # Enable Rouge for syntax highlighting in AsciiDoc blocks
 asciidoctor:

data/build/docs/_release_index.adoc

@@ -2,8 +2,9 @@
 
 Each release includes detailed notes about new features, improvements, bug fixes, and breaking changes.
 
-* link:../release/0.1.2.html[0.1.2] - 2026-01-29
+* link:../release/0.2.0[0.2.0] - 2026-05-27
+* link:../release/0.1.2[0.1.2] - 2026-01-30
 
 == Latest Release
 
-include::release/0.1.2.adoc[leveloffset=+1]
+include::release/0.2.0.adoc[leveloffset=+1]

data/build/docs/config-reference.adoc

@@ -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:::
 +
 --
-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.
+
+
+[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_engine[config.conversions.engine]`
+path;; `xref:conf_ppty_conversions_engines_html[config.conversions.engines.html]`
+--
+
+[[conf_ppty_conversions_engines_pdf,config.conversions.engines.pdf]]
+conversions.engines.pdf::::
++
+--
+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_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:::
 +
@@ -4101,4 +4288,4 @@ default;;
 +
 `+++false+++`
 path;; `xref:conf_ppty_notes_items_show_auths_label[config.notes.items.show_auths_label]`
---
+--

data/build/docs/config-reference.json

@@ -155,10 +155,23 @@
           "type": "String",
           "default": "markdown"
         },
-        "engine": {
-          "path": "conversions.engine",
-          "desc": "The markup converter to use for the issues.\nDefaults to `asciidoctor` for AsciiDoc and `redcarpet` for Markdown.\nOptions include `asciidoctor`, `redcarpet`, `commonmarker`, `kramdown`, or `pandoc`.\n",
-          "type": "String"
+        "engines": {
+          "path": "conversions.engines",
+          "desc": "Specifies the conversion engines to use when enriching to various output formats.\n\nThese settings determine which tool processes the conversion from draft formats to rich output.\nIntelligent defaults are applied based on source format when engines are not explicitly configured.\n",
+          "properties": {
+            "html": {
+              "path": "conversions.engines.html",
+              "desc": "Engine for converting to HTML format.\n\nValid engines:\n\n[horizontal]\n`asciidoctor-html5`:: Standard Asciidoctor HTML5 backend (nested div structure)\n`asciidoctor-html5s`:: Semantic HTML5 backend (cleaner section-based markup)\n`kramdown`:: Kramdown Markdown converter (for Markdown sources)\n`pandoc`:: Universal document converter (if available)\n\nWhen not specified, intelligent defaults apply:\n\n- AsciiDoc → HTML: `asciidoctor-html5s` (semantic HTML5)\n- Markdown → HTML: `kramdown`\n- RHYML → HTML: Liquid templates (no engine needed)\n",
+              "docs": "The html5s backend produces cleaner, more semantic HTML with `<section>` elements\ninstead of nested `<div class=\"sect1\"><div class=\"sectionbody\">` structures.\n\nThis is particularly useful when you want to apply custom CSS or when generating\nHTML that will be further processed or embedded in other systems.\n\nFor backwards compatibility or when you need the traditional Asciidoctor structure,\nuse `asciidoctor-html5`.\n",
+              "type": "String"
+            },
+            "pdf": {
+              "path": "conversions.engines.pdf",
+              "desc": "Engine for converting to PDF format.\n\nValid engines:\n\n[horizontal]\n`asciidoctor-pdf`:: Asciidoctor PDF converter (default for AsciiDoc)\n`asciidoctor-web-pdf`:: Web-based PDF converter using headless Chrome\n`pandoc`:: Universal document converter (if available)\n\nWhen not specified, intelligent defaults apply:\n\n- AsciiDoc → PDF: `asciidoctor-pdf`\n- Markdown → PDF: `pandoc` (if available)\n",
+              "docs": "The default `asciidoctor-pdf` engine provides excellent typography and layout\nfor technical documentation with support for themes, fonts, and advanced formatting.\n",
+              "type": "String"
+            }
+          }
         }
       }
     },
@@ -996,8 +1009,8 @@
       "path": "modes",
       "desc": "Default settings for `rhx` command executions.\n",
       "properties": {
-        "wrapped": {
-          "path": "modes.wrapped",
+        "html_wrap": {
+          "path": "modes.html_wrap",
           "desc": "Include (or exclude) head, header, and footer elements when enriching to HTML.\n",
           "type": "Boolean",
           "default": false
@@ -1017,7 +1030,8 @@
         "asciidoc_frontmatter": {
           "path": "modes.asciidoc_frontmatter",
           "desc": "Include frontmatter in AsciiDoc drafts.\n\nUses the `templates.asciidoc_frontmatter` template.\n",
-          "type": "Boolean"
+          "type": "Boolean",
+          "default": false
         },
         "fetch": {
           "path": "modes.fetch",
@@ -1126,6 +1140,41 @@
           "type": "Liquid",
           "default": "---\ntitle: Release History for {{ release.code }}\nversion: {{ release.code }}\ndate: {{ release.date }}\n---\n"
         },
+        "html_framework": {
+          "path": "history.html_framework",
+          "desc": "The HTML framework to use when enriching to HTML.\n\nValid entries:\n\n[horizontal]\n`bare`:: minimal HTML structure\n`bootstrap4`:: Bootstrap 4 framework\n`bootstrap5`:: Bootstrap 5 framework\n",
+          "type": "String",
+          "default": "bare"
+        },
+        "styling": {
+          "path": "history.styling",
+          "desc": "Configuration options for HTML styling and CSS framework integration.\n",
+          "properties": {
+            "mode": {
+              "path": "history.styling.mode",
+              "desc": "The HTML styling approach to use when generating wrapped HTML output.\n\nValid options:\n\n* `minimal` -- Basic semantic HTML with minimal inline styles\n* `embedded` -- Include comprehensive CSS in `<style>` block \n* `external` -- Reference external stylesheet via `<link>` tag\n* `framework` -- Use configured CSS framework only (Bootstrap, etc.)\n\nWhen `mode: framework`, styling relies entirely on the configured CSS framework.\nWhen `mode: embedded`, CSS is included inline for standalone HTML files.\nWhen `mode: external`, a custom CSS file must be provided via `css_url`.\n",
+              "type": "String",
+              "default": "framework"
+            },
+            "theme": {
+              "path": "history.styling.theme",
+              "desc": "The visual theme variant to apply to HTML output.\n\nBuilt-in themes:\n\n* `default` -- Standard professional appearance\n* `compact` -- Reduced spacing and condensed layout\n* `detailed` -- Enhanced metadata display with expanded information\n\nTheme selection affects spacing, typography, and metadata prominence.\n",
+              "type": "String",
+              "default": "default"
+            },
+            "embed_css": {
+              "path": "history.styling.embed_css",
+              "desc": "Include comprehensive CSS directly in the HTML `<style>` block.\n\nWhen enabled, generates standalone HTML files that display correctly\nwithout external dependencies. CSS includes framework customizations,\nresponsive design rules, and print optimizations.\n\nAutomatically enabled when `mode: embedded`.\n",
+              "type": "Boolean",
+              "default": false
+            },
+            "css_url": {
+              "path": "history.styling.css_url",
+              "desc": "URL or path to external CSS stylesheet for custom styling.\n\nWhen `mode: external`, this stylesheet is linked via `<link rel=\"stylesheet\">`.\nCan be a relative path, absolute URL, or CDN link.\n\nExample: `assets/custom-releasehx.css` or `https://example.com/styles.css`\n\nWhen provided, framework CSS and embedded CSS are disabled.\n",
+              "type": "String"
+            }
+          }
+        },
         "items": {
           "path": "history.items",
           "desc": "Settings pertaining to displayed items across Changelog and Release Notes sections.\n\nMost of these settings can be defined separately for each section under <<conf_ppty_changelog_items>> and <<conf_ppty_notes_items>>.\nIf an identically named setting exists, it will override the primary designator defined in this `config.history.items` block.\n",