--- ---

Fix Jekyll-AsciiDoc Build Errors

Analyzing and addressing Asciidoctor errors that surface in Jekyll build operations

When Asciidoctor errors are encountered during the conversion stage of a Jekyll build operation, use this procedure to clarify and fix them.

Procedure Overview

PREREQUISITE

This procedure requires the docopslab-dev utility.

  1. Perform a basic Jekyll build that writes verbose output to a local file.

    Example with config option
    bundle exec jekyll build --verbose --config configs/jekyll.yml > .agent/scratch/jekyll-build.log 2>&1

    Note the 2>&1 at the end of the command, which ensures that both standard output and error messages are captured in the log file.

  2. Run the analysis task on the exported file.

    bundle exec rake 'labdev:lint:logs[jekyll-asciidoc,.agent/scratch/jekyll-build.log]'

  3. Open the YAML file relayed in the response message (example: Jekyll AsciiDoc issues report generated: .agent/reports/jekyll-asciidoc-issues-20251214_085323.yml).

  4. Follow the instructions in the report to address the issues found.

The Error Report

The report is a YAML file that lists the errors associated with their actual locations in the AsciiDoc source.

The report contains instructions so that it may be fed in its entirety to an LLM assistant to address the errors.

Default instructions
# When processing this file, focus on the relationship between
#  the 'file' and 'with' properties:
#
# 1. 'file' = The Jekyll file that includes/references the problem
# 2. 'with' = The file that contains the actual structural issue
# 3. 'kind' types and typical fixes:
#    - include_file_not_found: Create missing files or fix paths
#    - section_title_out_of_sequence: Adjust heading levels or leveloffset
#    - unterminated_listing_block: Close code blocks with proper delimiters
#    - invalid_reference: Fix broken cross-references
#    - missing_attribute: Define the attribute locally or via included settings
#
# Common patterns:
# - Multiple files referencing the same with file suggest the issue is in the shared file
# - #excerpt errors usually indicate an include is embedded in the excerpted text
# - Section title sequence errors often need leveloffset adjustments in include directives
# - Missing files may need creation or path corrections