Commits on Mar 30, 2026

1. Add AI-friendly meta tags and enhanced structured data (#371) …

   * Add AI-friendly meta tags and structured data
   
   ## Changes
   
   ### head-meta.hbs
   - Add AI-friendly robots meta tag for production pages
   - Include max-snippet:-1, max-image-preview:large directives
   - Add ai-content-declaration meta tag
   - Keep noindex for prereleases and previews
   
   ### head-structured-data.hbs
   - Add TechArticle schema.org type for individual pages
   - Include page title, description, and URL
   - Link to organization and website schemas
   - Add software application context for component pages
   
   ## Benefits
   - Better AI crawler understanding of page content
   - Improved discoverability by AI search engines
   - Richer metadata for AI-powered tools
   - Standards-compliant structured data
   
   * Update applicationCategory to Agentic Data Plane
   
   * Remove non-standard ai-content-declaration meta tag
   
   After research, ai-content-declaration is not a recognized standard.
   The industry uses C2PA metadata instead of HTML meta tags for
   AI content declarations. Keeping only the official Google robots
   meta tags (max-snippet, max-image-preview, max-video-preview).
   
   * Fix JSON escaping and date metadata in structured data
   
   - Escape description field properly: use {{...}} instead of {{{...}}}
     to prevent JSON breakage from quotes/newlines in descriptions
   - Use content-level dates for datePublished/dateModified: check
     docdatetime and revdate attributes before falling back to build-time
     iso-date so dates reflect actual content timestamps
   
   * Fix markdown-url helper to generate proper .md URLs
   
   Change indexify URLs from /path/index.md to /path.md to match
   the new markdown export structure. This fixes "Copy as Markdown"
   and "View as plain text" buttons to use correct URLs.
   
   * Enhance TechArticle schema with additional fields
   
   Add richer structured data for better search engine understanding:
   - alternativeHeadline: navtitle if different from title
   - keywords: from page keywords or categories attributes
   - genre: from page-role (tutorial, how-to, concept, reference)
   - dependencies: from page-prerequisites attribute
   - datePublished: use page-release-date first (when page created),
     then fall back to docdatetime, revdate, iso-date
   - dateModified: use docdatetime (last updated), then revdate,
     iso-date
   
   This provides search engines with more context about documentation
   pages while only using data already in page attributes.
   
   * Update structured data to use Git-based dates
   
   - Use git-created-date for datePublished with page-release-date fallback
   - Use git-modified-date for dateModified with page-release-date fallback
   - Replaces build-time date fallbacks with accurate Git commit history
   - Works with add-git-dates extension in docs-extensions-and-macros
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Add 10s timeout to Bloblang grammar HTTP requests to prevent CI hangs
   
   The generate:bloblang-grammar task was hanging indefinitely in GitHub Actions
   when fetching from GitHub/docs.redpanda.com due to network issues.
   
   Added timeout option and timeout event handler to fail fast instead of hanging
   for hours. This allows fallback versions to be tried and builds to complete.
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Add Handlebars helpers to access Git dates from contentCatalog
   
   Created git-created-date and git-modified-date helpers that query
   contentCatalog to access page.asciidoc.attributes where the
   add-git-dates extension stores Git commit dates.
   
   Updated structured data template to use these helpers instead of
   directly accessing page.attributes.git-created-date, which don't
   exist at template render time.
   
   This fixes the issue where datePublished and dateModified were
   showing today's date instead of actual Git commit dates.
   
   Also added page-has-markdown attribute to preview page for testing
   the "Page options" dropdown.
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Address structured data and URL handling issues from PR review
   
   Fixed all issues raised by Michele in PR #371:
   
   1. **Security: JSON string safety** (head-structured-data.hbs)
      - Created json-safe helper to escape dynamic values in JSON-LD
      - Escapes backslashes, quotes, and </script> tags
      - Prevents invalid JSON and script breakout vulnerabilities
      - Applied to all dynamic fields (title, description, keywords, etc.)
   
   2. **Code quality: Hardcoded applicationCategory** (head-structured-data.hbs)
      - Removed hardcoded "Agentic Data Plane" value
      - Now conditional on page.component.asciidoc.attributes.application-category
      - Allows per-component customization instead of global value
   
   3. **Code quality: Build-time date fallback** (head-structured-data.hbs)
      - Removed {{iso-date}} fallback for datePublished/dateModified
      - Pages without explicit dates now omit the field entirely
      - Prevents misleading "published at build time" metadata
   
   4. **Bug fix: Root path edge case** (markdown-url.js)
      - Added guard for url === '/' to return '/index.md'
      - Prevents invalid '.md' output from url.slice(0, -1)
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Revert to hardcoded 'Agentic Data Plane' applicationCategory
   
   Business decision: Keep applicationCategory as 'Agentic Data Plane' across
   all documentation to increase visibility for this new category.
   
   This reverts the conditional logic added in the previous commit while
   keeping the json-safe helper for proper escaping.
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Apply suggestion from @JakeSCahill
   
   * Apply suggestion from @JakeSCahill
   
   * Fix structured data attribute access and correct topic type field
   
   Changes:
   - Create page-attribute helper to properly access AsciiDoc document attributes
     via contentCatalog query (page.attributes.XXX doesn't work for doc attributes)
   - Update head-structured-data.hbs to use page-attribute helper for all
     AsciiDoc document attributes (description, keywords, page-categories,
     page-release-date, page-prerequisites, page-topic-type)
   - Change from page-role to page-topic-type (correct attribute name)
   - Use consistent {{#with}} pattern for optional fields
   
   This fixes the issue where AsciiDoc document attributes weren't rendering
   in structured data JSON-LD because they need to be accessed through
   contentCatalog, not directly from the page object.
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Fix structured data helpers for git dates, descriptions, and HTML entities
   
   Bug fixes:
   - git-created-date.js: Query page-git-created-date (with page- prefix)
   - git-modified-date.js: Query page-git-modified-date (with page- prefix)
   - page-attribute.js: Fall back to page.description/page.keywords for intrinsic attributes
   - json-safe.js: Decode HTML entities before JSON escaping
   
   The page- prefix is required because Antora only exposes attributes with
   this prefix to page.attributes in the UI model. The extension now sets
   page-git-created-date which becomes accessible as page.attributes['git-created-date'].
   
   HTML entity decoding handles:
   - Named entities (&amp;, &rsquo;, &mdash;, etc.)
   - Numeric decimal entities (&#8217;)
   - Numeric hex entities (&#x2019;)
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Remove redundant git date helpers, use page.attributes directly
   
   Git dates are available as page.attributes.git-created-date and
   page.attributes.git-modified-date directly since the extension
   uses the page- prefix. No need for contentCatalog.getById() lookup.
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Optimize nav helpers with O(1) URL lookups
   
   Changed is-beta-feature, is-limited-availability-feature, and
   is-enterprise helpers from O(n) per-lookup to O(1) by building
   a URL->attribute Map once per component.
   
   Before: Each nav item triggered a linear scan of all pages
   After: Single scan per component, then constant-time lookups
   
   Benchmark: ~45% faster builds (3:00 -> 1:45)
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Enhance TechArticle schema with additional properties
   
   Added schema.org/TechArticle properties:
   - learningResourceType: Maps from page-topic-type
   - audience: Maps from personas attribute
   - teaches: Maps from learning-objective-* attributes
   - version: Component version
   - articleSection: Module name
   - isAccessibleForFree: true
   
   These properties improve SEO and AI discoverability by providing
   richer semantic metadata about documentation content.
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Remove duplicate genre field from TechArticle schema
   
   genre is meant for creative works (comedy, drama, etc.)
   learningResourceType is the correct property for documentation types
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Trigger CI rebuild
   
   * Use direct page.attributes access, reduce helper calls
   
   - Use page.description and page.keywords directly (intrinsic)
   - Use page.attributes.* for page-prefixed attributes
   - Only use page-attribute helper for non-prefixed attrs:
     - personas
     - learning-objective-*
   
   Reduces contentCatalog.getById() calls from 8 to 4 per page.
   
   Co-Authored-By: Claude Opus 4.5 <[email protected]>
   
   * Add FAQ structured data to schema.org JSON-LD
   
   Includes FAQPage in @graph when page-faq-json-ld attribute exists.
   
   Works with docs-extensions-and-macros FAQ extension that:
   - Auto-extracts Q&A from page sections
   - Supports manual overrides
   - Generates schema.org compliant FAQPage
   
   Example output:
   {
     "@type": "FAQPage",
     "mainEntity": [
       {
         "@type": "Question",
         "name": "How do I install?",
         "acceptedAnswer": {
           "@type": "Answer",
           "text": "Install using..."
         },
         "url": "https://docs.redpanda.com/page#section"
       }
     ]
   }
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Generate FAQPage JSON-LD from structured attributes
   
   Update head-structured-data.hbs to generate FAQPage JSON-LD structure
   from page attributes instead of dumping pre-generated JSON. This properly
   separates concerns between the extension (data) and template (presentation).
   
   Changes:
   - Generate JSON-LD from page.attributes.has-faqs and page.attributes.faqs
   - Use @root helper for proper Handlebars context in nested loops
   - Construct FAQ URLs from site.url + page.url + anchor
   - Handle optional anchors with conditional URL generation
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   * Optimize validate-build workflow with caching
   
   Speed up the validate-build CI job by adding multiple caching layers:
   
   1. Go module caching - Cache Go dependencies for WASM build
   2. npm caching - Cache node_modules to speed up npm ci
   3. Generated files caching - Cache Bloblang grammar and WASM files
      to avoid regenerating them on every run
   
   Also switched from npm i to npm ci for faster, more deterministic
   installs in CI.
   
   Expected improvements:
   - Cold cache: ~3-6 minutes (unchanged)
   - Warm cache: ~1-2 minutes (50-70% faster)
   
   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
   
   ---------
   
   Co-authored-by: Claude Sonnet 4.5 <[email protected]>

   

   JakeSCahill and claude authored Mar 30, 2026
   Configuration menu

   • View commit details
   • Copy full SHA for c694140
   • Browse repository at this point

   Copy the full SHA

   c694140 View commit details

   Browse the repository at this point in the history