Page Metadata Format

Overview

Redis documentation pages include AI-friendly metadata that helps AI agents understand page structure, content, and navigation. This metadata is automatically generated during the Hugo build process and embedded in both HTML and Markdown output formats.

Metadata Structure

Core Fields (Required)

• title (string, required): The page title
• description (string, required): A brief description of the page content

Navigation Fields

• tableOfContents (object): Hierarchical structure of page sections
  • sections (array): Array of top-level sections
    • id (string): Unique identifier matching the heading anchor ID
    • title (string): Display title of the section
    • children (array, optional): Nested subsections with the same structure

Categorization Fields

• categories (array): Category tags for the page (e.g., ["docs", "develop", "stack"])
• scope (string): Scope or domain of the page content
• topics (array): Related topics
• relatedPages (array): Links to related documentation pages

Command Reference Fields (for /commands/ pages)

• arguments (array): Command arguments
• syntax_fmt (string): Command syntax format
• complexity (string): Time complexity of the command
• group (string): Command group
• command_flags (array): Flags associated with the command
• acl_categories (array): ACL categories for the command
• since (string): Redis version when the command was introduced
• arity (integer): Number of arguments the command accepts
• key_specs (array): Key specifications for the command

Code Examples Fields

• codeExamples (array): Array of code examples found on the page
  • id (string): Unique identifier for the code example
  • description (string, optional): Description of what the code example demonstrates
  • difficulty (string, optional): Difficulty level - one of "beginner", "intermediate", "advanced" (defaults to "beginner")
  • buildsUpon (array, optional): Array of example step IDs that this example builds upon
    • Used to indicate learning progression and dependencies between examples
    • Example: ["set_get"] means this example requires understanding the "set_get" example first
    • Multiple dependencies: ["lpush_rpush", "lpop_rpop"] indicates this example builds on both
  • codetabsId (string, optional): DOM element ID of the codetabs container
  • languages (array): Array of language-specific code variants
    • id (string): Display name of the language (e.g., "Python", "Node.js", "Java-Sync")
    • panelId (string): DOM element ID of the code panel for this language
    • langId (string): Stable language identifier (e.g., "python", "javascript", "java")
    • clientId (string): Stable client library identifier (e.g., "redis-py", "node-redis", "lettuce")
    • clientName (string): Human-readable client library name (e.g., "redis-py", "Jedis", "Lettuce")

Metadata Location Fields

• location (string): Where this metadata is located in the HTML document
  • "head" - Metadata is in a <script> tag in the document head (primary copy)
  • "body" - Metadata is in a hidden <div> in the document body (fallback copy)
• duplicateOf (string, optional): If this metadata is a duplicate of another instance, this field indicates the location of the primary copy
  • Format: "location:selector" (e.g., "head:data-ai-metadata")
  • Only present in duplicate instances

Example

Basic Page Metadata (Head)

{
  "title": "Redis data types",
  "description": "Overview of data types supported by Redis",
  "location": "head",
  "categories": ["docs", "develop", "stack", "oss"],
  "tableOfContents": {
    "sections": [
      {
        "id": "data-types",
        "title": "Data types",
        "children": [
          {"id": "strings", "title": "Strings"},
          {"id": "lists", "title": "Lists"},
          {"id": "sets", "title": "Sets"}
        ]
      },
      {
        "id": "time-series",
        "title": "Time series"
      }
    ]
  }
}

Page with Code Examples

{
  "title": "String operations",
  "description": "Learn how to work with string values in Redis",
  "location": "head",
  "categories": ["docs", "develop"],
  "codeExamples": [
    {
      "id": "set_get",
      "description": "Foundational: Set and retrieve string values using SET and GET",
      "difficulty": "beginner",
      "codetabsId": "set_get_example",
      "languages": [
        {
          "id": "Python",
          "panelId": "set_get_python",
          "langId": "python",
          "clientId": "redis-py",
          "clientName": "redis-py"
        }
      ]
    },
    {
      "id": "setnx_xx",
      "description": "Conditional SET operations: Use NX and XX options for atomic compare-and-set",
      "difficulty": "intermediate",
      "buildsUpon": ["set_get"],
      "codetabsId": "setnx_xx_example",
      "languages": [
        {
          "id": "Python",
          "panelId": "setnx_xx_python",
          "langId": "python",
          "clientId": "redis-py",
          "clientName": "redis-py"
        }
      ]
    },
    {
      "id": "mset",
      "description": "Set and retrieve multiple values using MSET and MGET",
      "buildsUpon": ["set_get"],
      "codetabsId": "mset_example",
      "languages": [
        {
          "id": "Python",
          "panelId": "mset_python",
          "langId": "python",
          "clientId": "redis-py",
          "clientName": "redis-py"
        }
      ]
    }
  ]
}

