Release/0.2.1

.config/docopslab-dev.yml

@@ -56,7 +56,7 @@ tools:
         - specs/*
         - "**/config-reference.adoc"
         - docs/releases.adoc
-        - docs/release/*
+        - docs/_releases/*
         - .bundle/*
         - .agent/*
         - docs/manpage.adoc

.config/releasehx.yml

@@ -9,10 +9,10 @@ origin:
   format: json
 
 paths:
-  drafts_dir: docs/release/drafts
-  payloads_dir: docs/release/payloads
-  templates_dir: docs/release/templates
-  mappings_dir: docs/release/mappings
+  drafts_dir: docs/_releases/drafts
+  payloads_dir: docs/_releases/payloads
+  templates_dir: docs/_releases/templates
+  mappings_dir: docs/_releases/mappings
 
 conversions:
   summ: issue_heading

.gitignore

@@ -80,6 +80,6 @@ dev/
 releasehx-demo/
 
 # Release history working directories
-docs/release/drafts/
-docs/release/payloads/
+docs/_releases/drafts/
+docs/_releases/payloads/
 docs/agent/*.md

AGENTS.md

@@ -272,7 +272,7 @@ bundle exec rspec specs/tests/rspec --format documentation
 The releasehx-demo repository can help illustrate real usage (optional):
 
 ```bash
-git clone {releasehx_demo_repo}
+git clone git@github.com:DocOps/releasehx-demo.git
 cd releasehx-demo
 
 # Study different API data structures

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    releasehx (0.2.0)
+    releasehx (0.2.1)
       asciidoctor-html5s (~> 0.5)
       asciidoctor-pdf (~> 2.3)
       asciisourcerer (~> 0.4)

README.adoc

@@ -12,23 +12,25 @@
 :this_proj_slug: releasehx
 :this_proj_name: ReleaseHx
 // tag::universal-settings[]
+// ALL changes within this block must be made in prime template:
+//  DocOps/lab/gems/docopslab-dev/templates/README.asciidoc
 :docopslab_src_www_url: https://github.com/DocOps
 :docopslab_domain: docopslab.org
 :docopslab_www_url: https://{docopslab_domain}
 :docopslab_io_www_url: https://docopslab.github.io
 :docopslab_ruby_version: 3.2.7
-:docopslab_src_www_url: https://raw.githubusercontent.com/DocOps
 :docopslab_git_src_uri: git@github.com:DocOps
+:docopslab_src_raw_url: https://raw.githubusercontent.com/DocOps
 :this_proj_src_www_url: {docopslab_src_www_url}/{this_proj_slug}
-:this_proj_src_raw_url: https://raw.githubusercontent.com/DocOps/{this_proj_slug}/main
+:this_proj_src_raw_url: {docopslab_src_raw_url}/{this_proj_slug}
+:this_proj_src_main_raw_url: {this_proj_src_raw_url}/main
 :this_proj_src_main_files_url: {this_proj_src_www_url}/blob/main
-:this_proj_src_main_edit_url: {this_proj_src_www_url}/edit/main
 :this_proj_src_git_uri: {docopslab_git_src_uri}/{this_proj_slug}.git
 :this_proj_ruby_version: {docopslab_ruby_version}
 // tag::env-settings[]
-:extn:
+:docs_extn:
 ifdef::env-github[]
-:extn: .adoc
+:docs_extn: .adoc
 :icons: font
 :caution-caption: :fire:
 :important-caption: :exclamation:
@@ -37,15 +39,19 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 // end::env-settings[]
+// Settings likely to be overridden locally
+:this_prod_slug: {this_proj_slug}
+:this_prod_name: {this_proj_name}
+:this_prod_src_www_url: {this_proj_src_www_url}
 // end::universal-settings[]
-:releasehx_demo_repo: {docopslab_src_www_url}/releasehx-demo
+:releasehx-demo_repo_www_url: {docopslab_src_www_url}/releasehx-demo
 // tag::product-settings[]
 :this_prod_slug: {this_proj_slug}
 // tag::version-settings[]
 :this_prod_vrsn_major: 0
 :this_prod_vrsn_minor: 2
 :this_prod_vrsn_majmin: {this_prod_vrsn_major}.{this_prod_vrsn_minor}
-:this_prod_vrsn_patch: 0
+:this_prod_vrsn_patch: 1
 :this_prod_vrsn: {this_prod_vrsn_majmin}.{this_prod_vrsn_patch}
 :next_prod_vrsn: 0.3.0
 :next_prod_vrsn_majmin: 0.3
@@ -461,7 +467,7 @@ Then have it consult `releasehx://config/sample` as a table of contents before u
 [[demo-setup]]
 ==== Demo Repo Setup
 
-If you want to play around with ReleaseHx before connecting it to your own Issues source via API, use the `link:{releasehx_demo_repo}[DocOps/releasehx-demo]` repository as instructed in this section.
+If you want to play around with ReleaseHx before connecting it to your own Issues source via API, use the `link:{releasehx-demo_repo_www_url}[DocOps/releasehx-demo]` repository as instructed in this section.
 
 Alternately, skip to <<issue-sources>> to begin configuring your own project/environment.
 
@@ -632,7 +638,7 @@ Out of the box, there are two issues in the `jira-customfield-note-1.1.0.json` f
 [.prompt.testable]
  rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --html --pdf
 
-For more on the demo repo, visit its README at {releasehx_demo_repo}.
+For more on the demo repo, visit its README at {releasehx-demo_repo_www_url}.
 
 [[custom-configuration]]
 ==== Custom Configuration
@@ -923,7 +929,7 @@ For *custom field-based* release notes, the entire ADF content in the custom fie
 No heading extraction is performed.
 --
 
-See link:{releasehx_demo_repo}[releasehx-demo] repository for working examples with ADF payloads and configurations.
+See link:{releasehx-demo_repo_www_url}[releasehx-demo] repository for working examples with ADF payloads and configurations.
 
 [[github-issues]]
 ==== GitHub Issues
@@ -1350,7 +1356,7 @@ When rendered, the HTML will include:
 }
 ----
 
-For examples of dark theme in action, see the demo configurations in the {releasehx_demo_repo}[releasehx-demo repository], particularly `github-dark-mode.yml` and `github-bootstrap-dark.yml`.
+For examples of dark theme in action, see the demo configurations in the {releasehx-demo_repo_www_url}[releasehx-demo repository], particularly `github-dark-mode.yml` and `github-bootstrap-dark.yml`.
 
 [[html-wrapper-control]]
 ===== HTML Wrapper Control
@@ -1954,7 +1960,7 @@ ReleaseHx comes with a complete default configuration file as well as a series o
 
 The complete link:{default-config_www}[default config file] displays default values with commented descriptions of all available properties.
 
-The various sample configurations stored in the link:{releasehx_demo_repo}/blob/main/configs/[demo repository] may be a good start toward establishing your own setup.
+The various sample configurations stored in the link:{releasehx-demo_repo_www_url}/blob/main/configs/[demo repository] may be a good start toward establishing your own setup.
 
 [[env-vars]]
 === Environment Variables in ReleaseHx
@@ -2188,7 +2194,7 @@ For example, if your GitHub issues use labels like:
 Your ReleaseHx application will need an alternate mapping because the default GitHub mapping expects native `issue_type.name` fields.
 
 An example alternate mapping for label-based GitHub type extraction can be found at:
-link:{releasehx_demo_repo}/blob/main/_mappings_/legacy-labels/github.yaml[`releasehx-demo/_mappings_/legacy-labels/github.yaml`]
+link:{releasehx-demo_repo_www_url}/blob/main/_mappings_/legacy-labels/github.yaml[`releasehx-demo/_mappings_/legacy-labels/github.yaml`]
 
 This mapping includes Ruby logic to:
 
@@ -2240,7 +2246,7 @@ To use an alternate mapping:
 
 . Test with representative payload data to ensure proper extraction
 
-The link:{releasehx_demo_repo}[demo repository] contains working examples of these alternate mappings alongside their corresponding configurations and test payloads.
+The link:{releasehx-demo_repo_www_url}[demo repository] contains working examples of these alternate mappings alongside their corresponding configurations and test payloads.
 
 [NOTE]
 ReleaseHx by default looks for a mapping file that matches the name of the API you are using.
@@ -2276,7 +2282,7 @@ Using the ReleaseHx config file, you can manipulate:
 
 Most of this can be manipulated using the following sections: <<conf_ppty_history>>, <<conf_ppty_changelog>>, <<conf_ppty_notes>>, <<conf_ppty_links>>, as well as within change-metadata config blocks, where you can alter labels, icons, and such: <<conf_ppty_types>>, <<conf_ppty_parts>>, <<conf_ppty_tags>>.
 
-The various sample configurations found in the link:{releasehx_demo_repo}/blob/main/configs/[demo repository] illustrate many of these options.
+The various sample configurations found in the link:{releasehx-demo_repo_www_url}/blob/main/configs/[demo repository] illustrate many of these options.
 
 A complete link:{default-config_www}[sample config] displays default values and commented descriptions of all available properties.
 
@@ -2550,7 +2556,7 @@ To work with ReleaseHx source, clone both repositories side by side for the most
 +
 [.prompt]
  git clone {this_proj_src_www_url}
- git clone {releasehx_demo_repo}
+ git clone {releasehx-demo_repo_www_url}
 +
 This will give you `<source_dir>/releasehx` and `<source_dir>/releasehx-demo`, side by side.
 

Rakefile

@@ -278,7 +278,7 @@ namespace :rhx do
   desc 'Publish release notes as AsciiDoc'
   task :publish, [:version] do |_t, args|
     with_rhx(args) do |config_path, config, version|
-      drafts_dir = config.dig('paths', 'drafts_dir') || 'docs/release/drafts'
+      drafts_dir = config.dig('paths', 'drafts_dir') || 'docs/_releases/drafts'
       yaml_file = File.join(drafts_dir, "#{version}.yml")
 
       unless File.exist?(yaml_file)
@@ -288,7 +288,7 @@ namespace :rhx do
       end
 
       puts "Publishing release notes for version #{version}..."
-      output_file = "docs/release/#{version}.adoc"
+      output_file = "docs/_releases/#{version}.adoc"
       cmd = "bundle exec bin/rhx #{yaml_file} --config #{config_path} --adoc #{output_file}"
       run_cmd(cmd)
       puts "✓ Successfully published release notes to #{output_file}"
@@ -354,9 +354,9 @@ end
 
 def generate_release_index
   require 'fileutils'
-  require 'yaml'
+  require 'date'
 
-  release_dir = 'docs/release'
+  release_dir = 'docs/_releases'
   output_file = 'build/docs/_release_index.adoc'
 
   # Ensure output directory exists
@@ -370,40 +370,41 @@ def generate_release_index
 
   return if release_files.empty?
 
-  # Build the index content
+  # Build the index content — all releases included inline, links are anchors
   content = []
-  content << '== Available Releases'
-  content << ''
-  content << 'Each release includes detailed notes about new features, improvements, bug fixes, and breaking changes.'
+  content << '== Release History'
   content << ''
+  content << '[cols="~,~"]'
+  content << '|==='
 
-  # List releases
+  # TOC-style list linking to anchors within this page
   release_files.each do |file|
     version = File.basename(file, '.adoc')
-    # Try to extract date from the file
-    date = extract_release_date(file) || 'TBD'
-    content << "* link:../release/#{version}[#{version}] - #{date}"
+    raw_date = extract_release_date(file)
+    date = raw_date ? Date.parse(raw_date).strftime('%-d %B, %Y') : 'TBD'
+    anchor = "release-#{version.gsub('.', '-')}"
+    content << "| <<#{anchor},#{version}>>"
+    content << "| #{date}"
   end
 
-  content << ''
-  content << '== Latest Release'
+  content << '|==='
   content << ''
 
-  # Include the latest release content
-  if release_files.any?
-    latest_file = release_files.first
-    latest_version = File.basename(latest_file, '.adoc')
-    content << "include::release/#{latest_version}.adoc[leveloffset=+1]"
+  # Include all releases inline with anchor IDs
+  release_files.each do |file|
+    version = File.basename(file, '.adoc')
+    anchor = "release-#{version.gsub('.', '-')}"
+    content << "[[#{anchor}]]"
+    content << "include::_releases/#{File.basename(file)}[leveloffset=+1]"
+    content << ''
   end
 
   # Write the file
   File.write(output_file, content.join("\n"))
 end
 
 def extract_release_date file
-  # Read first 20 lines looking for :page-date: attribute
-  File.foreach(file).first(20).each do |line|
-    return Regexp.last_match(1).strip if line =~ /:page-date:\s+(.+)$/
-  end
-  nil
+  require 'asciidoctor'
+  doc = Asciidoctor.load_file file, safe: :safe, parse_header_only: true
+  doc.attr 'page-date'
 end

docs/_config.yml

@@ -1,6 +1,7 @@
 title: ReleaseHx Documentation
 theme: just-the-docs
 baseurl: /
+future: true
 
 plugins:
   - jekyll-asciidoc
@@ -31,7 +32,8 @@ exclude:
   - manpage.adoc
   - jekyll/
   - payloads/
-  - release/
+  - _releases/drafts
+  - _releases/payloads
   - yard/
   - release-procedure.adoc
 

docs/release/0.1.2.adoc → docs/_releases/0.1.2.adoc

@@ -2,7 +2,6 @@
 :page-title: Release History for 0.1.2
 :page-version: 0.1.2
 :page-date: 2026-01-30
-:page-permalink: /docs/releases/0.1.2
 = Release History -- 0.1.2 - 2026-01-30
 
 

docs/release/0.2.0.adoc → docs/_releases/0.2.0.adoc

@@ -2,7 +2,6 @@
 :page-title: Release History for 0.2.0
 :page-version: 0.2.0
 :page-date: 2026-05-27
-:page-permalink: /docs/releases/0.2.0
 = Release History -- 0.2.0 - 2026-05-27
 
 

docs/_releases/0.2.1.adoc

@@ -0,0 +1,52 @@
+:icons: font
+:page-title: Release History for 0.2.1
+:page-version: 0.2.1
+:page-date: 2026-05-28
+= Release History -- 0.2.1 - 2026-05-28
+
+
+[.release-section]
+== What's Changed
+
+
+Summary of all changes in this release.
+
+
+[.changelog-section]
+
+
+=== Fixed
+
+
+[.change-entry]
+* Fixed broken YAML output when changes contain notes
+ +
+xref:note-0_2_1-liquid-template[NOTE]
+
+
+== Release Notes
+
+
+Detailed descriptions of notable changes.
+
+
+[.notes-section]
+
+
+=== Fixed
+[[note-0_2_1-liquid-template]]
+[.release-note]
+--
+The `rhyml-change.yaml.liquid` template contained four defects introduced in 0.2.0 that caused `Liquid error: internal` followed by a YAML `SyntaxError` whenever a change entry included a release note.
+
+Specifically:
+
+* `_note` was referenced as a variable but never defined (should be `change.note`)
+* `summ:` key was output at column 0 instead of the required 2-space indent
+* `part:` key was indented 4 spaces instead of 2
+* `.strip` was applied as a Liquid filter, which is not valid Liquid syntax
+
+All four are corrected.
+Any configuration that includes `conversions.note` (Jira, GitHub, GitLab, or RHYML sources with note content) is affected by this bug and should upgrade to 0.2.1.
+
+--