v0.3.0: Sync/Cast _liquid preamble block support

- Add `_liquid` block to prime templates: defines Liquid variables
  shared across all canonical block renders during sync.
- Strip `_skip` and `_liquid` meta-blocks from output during init.
- Expand cast_spec and add liquid_preamble_spec (263 examples, 0 failures).
- Update README docs for `_liquid` preamble and `_skip` block behaviors.
- Add limited Markdown skimming to SourceSkim.
- Create skim_markup.rb to replace skim_asciidoc.rb (deprecated)
- Bump version: 0.2.1 -> 0.3.0.

Author: briandominick

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    asciisourcerer (0.2.1)
+    asciisourcerer (0.3.0)
       asciidoctor (~> 2.0)
       asciidoctor-html5s (~> 0.5)
       jekyll (~> 4.4)

README.adoc

@@ -37,11 +37,11 @@ endif::[]
 :this_prod_name: {this_proj_name}
 // end::universal-settings[]
 :this_prod_vrsn_major: 0
-:this_prod_vrsn_minor: 2
+:this_prod_vrsn_minor: 3
 :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.3.0
+:next_prod_vrsn: 0.4.0
 // end::global-settings[]
 :toc: macro
 :toclevels: 4
@@ -99,7 +99,7 @@ AsciiDoc-to-Markdown conversion::
 Convert AsciiDoc documents to Markdown for agentic consumption, with a focus on preserving semantic structure and document frontmatter.
 See <<markdowngrade>>.
 
-AsciiDoc source inspection::
+AsciiDoc and Markdown source inspection::
 Skim AsciiDoc documents to produce machine-oriented outlines of sections, code blocks, tables, and other semantic elements for tooling and agent consumption.
 See <<source-skim>>.
 
@@ -300,20 +300,21 @@ Override it per call with the `canonical_prefix:` keyword argument.
 Canonical blocks use AsciiDoc-style `tag::`/`end::` markers embedded inside comments.
 Three comment styles are recognized so the same prime can manage files of any type:
 
-[cols="3m,5m",options="header"]
+[cols="3,5m",options="header"]
 |===
 | Style | Example
-| HTML / Markdown comment
-| <!-- tag::universal-intro[] -->
-| AsciiDoc line comment
+| HTML / Markdown
+| <!-- tag::universal-intro[] +++-->+++
+| AsciiDoc / JavaScript
 | // tag::universal-intro[]
-| Shell / Ruby / YAML comment
+| Shell / Ruby / YAML / INI
 | # tag::universal-intro[]
 |===
 
-The trailing `[]` is optional in all three styles.
+A block with tag names beginning with the configured prefix (default `universal-`) is treated as canonical and managed by Sync/Cast.
+
+Any block wrapped in `tag::_skip[]` and `end::_skip[]` will _not_ be passed from prime to target even during the init operation.
 
-A tag whose name begins with the configured prefix (default `universal-`) is treated as canonical and managed by Sync/Cast.
 All other tagged regions in a target file are left entirely alone, and their presence beside a canonical block never triggers a warning.
 
 [[sync-cast-operations]]
@@ -322,6 +323,8 @@ All other tagged regions in a target file are left entirely alone, and their pre
 init::
 One-time operation that renders the prime template (the whole file, not just canonical blocks) through Liquid and writes the result as a new target file.
 Use this to bootstrap a repo-local copy of a project template.
++
+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.
@@ -354,6 +357,18 @@ This is {{ data.variables.name }} version {{ data.variables.version }}.
 <!-- end::universal-intro[] -->
 ----
 
+Since each block is rendered independently, variables cannot reference content from other blocks.
+Use a segment wrapped in `_liquid` tags to set variables inline that will be used across all subsequent blocks.
+This `_liquid` segment only has access to variables passed into the main render call, not to any content blocks.
+
+[source,markdown]
+----
+<!-- tag::_liquid -->
+{%- assign name = data.variables.this_proj_name | default: 'Unknown Project' %}
+{%- assign version = data.variables.this_prod_vrsn | default: '0.0.0' %}
+<!-- end::_liquid -->
+----
+
 [[sync-cast-bootstrap]]
 ==== Bootstrap example
 
@@ -362,7 +377,7 @@ This is {{ data.variables.name }} version {{ data.variables.version }}.
 Sourcerer::Sync.init(
   'templates/AGENTS.markdown',
   'AGENTS.md',
-  data: { 'project' => 'my-gem', 'org' => 'DocOps' }
+  data: { 'project' => 'my-gem', 'org' => 'ACME Co' }
 )
 ----
 
@@ -421,10 +436,14 @@ Schema-aware filters (including SGYML-specific classification filters) should be
 [[source-skim]]
 === SourceSkim
 
