Skip to content

HIERARCHY_FORMAT.md

Latest commit

 

History

History
260 lines (198 loc) · 7.41 KB

HIERARCHY_FORMAT.md

File metadata and controls

260 lines (198 loc) · 7.41 KB

Hierarchy Format Guide

This document describes the YAML-based format for representing hierarchies (class inheritance, filesystem trees, etc.) in Redis documentation.

Overview

Hierarchies are written in YAML format within a code block with the language identifier hierarchy. The render hook preserves the YAML source for AI agents while JavaScript generates a visual diagram for users.

Basic Syntax

Simple Hierarchy

Parent:
    Child1:
    Child2:
        Grandchild1:
        Grandchild2:

This represents:

Parent
├── Child1
├── Child2
│   ├── Grandchild1
│   └── Grandchild2

Quoted Names

Use quotes for names containing special characters (spaces, punctuation, etc.):

"Top-level folder":
    "file1.js":
    "file2.png":
    "Inner folder":
        "file3.jpg":

This is especially important for:

  • Filenames with extensions (.js, .png, etc.)
  • Names with spaces
  • Names with hyphens or other punctuation

Metadata

Add metadata to any item using the special _meta key:

"Exception":
    _meta:
        description: "Base exception class"
    "RuntimeException":
    "IOException":

Currently supported metadata fields:

  • description: A brief description of the item (displayed as italic text after the item name)
  • link: URL or relative path to make the item clickable (works in both SVG diagrams and AI agent processing)
  • ellipsis: Boolean indicating this is a placeholder for omitted items

Links

Add a link field to make items clickable:

"Documentation":
    _meta:
        link: "https://example.com/docs"
    "Getting Started":
        _meta:
            link: "./getting-started.md"
    "API Reference":
        _meta:
            link: "./api-reference.md"

The link field:

  • Works with both absolute URLs and relative paths
  • Makes the item clickable in SVG diagrams (for users)
  • Provides navigation information for AI agents
  • Can be combined with description for additional context

Ellipsis (Omitted Items)

Use an ellipsis item to indicate that some items are not shown:

"RedisError":
    "ConnectionError":
    "ResponseError":
    "InvalidResponse":
    "...":
        _meta:
            ellipsis: true
            description: "Other exception types"

The _meta with ellipsis: true tells the renderer to display this as "..." and not expand it further. The ellipsis item is rendered with a dotted vertical line below it to indicate continuation. You can optionally add a description to provide context about the omitted items.

Complete Example: Exception Hierarchy

"RedisError":
    _meta:
        description: "Base class for all redis-py exceptions"
    "ConnectionError":
        _meta:
            description: "Connection-related errors"
        "TimeoutError":
        "BusyLoadingError":
    "ResponseError":
    "InvalidResponse":
    "DataError":
    "PubSubError":
    "...":
        _meta:
            ellipsis: true
            description: "Other exception types"

This represents an exception hierarchy with:

  • A base exception class with description
  • Nested exception types
  • An ellipsis indicating additional exception types not shown

Complete Example: Filesystem Hierarchy

"(root)":
    "config.yaml":
        _meta:
            description: "Main configuration file"
    "jobs":
        _meta:
            description: "Folder containing job definitions"
        "default-job.yaml":
            _meta:
                description: "Default job configuration"
        "job1.yaml":
        "...":
            _meta:
                ellipsis: true
                description: "Other job files"

This represents a filesystem structure with:

  • A root folder containing configuration files
  • Nested directories and files
  • Descriptions for each item
  • An ellipsis indicating additional files not shown

When type="filesystem" is used, the renderer displays file and folder icons next to each item.

Usage in Markdown

Code Block Syntax

```hierarchy {type="filesystem"}
Parent:
    Child1:
    Child2:
```

Attributes

  • type (optional): Indicates the kind of hierarchy. Common values:

    • type="exception" - Exception/error hierarchy
    • type="filesystem" - Filesystem or directory structure
    • type="generic" - Generic hierarchy (default if omitted)

    The type helps the renderer apply appropriate styling and helps AI agents understand the context.

  • noicons (optional): Disables icon rendering for filesystem hierarchies. Use noicons="true" to hide file/folder icons.

    • Only applies to type="filesystem"
    • Default: icons are shown

Placement

Place the hierarchy code block where you want the diagram to appear in the rendered HTML. The render hook will:

  1. Preserve the YAML source in a <pre> element (for AI agents)
  2. Generate a visual diagram below it (for users with JavaScript)

Best Practices

Naming

  • Use clear, descriptive names
  • Use quotes for any names with special characters
  • Keep names concise but meaningful

Organization

  • Order items logically (alphabetically, by importance, etc.)
  • Use ellipsis to indicate omitted items rather than showing everything
  • Group related items together

Metadata

  • Add metadata only when it provides useful information
  • Use consistent metadata field names across similar hierarchies
  • Keep descriptions brief (one sentence)

Metadata Reference

Supported Fields

Field Type Purpose Example
description string Brief description of the item (displayed as italic text) "Base exception class"
link string URL or relative path to make the item clickable "./api-reference.md" or "https://example.com"
ellipsis boolean Marks as placeholder for omitted items true

Notes

  • The description field is displayed as italic text after the item name in the rendered diagram
  • The link field makes items clickable in SVG diagrams and provides navigation for AI agents
  • The ellipsis field should be set to true for items representing omitted content (typically named "...")
  • Multiple metadata fields can be combined (e.g., description + link)
  • Other metadata fields may be added in the future

Rendering

For Users (HTML)

The render hook generates a visual SVG diagram with:

  • ASCII art-style tree structure with indented text
  • Connected tree lines showing parent-child relationships
  • File and folder icons for filesystem hierarchies (when type="filesystem")
  • Descriptions displayed as italic text after item names
  • Dotted vertical lines for ellipsis items indicating continuation
  • Space Mono font matching Redis documentation style

For AI Agents (Markdown)

AI agents accessing the .html.md version see the raw YAML:

  • Clean, structured format
  • Easy to parse and understand
  • Metadata preserved for context
  • Descriptions available for understanding item purposes

Validation

The YAML must be valid according to the YAML 1.2 specification:

  • Proper indentation (spaces, not tabs)
  • Quoted strings for special characters
  • Valid YAML syntax

Invalid YAML will cause rendering errors. Use a YAML validator to check your syntax.

Real-World Examples

See the following files for real-world examples:

  • content/develop/clients/redis-py/error-handling.md - Exception hierarchy with descriptions
  • content/integrate/redis-data-integration/data-pipelines/_index.md - Filesystem hierarchy with file/folder icons