Duplicate Metadata (Body)

{
  "title": "SET command",
  "description": "Set the string value of a key",
  "location": "body",
  "duplicateOf": "head:data-ai-metadata",
  "categories": ["docs", "commands"],
  "codeExamples": [...]
}

Embedding

HTML Output

Metadata is embedded in two locations for redundancy and accessibility:

Primary: Head (Script Tag)

<head>
  <script type="application/json" data-ai-metadata>
  {
    "title": "...",
    "description": "...",
    "location": "head",
    ...
  }
  </script>
</head>

Use this location for:

• Static analysis and extraction
• AI agent processing
• Schema validation
• Caching (primary copy)

Fallback: Body (Hidden Div)

<body>
  <div hidden data-redis-metadata="page">
  {
    "title": "...",
    "description": "...",
    "location": "body",
    "duplicateOf": "head:data-ai-metadata",
    ...
  }
  </div>
</body>

Use this location for:

• DOM-based extraction (when JavaScript is available)
• Fallback access if head metadata is unavailable
• Runtime access from page scripts

Note: The duplicateOf field indicates this is a duplicate of the head version. Prefer the head version when available.

Markdown Output (.html.md)

Metadata is embedded in a JSON code block at the top of the page:

```json metadata
{...metadata...}
```

Per-Codetabs Metadata

In addition to page-level metadata, each codetabs container includes a data-codetabs-meta attribute with language/client mappings:

<div class="codetabs" id="set_example" data-codetabs-meta='{"redis-cli": {"language": "redis-cli", "client": "redis-cli"}, "Python": {"language": "python", "client": "redis-py"}, "Node.js": {"language": "javascript", "client": "node-redis"}, ...}'>
  <!-- codetabs panels -->
</div>

This metadata provides:

• Single source of truth for each codetabs block
• Runtime access to language/client mappings
• Zero duplication - not repeated on every panel
• AI agent friendly - direct mapping from tab → language → client

Usage Example

// Get the codetabs metadata
const codetabsDiv = document.getElementById('set_example');
const metaStr = codetabsDiv.getAttribute('data-codetabs-meta');
const metadata = JSON.parse(metaStr);

// Find Python's client library
const pythonMeta = metadata['Python'];
console.log(pythonMeta.language); // "python"
console.log(pythonMeta.client);   // "redis-py"

Auto-Generation

The tableOfContents is automatically generated from page headings using Hugo's built-in .TableOfContents method. The HTML structure is converted to JSON using regex substitutions in the layouts/partials/toc-json-regex.html partial.

The codeExamples array is automatically generated from codetabs blocks found on the page using the layouts/partials/code-examples-json.html partial.

Schema

The complete JSON schema is available at: https://redis.io/schemas/page-metadata.json

This schema enables:

• Validation of metadata structure
• IDE autocomplete and type checking
• AI agent understanding of page structure
• Consistent metadata across all pages

Metadata Precedence

When both head and body metadata are available:

1. Prefer head metadata - It's the primary copy and more efficient to access
2. Use body metadata as fallback - If head is unavailable or inaccessible
3. Check duplicateOf field - If present, indicates this is a duplicate of another instance

Notes

• The in-page JSON metadata does not include a $schema reference. The schema is available separately for validation and documentation purposes.
• The metadata is auto-generated during the Hugo build process and does not require manual maintenance.
• Both head and body metadata contain identical content (except for location and duplicateOf fields)
• The location field helps downstream tooling understand which copy they're accessing
• The duplicateOf field enables smart caching and fallback logic in AI agents and tools