-`Sourcerer::SourceSkim` generates machine-oriented _skims_ of AsciiDoc source documents.
+`Sourcerer::SourceSkim` generates machine-oriented _skims_ of AsciiDoc and Markdown source documents.
 
-A skim is a structured, JSON/YAML-ready outline of selected source elements:
+A skim is a structured, JSON/YAML-ready outline of selected source elements.
+AsciiDoc skims include:
 sections, code blocks, definition lists, tables, images, and more.
+
+Markdown skims include only sections and frontmatter, since other semantic elements are not reliably parseable in Markdown's freeform syntax.
+
 Skims are intended to help tooling and agents inspect documentation source without ingesting full file contents.
 
 .Example: Skim a file for sections and code blocks
@@ -441,13 +460,17 @@ skim = Sourcerer::SourceSkim.skim_file('docs/install.adoc', categories: [:code_b
 
 # Skim inline content
 skim = Sourcerer::SourceSkim.skim_string(raw_adoc_content)
+
+# Skim Markdown file with flat sections only
+skim = Sourcerer::SourceSkim.skim_file('README.md', forms: [:flat])
 ----
 
 Section shapes::
 Pass `forms: [:tree]` (default), `forms: [:flat]`, or both.
 Tree shape preserves nesting; flat shape adds `parent_id` and expresses child section IDs as an array.
 
 Categories::
+(AsciiDoc skims only.)
 Default output includes `attributes_custom`, `definition_lists`, `code_blocks`, `literal_blocks`, `examples`, `sidebars`, `tables`, and `images`.
 Opt-in only (excluded by default): `attributes_builtin`, `admonitions`, `quotes`.
 Pass `categories:` with an explicit array of symbols to restrict or expand output.
@@ -457,6 +480,7 @@ The skim output schema is at `specs/data/asciidoc-source-skim.schema.json` and a
 
 [[skim-asciidoctor-extension]]
 ==== Asciidoctor extension
+
 `Sourcerer::SourceSkim::TreeProcessorExtension` integrates SourceSkim into Asciidoctor parsing pipelines.
 It stores the result as the `source-skim-result` document attribute and reads `source-skim-forms` and `source-skim-categories` document attributes for per-document configuration.
 
@@ -620,9 +644,10 @@ Use them as examples or utilities but do not rely on them in production.
 
 Current scripts include: ::
 
-link:https://github.com/DocOps/asciisourcerer/blob/main/scripts/skim_asciidoc.rb[`skim_asciidoc.rb`]:::
-For AsciiDoc source inspection.
-Generates YAML or JSON versions of `Sourcerer::SourceSkim` output for a given AsciiDoc document or collection of documents.
+link:https://github.com/DocOps/asciisourcerer/blob/main/scripts/skim_markup.rb[`skim_markup.rb`]:::
+(Formerly `skim_asciidoc.rb`.)
+For AsciiDoc/Markdown source inspection.
+Generates YAML or JSON versions of `Sourcerer::SourceSkim` output for a given AsciiDoc document, Markdown file, or collection of such.
 
 link:https://github.com/DocOps/asciisourcerer/blob/main/scripts/mark_down_grade.rb[`mark_down_grade.rb`]:::
 For AsciiDoc-to-Markdown conversion.
@@ -655,14 +680,14 @@ For each script you wish to use:
 +
 .Example: writes current GH copy to a local `scripts/` path.
 [.prompt]
- curl -o scripts/skim_asciidoc.rb https://raw.githubusercontent.com/DocOps/asciisourcerer/refs/heads/main/scripts/skim_asciidoc.rb
+ curl -o scripts/skim_markup.rb https://raw.githubusercontent.com/DocOps/asciisourcerer/refs/heads/main/scripts/skim_markup.rb
 +
 Change `-o scripts/` to wherever you wish to save the script locally.
 
 . Run the script.
 +
 [.prompt]
- bundle exec ruby scripts/skim_asciidoc.rb --help
+ bundle exec ruby scripts/skim_markup.rb --help
 
 
 [[development]]

lib/sourcerer.rb

@@ -17,11 +17,18 @@
 # Requiring `sourcerer` also makes adjacent public constants (for example,
 # `Sourcerer::Builder`) available to downstream callers.
 module Sourcerer
+  # File extensions recognised as Markdown source files.
+  MARKDOWN_EXTS  = %w[.md .markdown].freeze
+
+  # File extensions recognised as AsciiDoc source files.
+  ASCIIDOC_EXTS  = %w[.adoc .asciidoc .asc .ad].freeze
+
   autoload :AttributesFilter, 'sourcerer/attributes_filter'
-  autoload :Jekyll, 'sourcerer/jekyll'
-  autoload :MarkDownGrade, 'sourcerer/mark_down_grade'
-  autoload :SourceSkim, 'sourcerer/source_skim'
-  autoload :Sync, 'sourcerer/sync'
+  autoload :YamlFrontmatter,     'sourcerer/yaml_frontmatter'
+  autoload :Jekyll,              'sourcerer/jekyll'
+  autoload :MarkDownGrade,       'sourcerer/mark_down_grade'
+  autoload :SourceSkim,          'sourcerer/source_skim'
+  autoload :Sync,                'sourcerer/sync'
 
   DEPRECATED_FACADE_METHODS = {
     # DO NOT add new public methods to this surface

lib/sourcerer/asciidoc.rb

@@ -4,6 +4,7 @@
 require 'fileutils'
 require 'yaml'
 require 'cgi'
+require_relative 'yaml_frontmatter'
 
 module Sourcerer
   # AsciiDoc-focused primitives for attribute loading, region extraction,
@@ -35,7 +36,7 @@ module Sourcerer
   #
   # @see https://asciidoctor.org/ Asciidoctor Documentation
   module AsciiDoc
-    YAML_FRONTMATTER_REGEXP = /\A(---\s*\n.*?\n)(---\s*\n?)/m
+    YAML_FRONTMATTER_REGEXP = Sourcerer::YamlFrontmatter::REGEXP
     YAML_FRONT_MATTER_REGEXP = YAML_FRONTMATTER_REGEXP
     PAGE_ATTRIBUTE_PREFIX = 'page-'
 
@@ -327,22 +328,15 @@ def self.extract_page_attributes document_attributes
     # @param source_text [String]
     # @return [Hash]
     def self.extract_yaml_frontmatter source_text
-      match = source_text.match(YAML_FRONTMATTER_REGEXP)
-      return {} unless match
-
-      frontmatter_payload = match[1].sub(/\A---\s*\n/, '')
-      parsed = YAML.safe_load(frontmatter_payload, aliases: true)
-      parsed.is_a?(Hash) ? parsed : {}
-    rescue Psych::SyntaxError
-      {}
+      Sourcerer::YamlFrontmatter.extract(source_text)
     end
 
     # Remove leading YAML front matter fence block from AsciiDoc source.
     #
     # @param source_text [String]
     # @return [String]
     def self.strip_yaml_frontmatter source_text
-      source_text.sub(YAML_FRONTMATTER_REGEXP, '')
+      Sourcerer::YamlFrontmatter.strip(source_text)
     end
 
     # Compatibility alias.
@@ -483,5 +477,65 @@ def self.ensure_document_title html_body, doctitle
                          :normalize_extract_tags,
                          :collect_tagged_content,
                          :normalize_mark_down_grade_options
+
+    # Utilities for filtering and partitioning Asciidoctor document attributes.
+    #
+    # Separates user-defined ("custom") attributes from those injected by
+    # Asciidoctor at parse time ("built-in").
+    #
+    # @example
+    #   custom  = Sourcerer::AsciiDoc::AttributesFilter.user_attributes(doc)
+    #   builtin = Sourcerer::AsciiDoc::AttributesFilter.builtin_attributes(doc)
+    module AttributesFilter
+      # Attribute keys injected by Asciidoctor at parse time.
+      BUILTIN_ATTR_KEYS = (Asciidoctor::DEFAULT_ATTRIBUTES.keys + %w[
+        asciidoctor asciidoctor-version
+        attribute-missing attribute-undefined
+        authorcount
+        docdate docdatetime docdir docfile docfilesuffix docname doctime doctitle doctype docyear
+        embedded
+        htmlsyntax
+        iconsdir
+        localdate localdatetime localtime localyear
+        max-include-depth
+        notitle
+        outfilesuffix
+        stylesdir
+        toc-position
+        user-home
+      ]).freeze
+
+      BUILTIN_ATTR_PATTERNS = [
+        /^backend(-|$)/,
+        /^basebackend(-|$)/,
+        /^doctype-/,
+        /^filetype(-|$)/,
+        /^safe-mode-/
+      ].freeze
+
+      module_function
+
+      # Returns user-defined attributes, excluding Asciidoctor built-ins.
+      #
+      # @param doc [Asciidoctor::Document]
+      # @return [Hash{String => String}]
+      def user_attributes doc
+        doc.attributes.reject do |k, _|
+          BUILTIN_ATTR_KEYS.include?(k) ||
+            BUILTIN_ATTR_PATTERNS.any? { |pat| pat.match?(k) }
+        end
+      end
+
+      # Returns built-in Asciidoctor attributes injected at parse time.
+      #
+      # @param doc [Asciidoctor::Document]
+      # @return [Hash{String => String}]
+      def builtin_attributes doc
+        doc.attributes.select do |k, _|
+          BUILTIN_ATTR_KEYS.include?(k) ||
+            BUILTIN_ATTR_PATTERNS.any? { |pat| pat.match?(k) }
+        end
+      end
+    end
   end
 end