Card Layouts

class CardsExtension(Extension):
    """
    Markdown extension for card layout components.
    
    Configuration:
    - priority: Extension processing priority (default: 12)
    - blank_target: Whether to open links in new tab (default: False)
    """
    config = {
        "priority": [12, "The priority to be configured for the extension."],
        "blank_target": [False, 'Whether to generate links with target="_blank"'],
    }
    
    def extendMarkdown(self, md): ...

class CardsEmbeddedProcessor(BaseCardsProcessor, EmbeddedBlockProcessor):
    """
    Block processor for embedded card data using ::cards:: syntax.
    """

class CardsSourceProcessor(BaseCardsProcessor, SourceBlockProcessor):
    """
    Block processor for external card data using [cards(...)] syntax.
    """

class BaseCardsProcessor:
    """
    Base class for card processors with common functionality.
    """
    @property
    def name(self) -> str:
        """Returns 'cards' as the processor name."""
    
    def norm_obj(self, obj):
        """
        Normalizes card data, converting image objects.
        
        Parameters:
        - obj: List of card item dictionaries
        """
    
    def build_html(self, parent, obj, props) -> None:
        """
        Builds HTML for card components.
        
        Parameters:
        - parent: Parent XML element
        - obj: List of card items
        - props: Configuration properties
        """

class CardItem:
    """
    Represents a single card item.
    
    Attributes:
    - title: Card title (required)
    - url: Optional link URL
    - content: Card content description
    - icon: Icon identifier (FontAwesome, image, or text)
    - key: Optional unique identifier
    - image: Optional card image
    """
    title: str
    url: Optional[str]
    content: Optional[str]
    icon: Optional[str]
    key: Optional[str]
    image: Optional[Image]

class Cards:
    """
    Represents a collection of card items.
    
    Attributes:
    - items: List of card items
    """
    items: List[CardItem]

class CardsViewOptions:
    """
    Configuration options for cards rendering.
    
    Attributes:
    - id: HTML ID attribute
    - class_name: CSS class name
    - cols: Number of columns in grid
    - image_bg: Whether to use images as backgrounds
    - blank_target: Whether to open links in new tab
    """
    id: Optional[str]
    class_name: Optional[str]
    cols: int
    image_bg: bool
    blank_target: bool

class CardsHTMLBuilder:
    """
    Builds HTML for card components.
    """
    def build_html(self, parent, cards: Cards) -> None:
        """
        Builds complete cards grid HTML structure.
        
        Parameters:
        - parent: Parent XML element
        - cards: Cards data to render
        """
    
    def build_item_html(self, parent, item: CardItem) -> None:
        """
        Builds HTML for individual card item.
        
        Parameters:
        - parent: Parent XML element
        - item: Card item to render
        """
    
    def build_image_html(self, wrapper_element, item: CardItem) -> None:
        """
        Builds card image HTML.
        
        Parameters:
        - wrapper_element: Card wrapper element
        - item: Card item with image data
        """

::cards::
- title: "Getting Started"
  content: "Learn the basics of using our platform"
  url: "/getting-started"
  icon: "play-circle"

- title: "API Reference"
  content: "Complete API documentation and examples"
  url: "/api"
  icon: "book"

- title: "Examples"
  content: "Code examples and tutorials"
  url: "/examples"
  icon: "code"
::end-cards::

::cards::
- title: "Product A"
  content: "High-quality product with advanced features"
  url: "/products/a"
  image:
    url: "./images/product-a.jpg"
    alt: "Product A"

- title: "Product B"
  content: "Affordable solution for everyday use"
  url: "/products/b"
  image:
    url: "./images/product-b.jpg"
    alt: "Product B"
::end-cards::

::cards:: cols=4 class="feature-cards"
- title: "Fast"
  content: "Lightning-fast performance"
  icon: "zap"

- title: "Secure"
  content: "Enterprise-grade security"
  icon: "shield"

- title: "Scalable"
  content: "Grows with your business"
  icon: "trending-up"

- title: "Reliable"
  content: "99.9% uptime guarantee"
  icon: "check-circle"
::end-cards::

::cards:: image_bg=true cols=2
- title: "Mountain Adventures"
  content: "Explore breathtaking mountain trails"
  image:
    url: "./images/mountains.jpg"
    alt: "Mountains"
  url: "/adventures/mountain"

- title: "Ocean Expeditions"
  content: "Discover underwater wonders"
  image:
    url: "./images/ocean.jpg"
    alt: "Ocean"
  url: "/adventures/ocean"
::end-cards::

[cards(features.yaml)]

- title: "Feature One"
  content: "Description of feature one"
  icon: "star"
- title: "Feature Two"
  content: "Description of feature two"
  icon: "heart"

::cards:: id="product-showcase" cols=3 blank_target=true
- title: "Professional Plan"
  content: |
    Perfect for growing teams and businesses.
    
    Features:
    - Unlimited projects
    - Advanced analytics
    - Priority support
    - Custom integrations
  url: "/pricing/professional"
  icon: "briefcase"
  image:
    url: "./images/pro-plan.jpg"
    alt: "Professional Plan"
    width: 300
    height: 200

- title: "Enterprise Plan"
  content: |
    For large organizations with complex needs.
    
    Features:
    - Everything in Professional
    - Dedicated account manager
    - Custom SLA
    - On-premise deployment
  url: "/pricing/enterprise"
  icon: "building"
  image:
    url: "./images/enterprise-plan.jpg"
    alt: "Enterprise Plan"
    width: 300
    height: 200

- title: "Contact Sales"
  content: |
    Need a custom solution? Our sales team can help you find the perfect fit for your organization.
  url: "/contact"
  icon: "phone"
::end-cards::

<!-- Local files -->
[cards(./data/products.yaml)]
[cards(../shared/features.json)]

<!-- URLs (if configured) -->
[cards(https://api.example.com/cards.json)]

title,content,url,icon
"Guide","User documentation","/docs","book"
"API","Technical reference","/api","code"
"Support","Get help","/support","help-circle"

# Simple string URL
- title: "Card with Image"
  image: "./images/card.jpg"

# Full image object
- title: "Card with Detailed Image"
  image:
    url: "./images/card.jpg"
    alt: "Card image description"
    width: 400
    height: 300

# Image with responsive attributes
- title: "Responsive Card"
  image:
    url: "./images/responsive-card.jpg"
    alt: "Responsive image"

<div class="cards-container">
  <div class="card">
    <div class="card-image">
      <img src="..." alt="...">
    </div>
    <div class="card-content">
      <h3 class="card-title">Title</h3>
      <p class="card-description">Content</p>
    </div>
    <div class="card-icon">
      <i class="fas fa-icon"></i>
    </div>
  </div>
</div>