---
title: "Views and Templates Category"
description: "Views and Templates"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-09"
last_update: "2026-09-09"
time_minutes: 1
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/ui"
---

# Views and Templates



---

## Renderer Project

Unified Template Rendering Made Simple For PHP

# Unified Template Rendering Made Simple For PHP

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/renderer/main)
![CI Workflow](https://github.com/derafu/renderer/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/renderer)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/renderer)
![Total Downloads](https://poser.pugx.org/derafu/renderer/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/renderer/d/monthly)

A modern, flexible PHP template rendering library that provides a unified interface for multiple template engines and output formats.

## Features

- 🔄 **Unified Interface**: One consistent API for all template engines.
- 🚀 **Multiple Engine Support**: Works with Twig, PHP, Markdown and more.
- 📄 **Multiple Output Formats**: Generate HTML, PDF from any template.
- 🔌 **Extensible Architecture**: Easy to add new engines and formats.
- 🎨 **Powerful Formatting System**: Format data consistently across all templates.
- 🛡️ **Secure by Design**: Safe template rendering and file handling.
- 🪶 **Lightweight Core**: Only load what you need.
- ⚡ **Framework Agnostic**: Use with any PHP framework.

## Why Derafu\Renderer?

Traditional template systems often lock you into a single engine or require different handling for each format. Derafu\Renderer solves this by providing:

- A single, clean API for all template engines.
- Seamless switching between output formats.
- Consistent data formatting across all templates.
- Framework-agnostic design.
- Easy integration with existing systems.

## Installation

Install via Composer:

```bash
composer require derafu/renderer
```

## Basic Usage

```php
use Derafu\Renderer\Factory\RendererFactory;

// Create renderer with engines Twig and PDF.
$renderer = RendererFactory::create([
    'engines' => ['twig', 'pdf'],
    'paths' => ['/path/to/templates'],
]);

// Render templates in different engines.
$html = $renderer->render('template.html.twig', ['name' => 'John']);
$pdf = $renderer->render('template.html.twig', ['name' => 'John'], ['engine' => 'pdf']);
```

## Template Engines

### Twig Templates
```php
// template.html.twig
<h1>Hello {{ name }}!</h1>
<p>Today is {{ date|format_as('date.long') }}</p>
```

### PHP Templates
```php
// template.php
<h1>Hello <?= $name ?>!</h1>
<p>Today is <?= $format_as($date, 'date.long') ?></p>
```

### Markdown Templates
```markdown
# Hello {{ name }}!

Today is {{ date }}
```

## Advanced Usage

### Custom Engine Configuration
```php
$renderer = RendererFactory::create([
    'engines' => ['twig', 'markdown', 'pdf'],
    'paths' => ['/path/to/templates'],
    'formatters' => [
        'date' => function (string $date): string {
            $timestamp = strtotime($date);
            return date('d/m/Y', $timestamp);
        },
    ],
]);
```




---

## Twig Project

Derafu Twig

# Derafu Twig




---

### Introduction

UI Component and Extension Library

# UI Component and Extension Library

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/twig/main)
![CI Workflow](https://github.com/derafu/twig/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/twig)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/twig)
![Total Downloads](https://poser.pugx.org/derafu/twig/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/twig/d/monthly)

**Derafu Twig** is a comprehensive UI component library for Twig, designed to work standalone or with any PHP framework. Built with Bootstrap 5 and Font Awesome 6, it provides a collection of reusable, customizable components for rapid web development.

## Features

- 🎨 **Rich Component Library**: Extensive collection of UI components including headers, footers, cards, grids, and more.
- 🎯 **Framework Agnostic**: Works with any PHP framework or standalone Twig.
- 🔧 **Highly Customizable**: Support for Bootstrap CSS variables for easy styling.
- 📱 **Responsive Design**: All components are mobile-first and fully responsive.
- 🧩 **Modular Architecture**: Components can be used independently or combined.
- 📦 **Bootstrap 5 Integration**: Leverages Bootstrap's grid system and utilities.
- 🎟️ **Font Awesome 6**: Integrated icon support.
- 🏷️ **MIT License**: Open-source and free to use.

## Component Categories

### Block Components

- **Layout**: Header, Footer, Grid.
- **Content**: Cards, Features (Grid, List, Icon, Table), Text with Image/Video.
- **Navigation**: Tabs, Steps, Timeline.
- **Interaction**: Accordion, CTA (Call to Action).
- **Showcasing**: Team, Testimonials, Hero, Image.
- **Comparison**: Tables, Boxes, Comparison grids.

## Extensions

- **Markdown**: render markdown content with `markdown` filter.
- **Translation**: `trans`/`t()`/`{% trans %}`/`{% trans_default_domain %}` —
  see [Translations](https://www.derafu.dev/docs/ui/twig/translations).

## Installation

Install the library using Composer:

```bash
composer require derafu/twig
```

## Basic Usage

1. Create the Twig environment with `TwigService` or register the components with `ComponentRegistrar`:

```php
use Derafu\Twig\Service\TwigService;

$options = [
    'paths' => [
        __DIR__ . '/../templates',  // Path to the derafu-twig templates.
        __DIR__ . '/pages',         // Path to your templates.
    ],
];

$twigService = new TwigService($options);

echo $twigService->render('example.html.twig');
```

2. Use components in your Twig templates:

```twig
{# Example using a card grid component #}
<twig:block-card-grid
    :cols="3"
    :cards="[
        {
            image: 'path/to/image.jpg',
            title: 'Card Title',
            content: 'Card content text',
            buttonText: 'Learn More',
            buttonUrl: '#'
        }
    ]"
/>
```

## Key Concepts

### Component Structure

Each component follows a consistent structure:

- PHP Class: Defines component properties and logic.
- Twig Template: Handles component rendering.
- CSS: Component-specific styles.

## Roadmap

- 🔌 More component variations.
- 📱 Enhanced mobile optimizations.
- 🎨 Additional theme presets.




---

### Components

Components

# Components

A collection of UI components for building easily web interfaces.




---

#### Accordion

Collapsible content sections.

<twig:block-accordion
    :items="[
        {
            title: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim. <a href=\'https://www.example.com/\' target=\'_blank\'>Link</a>',
        },
        {
            title: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim.',
        }
    ]"
/>

<twig:block-accordion
    :items="[
        {
            title: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim.',
            active: true
        },
        {
            title: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim.',
        }
    ]"
/>




---

#### Alert

Alert messages for user feedback.

{% set types = ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark'] %}
{% for type in types %}
    <twig:block-alert
      class="my-4"
      type="{{ type }}"
      content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore <a href='https://www.example.com/' target='_blank'>magna aliqua.</a>"
    />
{% endfor %}




---

#### Box

Simple box container for content.

<twig:block-box
    class="rounded"
    title="Box with rounded corners"
    content='Lorem ipsum dolor sit amet, consectetur adipiscing <a href="https://www.example.com/" target="_blank">elit</a>.'
/>

<twig:block-box
    title="Box without rounded corners"
    content="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
/>

<twig:block-box
    title="Box without content"
/>




---

#### Boxes

Large box display for information.

<twig:block-boxes
    class="my-4"
    cols="1"
    :boxes="[
        {
            icon: 'fa-solid fa-search',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur <a href=\'https://www.example.com/\' target=\'_blank\'>adipiscing elit.</a>',
            buttonText: 'Lorem ipsum',
            buttonUrl: '#'
        }
    ]"
/>

<twig:block-boxes
    class="my-4"
    :boxes="[
        {
            icon: 'fa-solid fa-search',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            buttonText: 'Lorem ipsum',
            buttonUrl: '#'
        },
        {
            icon: 'fa-solid fa-file',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            buttonText: 'Lorem ipsum',
        }
    ]"
/>

<twig:block-boxes
    class="my-4"
    cols="3"
    :boxes="[
        {
            icon: 'fa-solid fa-search',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
        },
        {
            icon: 'fa-solid fa-file',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            buttonText: 'Lorem ipsum',
            buttonUrl: '#'
        },
        {
            icon: 'fa-solid fa-file',
            title: 'Lorem ipsum dolor sit amet',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            buttonText: 'Lorem ipsum',
            buttonUrl: '#'
        }
    ]"
/>




---

#### Card Grid

Grid layout for multiple cards.

<twig:block-card-grid
    class="my-4"
    :cols="3"
    :cards="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig. <a href=\'https://www.example.com/\' target=\'_blank\'>Link</a>',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com',
            buttonColor: 'primary'
        },
        {
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            content: 'Twig is a twig'
        }
    ]"
/>

<twig:block-card-grid
    class="my-4"
    :cols="4"
    :cards="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com',
            buttonColor: 'success'
        }
    ]"
/>

<twig:block-card-grid
    class="my-4"
    :cols="3"
    :cards="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Twig',
            content: 'It is a twig.',
            buttonText: 'Learn about Twig',
            buttonUrl: 'https://twig.symfony.com',
            offset: 4
        }
    ]"
/>




---

#### Card

Card component for content display.

<twig:block-card
    class="my-4"
    image="/img/home/derafu-dev-programmer.png"
    title="Card"
    content="Lorem ipsum dolor sit amet, consectetur <a href='https://www.example.com/' target='_blank'>adipiscing elit.</a>"
    buttonText="More..."
    buttonUrl="https://www.example.com/"
/>




---

#### Comparison

Side-by-side comparison of features.

<twig:block-comparison
    class="my-4"
    :plans="[
        {
            title: 'Alpha Plan',
            price: '$20<small>.000</small>',
            period: '/month',
            features: [
                {
                    text: 'Up to <b>500</b> monthly receipts',
                    tooltip: 'Monthly limit for issuing or synchronizing electronic honorarium receipts (EHR).'
                },
                {
                    text: 'Allows other users',
                    value: false
                },
                {
                    text: 'API issuance',
                    value: true
                }
            ],
            note: 'Recommended for accountants or doctors.',
            buttonText: 'Sign up',
            buttonUrl: 'https://www.example.com/'
        },
        {
            title: 'Beta Plan',
            price: '$40<small>.000</small>',
            period: '/month',
            features: [
                {
                    text: 'Up to <b>2,000</b> monthly receipts'
                },
                {
                    text: 'Up to <b>2 users</b> can work with the issuer'
                },
                {
                    text: 'API issuance',
                    value: true
                }
            ],
            note: 'Recommended for professional societies.',
            buttonText: 'Sign up',
            buttonUrl: 'https://www.example.com/',
            highlighted: true
        },
        {
            title: 'Gamma',
            price: '$ 80<small>.000</small>',
            period: '/ month',
            features: [
                {
                    text: 'Up to <b>5,000</b> monthly receipts'
                },
                {
                    text: 'Up to <b>3 users</b> can work with the issuer'
                },
                {
                    text: 'API issuance',
                    value: true
                }
            ],
            note: 'Recommended for notaries.',
            buttonText: 'Sign up',
            buttonUrl: 'https://www.example.com/'
        }
    ]"
/>

<twig:block-comparison
    class="my-4"
    :plans="[
        {
            title: 'Android',
            priceIcon: 'fa-brands fa-android fa-2x',
            features: [
                {
                    text: 'Use the application with multiple <a href=\'https://www.example.com/\' target=\'_blank\'>companies</a>'
                },
                {
                    text: 'Issue receipts, invoices and shipping guides'
                },
                {
                    text: 'Easy receipt and retail point of sale'
                }
            ],
            note: 'Turn your Android device into a Point of Sale.',
            buttonText: 'Install from Google Play up to Android 9',
            buttonUrl: '#'
        },
        {
            title: 'iOS',
            priceIcon: 'fa-brands fa-apple fa-2x',
            features: [
                {
                    text: 'Use the application with multiple companies'
                },
                {
                    text: 'Issue receipts, invoices and shipping guides'
                },
                {
                    text: 'Easy receipt and retail point of sale'
                }
            ],
            note: 'Check your company and issue tax documents easily.',
            buttonText: 'Install from App Store',
            buttonUrl: '#',
            highlighted: true
        }
    ]"
/>




---

#### CTA

Call-to-action component.

<p><strong>Note</strong>: The CTA block can be used in full width or in a container. In full with the CTA should not have rounded corners. In this example we use a container, that is the reason why we have rounded corners.</p>

<twig:block-cta
    class="my-4 rounded p-4"
    title="Lorem ipsum dolor sit amet"
    content='Lorem ipsum dolor sit amet, consectetur <a href="https://www.example.com/" target="_blank">adipiscing elit.</a>'
    buttonText="More information"
    buttonUrl="https://www.example.com/"
/>

<twig:block-cta
    class="my-4 rounded p-4"
    title="Lorem ipsum dolor sit amet"
    content='Lorem ipsum dolor sit amet, consectetur <a href="https://www.example.com/" target="_blank">adipiscing elit.</a>'
    buttonText="Disabled button"
/>




---

#### Features Grid

Grid layout for features.

<twig:block-features-grid
    class="my-4"
    :blocks="[
        {
            title: 'Lorem',
            subtitle: 'First block subtitle',
            features: [
                {
                    icon: 'fa-solid fa-cloud',
                    title: 'Feature 1',
                    content: 'Content of <a href=\'https://www.example.com/\' target=\'_blank\'>feature 1.</a>'
                },
                {
                    icon: 'fa-solid fa-cog',
                    title: 'Feature 2',
                    content: 'Content of feature 2.'
                },
                {
                    icon: 'fa-solid fa-users',
                    title: 'Feature 3',
                    content: 'Content of feature 3.'
                }
            ]
        },
        {
            title: 'Ipsum',
            subtitle: 'Subtitle of the second <a href=\'https://www.example.com/\' target=\'_blank\'>block</a>.',
            features: [
                {
                    icon: 'fa-solid fa-star',
                    title: 'Feature 1',
                    content: 'Content of feature 1.'
                },
                {
                    icon: 'fa-solid fa-heart',
                    title: 'Feature <a href=\'https://www.example.com/\' target=\'_blank\'>2</a>',
                    content: 'Content of feature 2.'
                },
                {
                    icon: 'fa-solid fa-bell',
                    title: 'Feature 3',
                    content: 'Content of feature 3.'
                }
            ]
        }
    ]"
/>




---

#### Features Icon

Icon list for features.

{# Case 4 elements (one row of 4) #}
<twig:block-features-icon
    class="my-4"
    :features="[
        {
            icon: 'fa-solid fa-cloud',
            title: 'Software as a Service',
            content: 'We are a cloud software, you need Internet access to <a href=\'https://www.example.com/\' target=\'_blank\'>use it.</a>'
        },
        {
            icon: 'fa-solid fa-money-bill',
            title: '<a href=\'https://www.example.com/\' target=\'_blank\'>Price</a> per company',
            content: 'The Plus Service price is per company. If you have 3 companies, you will need to pay for 3 Plus Services.'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'SII Synchronization',
            content: 'Your tax documents are immediately sent to SII and we monitor their status.'
        },
        {
            icon: 'fa-solid fa-check',
            title: 'Feature 4',
            content: 'Content of feature 4.'
        }
    ]"
/>

{# Case 5 elements (row of 3 + row of 2) #}
<twig:block-features-icon
    class="my-4"
    :features="[
        {
            icon: 'fa-solid fa-cloud',
            title: 'Feature 1',
            content: 'Content 1'
        },
        {
            icon: 'fa-solid fa-money-bill',
            title: 'Feature 2',
            content: 'Content 2'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Feature 3',
            content: 'Content 3'
        },
        {
            icon: 'fa-solid fa-check',
            title: 'Feature 4',
            content: 'Content 4'
        },
        {
            icon: 'fa-solid fa-star',
            title: 'Feature 5',
            content: 'Content 5'
        }
    ]"
/>

{# Case 8 elements (two rows of 4) #}
<twig:block-features-icon
    class="my-4"
    :features="[
        {
            icon: 'fa-solid fa-cloud',
            title: 'Feature 1',
            content: 'Content 1'
        },
        {
            icon: 'fa-solid fa-money-bill',
            title: 'Feature 2',
            content: 'Content 2'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Feature 3',
            content: 'Content 3'
        },
        {
            icon: 'fa-solid fa-check',
            title: 'Feature 4',
            content: 'Content 4'
        },
        {
            icon: 'fa-solid fa-star',
            title: 'Feature 5',
            content: 'Content 5'
        },
        {
            icon: 'fa-solid fa-heart',
            title: 'Feature 6',
            content: 'Content 6'
        },
        {
            icon: 'fa-solid fa-bell',
            title: 'Feature 7',
            content: 'Content 7'
        },
        {
            icon: 'fa-solid fa-user',
            title: 'Feature 8',
            content: 'Content 8'
        }
    ]"
/>




---

#### Features List

List of features with left and right alignment.

<twig:block-features-list
    class="my-4"
    :featuresLeft="[
        {
            icon: 'fa-solid fa-laptop fa-fw',
            title: 'Web <a href=\'https://www.example.com/\' target=\'_blank\'>Application.</a>',
            content: 'With individual and <a href=\'https://www.example.com/\' target=\'_blank\'>bulk</a> document issuance.'
        },
        {
            icon: 'fa-solid fa-chart-line fa-fw',
            title: 'Reports',
            content: 'Charts and statistics to visualize your data in a simple way.'
        },
        {
            icon: 'fa-solid fa-cogs fa-fw',
            title: 'Configuration',
            content: 'Customize the application according to your specific needs.'
        }
    ]"
    :featuresRight="[
        {
            icon: 'fa-solid fa-cubes fa-fw',
            title: 'Products and Services',
            content: 'Code your products and services to issue quickly.'
        },
        {
            icon: 'fa-solid fa-cloud-download fa-fw',
            title: 'Backup',
            content: 'Download your data whenever you need it.'
        },
        {
            icon: 'fa-solid fa-shield fa-fw',
            title: 'Security',
            content: 'Your data is protected with the highest security standards.'
        }
    ]"
/>




---

#### Features Table

Table of features with values.

<twig:block-features-table
    class="my-4"
    title="Features"
    :features="[
        {
            icon: 'fa-solid fa-folder',
            title: 'Taxpayers API',
            content: 'Tax status of third parties and <a href=\'https://www.example.com/\' target=\'_blank\'>economic activities</a>',
            values: {
                'SME Plan': true,
                'Premium Plan': true,
                'Pro Plan': true,
                'Premier Plan': true,
                'e600k Plan': true
            }
        },
        {
            icon: 'fa-solid fa-chart-line',
            title: 'SII API',
            content: 'Indicators: UF and complementary global tax.',
            values: {
                'SME Plan': true,
                'Premium Plan': true,
                'Pro Plan': true,
                'Premier Plan': true,
                'e600k Plan': true
            }
        },
        {
            icon: 'fa-solid fa-file-lines',
            title: 'DTE API',
            content: 'Electronic tax documents.',
            values: {
                'SME Plan': true,
                'Premium Plan': true,
                'Pro Plan': true,
                'Premier Plan': true,
                'e600k Plan': true
            }
        },
        {
            icon: 'fa-solid fa-file-invoice',
            title: 'BHE API',
            content: 'Issued and received fee receipts.',
            values: {
                'SME Plan': false,
                'Premium Plan': false,
                'Pro Plan': true,
                'Premier Plan': true,
                'e600k Plan': true
            }
        },
        {
            icon: 'fa-solid fa-car',
            title: 'Vehicles API',
            content: 'Vehicle appraisal.',
            values: {
                'SME Plan': false,
                'Premium Plan': false,
                'Pro Plan': false,
                'Premier Plan': true,
                'e600k Plan': true
            }
        },
        {
            icon: 'fa-solid fa-chart-bar',
            title: 'Queries every 24 hours',
            values: {
                'SME Plan': '<span class=\'lead\'><a href=\'https://www.example.com/\' target=\'_blank\'>500</a></span>',
                'Premium Plan': '<span class=\'lead\'>1.400</span>',
                'Pro Plan': '<span class=\'lead\'>4.000</span>',
                'Premier Plan': '<span class=\'lead\'>10.000</span>',
                'e600k Plan': '<span class=\'lead\'>20.000</span>'
            }
        },
        {
            icon: 'fa-solid fa-dollar',
            title: '<a href=\'https://www.example.com/\' target=\'_blank\'>Plan price</a>',
            content: '+ VAT / month',
            values: {
                'SME Plan': '<span class=\'lead\'>$40.000</span>',
                'Premium Plan': '<span class=\'lead\'>$80.000</span>',
                'Pro Plan': '<span class=\'lead\'>$150.000</span>',
                'Premier Plan': '<span class=\'lead\'>$300.000</span>',
                'e600k Plan': '<span class=\'lead\'>$600.000</span>'
            }
        }
    ]"
/>

<twig:block-features-table
    class="my-4"
    title="Plan Comparison"
    :features="[
        {
            isHeader: true,
            title: 'API Access'
        },
        {
            icon: 'fa-solid fa-folder',
            title: 'Taxpayers API',
            content: 'Tax data consultation',
            values: {
                'Basic': true,
                'Complete': true
            }
        },
        {
            icon: 'fa-solid fa-file-invoice',
            title: 'Documents API',
            content: 'Electronic invoices and receipts',
            values: {
                'Basic': false,
                'Complete': true
            }
        },
        {
            isHeader: true,
            title: 'Technical Support'
        },
        {
            title: 'Email support',
            values: {
                'Basic': true,
                'Complete': true
            }
        },
        {
            isHeader: true,
            icon: 'fa-solid fa-dollar',
            title: 'Pricing'
        },
        {
            icon: 'fa-solid fa-money-bill',
            title: 'Monthly cost',
            content: '+ VAT',
            values: {
                'Basic': '<span class=\'lead\'>$35.000</span>',
                'Complete': '<span class=\'lead\'>$90.000</span>'
            }
        }
    ]"
/>




---

#### Footer

Footer component with multiple layouts.

{# Example 1: Complete Footer with 4 columns #}
<twig:block-footer
    class="my-4"
    col1Title="Useful Links"
    :col1Links="[
        {
            text: 'Academy',
            url: 'http://www.example.com',
            icon: 'fa-solid fa-graduation-cap fa-fw'
        },
        {
            text: 'Jobs',
            url: 'http://www.example.com',
            icon: 'fa-solid fa-briefcase fa-fw',
            targetBlank: true
        },
        {
            text: 'Store',
            url: '#',
            icon: 'fa-solid fa-shopping-cart fa-fw'
        },
        {
            text: 'Bank Transfer Payments',
            url: '#',
            icon: 'fa-solid fa-money-bill fa-fw'
        }
    ]"

    col2Title="Software Products"
    :col2Links="[
        {
            text: 'Software 1',
            url: '#',
            icon: 'fa-solid fa-file-invoice fa-fw'
        },
        {
            text: 'Software 2',
            url: '#',
            icon: 'fa-solid fa-network-wired'
        },
        {
            text: 'Software 3',
            url: '#',
            icon: 'fa-solid fa-cash-register fa-fw'
        }
    ]"

    col3Title="Contact Us"
    :col3Links="[
        {
            text: 'derafu-twig@example.com',
            url: 'mailto:derafu-twig@example.com',
            icon: 'fa-solid fa-envelope fa-fw'
        },
        {
            text: 'Schedule a Meeting',
            url: '#',
            icon: 'fa-solid fa-calendar fa-fw'
        },
        {
            text: 'Help Center',
            url: '#',
            icon: 'fa-solid fa-question-circle fa-fw'
        }
    ]"

    col4Title="Derafu DEV"
    col4Html="<p>From Chile to the world with ❤️</p>"
    :col4SocialIcons="[
        {
            icon: 'fa-brands fa-linkedin fa-2x',
            url: '#',
            color: '#0077b5',
            targetBlank: true
        },
        {
            icon: 'fa-brands fa-github fa-2x',
            url: '#',
            color: '#333',
            targetBlank: true
        }
    ]"

    leftText="Copyright © Derafu DEV"
    rightText="All rights reserved"
    socialIconsCircular="true"
/>

{# Example 2: Minimalist Footer with 2 columns #}
<twig:block-footer
    class="my-4"
    col1Title="Our Company"
    col1Html="<p>Innovative software solutions for modern businesses.</p>"
    :col1Links="[
        {
            text: 'About Us',
            url: '#'
        },
        {
            text: 'Contact',
            url: '#'
        }
    ]"

    col2Title="Quick Links"
    :col2Links="[
        {
            text: 'Documentation',
            url: '#'
        },
        {
            text: 'Support',
            url: '#'
        }
    ]"

    leftText="© 2024 Derafu ORG"
/>

{# Example 3: Footer with emphasis on social media #}
<twig:block-footer
    class="my-4"
    col1Title="Follow Us"
    col1Html="<p>Stay connected with us on social media</p>"
    :col1SocialIcons="[
        {
            icon: 'fa-brands fa-facebook fa-2x',
            url: 'http://www.example.com',
            color: '#1877f2',
            targetBlank: true
        },
        {
            icon: 'fa-brands fa-twitter fa-2x',
            url: '#',
            color: '#1da1f2',
            targetBlank: true
        },
        {
            icon: 'fa-brands fa-instagram fa-2x',
            url: '#',
            color: '#e4405f',
            targetBlank: true
        },
        {
            icon: 'fa-brands fa-youtube fa-2x',
            url: '#',
            color: '#ff0000',
            targetBlank: true
        }
    ]"

    col2Title="Community"
    :col2Links="[
        {
            text: 'Blog',
            url: '#',
            icon: 'fa-solid fa-blog'
        },
        {
            text: 'Forum',
            url: '#',
            icon: 'fa-solid fa-comments'
        },
        {
            text: 'Events',
            url: '#',
            icon: 'fa-solid fa-calendar-days'
        }
    ]"
    :col2SocialIcons="[
        {
            icon: 'fa-brands fa-discord fa-2x',
            url: '#',
            color: '#5865f2',
            targetBlank: true
        },
        {
            icon: 'fa-brands fa-telegram fa-2x',
            url: '#',
            color: '#0088cc',
            targetBlank: true
        }
    ]"

    leftText="Join our community"
    rightText='<a href="#">Privacy Policy</a> | <a href="#">Terms of Use</a>'
/>




---

#### Gallery

Grid of images and videos with a click-to-enlarge lightbox.

{#
    Basic gallery with images only. The "caption" field is optional per item
    (the first photo below has none).
    The "caption" text is shown two places: as an overlay at the bottom of
    each thumbnail in the grid, and again under the media inside the
    lightbox once you click a thumbnail to open it.
    "size" controls the lightbox modal size. Valid values: "sm", "lg", "xl"
    (default) and "fullscreen".
#}
<twig:block-gallery
    class="my-4"
    :cols="4"
    size="sm"
    :items="[
        {
            image: '/img/home/derafu-dev-programmer.png',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Caption for photo 2'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Caption for photo 3'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Caption for photo 4'
        }
    ]"
/>

{#
    Gallery mixing images and videos in the same grid. Video thumbnails
    without a custom "thumbnail" show a play icon over a dark background
    (see the next example for a video with a real poster image instead).
#}
<twig:block-gallery
    class="my-4"
    :cols="3"
    :items="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Photo 1'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            caption: 'Video 1 (no thumbnail: play icon placeholder)'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Photo 2'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            caption: 'Video 2 (no thumbnail: play icon placeholder)'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Photo 3'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            caption: 'Video 3 (no thumbnail: play icon placeholder)'
        }
    ]"
/>

{#
    Gallery combining every optional field: "thumbnail" as a custom poster
    for a video item, "alt" as the accessible/tooltip text shown on hover
    over image thumbnails, and "caption" shown under the thumbnail and in
    the lightbox.
#}
<twig:block-gallery
    class="my-4"
    :cols="6"
    :items="[
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            thumbnail: '/img/home/derafu-dev-programmer.png',
            alt: 'Product demo',
            caption: 'Video with poster'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            alt: 'Team photo',
            caption: 'Team'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            alt: 'Office',
            caption: 'Office'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            alt: 'Tutorial',
            caption: 'Video without poster'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            alt: 'Event',
            caption: 'Event'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            alt: 'Conference',
            caption: 'Conference'
        }
    ]"
/>

{# Gallery with a fullscreen lightbox (size="fullscreen") #}
<twig:block-gallery
    class="my-4"
    :cols="2"
    size="fullscreen"
    :items="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Wide photo 1'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            caption: 'Wide photo 2'
        }
    ]"
/>




---

#### Grid

Grid layout for content.

{% set grid_item_1 %}
    <h2>Item 1</h2>
    <p>orem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet <a href="https://www.example.com/" target="_blank">tempus gravida.</a></p>
{% endset %}

{% set grid_item_2 %}
    <twig:block-image
        title="What is Twig?"
        image="/img/home/derafu-dev-programmer.png"
        content="<p>A small branch.</p>"
        :buttons="[
            {
                text: 'Learn about Twig',
                url: 'https://twig.symfony.com/'
            }
        ]"
    />
{% endset %}

{% set grid_item_3 %}
    <twig:block-image
        title="Lorem ipsum"
        image="/img/home/derafu-dev-programmer.png"
        content="<p>Dolor sit amet</p>"
        :buttons="[
            {
                text: 'Consectetur',
                url: 'https://twig.symfony.com/'
            }
        ]"
    />
{% endset %}

{# Example 1: Grid without specified columns #}
<twig:block-grid
    class="my-4"
    :items="[
        grid_item_1,
        grid_item_2,
    ]"
/>

{# Example 2: Grid with 4 columns #}
<twig:block-grid
    class="my-4"
    cols="4"
    :items="[
        grid_item_1,
        grid_item_2,
        grid_item_3,
        grid_item_2,
    ]"
/>




---

#### Header

Header component with multiple layouts.

<twig:block-header
    class="mt-0"
    logoImage="/img/home/derafu-dev-programmer.png"
    logoText="<span class='fw-normal'>Soft</span><span class='fw-bold text-primary'>ware</span>"
    :leftNav="[
        {
            text: 'Home',
            url: '#'
        },
        {
            text: 'Solutions',
            icon: 'fa-solid fa-cubes',
            items: [
                {
                    text: 'Basic Solution',
                    icon: 'fa-solid fa-star',
                    url: '#'
                },
                {
                    type: 'divider'
                },
                {
                    text: 'Advanced Solution',
                    icon: 'fa-solid fa-rocket',
                    items: [
                        {
                            text: 'Main Features',
                            url: '#'
                        },
                        {
                            icon: 'fa-solid fa-chart-line',
                            text: 'Analysis',
                            url: '#'
                        },
                        {
                            type: 'divider'
                        },
                        {
                            icon: 'fa-solid fa-book-open',
                            text: 'Complete Guide',
                            url: '#'
                        }
                    ]
                }
            ]
        }
    ]"
    :rightNav="[
        {
            text: 'Resources',
            url: '#',
            icon: 'fa-solid fa-toolbox'
        },
        {
            text: 'Integrations',
            icon: 'fa-solid fa-plug',
            items: [
                {
                    text: 'Platforms',
                    icon: 'fa-solid fa-desktop',
                    url: '#'
                },
                {
                    text: 'API',
                    icon: 'fa-solid fa-code',
                    url: '#'
                }
            ]
        }
    ]"
    ctaIcon="fa-solid fa-rocket"
    ctaText="Get Started"
    ctaUrl="#"
/>

<twig:block-header
    class="my-4"
    logoImage="/img/home/derafu-dev-programmer.png"
    logoText="<span class='fw-normal'>Another</span><span class='fw-bold text-primary'>Example</span>"
    :leftNav="[
        {
            text: 'Marketplace',
            icon: 'fa-solid fa-shopping-cart',
            sections: [
                {
                    title: 'Technology',
                    links: [
                        {
                            text: 'Software',
                            url: '#',
                            icon: 'fa-solid fa-laptop-code'
                        },
                        {
                            text: 'Hardware',
                            url: '#',
                            icon: 'fa-solid fa-server'
                        }
                    ]
                }
            ]
        }
    ]"
    ctaText="Explore"
    ctaUrl="#"
/>




---

#### Hero

Hero section for landing pages.

<twig:block-hero
   class="my-4"
   align="left"
   background="/img/home/derafu-dev-programmer.png"
   title="Lorem <a href='https://www.example.com/' target='_blank'>ipsum</a>"
   subtitle="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
   :buttons="[
       {
           text: 'Example.com',
           url: 'https://www.example.com'
       }
   ]"
/>

<twig:block-hero
   class="my-4"
   align="left"
   background="/img/home/derafu-dev-programmer.png"
   contentBackground="true"
   title="Lorem ipsum"
   subtitle="Lorem ipsum dolor sit amet, consectetur <a href='https://www.example.com/' target='_blank'>adipiscing elit.</a>"
   :buttons="[
       {
           text: 'Example.com',
           url: 'https://www.example.com'
       }
   ]"
/>

<twig:block-hero
   class="my-4"
   align="right"
   background="/img/home/derafu-dev-programmer.png"
   title="Lorem ipsum"
   subtitle="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
   :buttons="[
       {
           text: 'Example.com',
           url: 'https://www.example.com'
       }
   ]"
/>

<twig:block-hero
    class="my-4"
    title="Hero"
    subtitle="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    :buttons="[
        {
            text: 'Example.com 1',
            url: 'https://www.example.com'
        },
        {
            text: 'Example.com 2',
            url: 'https://www.example.com'
        }
    ]"
/>

{% set sizes = ['mini', 'small', 'medium', 'large', 'full'] %}
{% for size in sizes %}
   <twig:block-hero
       class="my-4"
       align="right"
       size="{{ size }}"
       background="/img/home/derafu-dev-programmer.png"
       title="Size: {{ size }}"
       subtitle="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
       :buttons="[
           {
               text: 'Example.com',
               url: 'https://www.example.com'
           }
       ]"
   />
{% endfor %}




---

#### Image Grid

Grid layout for images.

<twig:block-image-grid
    class="my-4"
    :cols="4"
    :images="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            url: 'https://www.example.com',
            tooltip: 'Company 1'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            tooltip: 'Company 2'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            url: 'https://www.example.com',
            tooltip: 'Company 1'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            tooltip: 'Company 2'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
        }
    ]"
/>




---

#### Image

Image component with title, content and buttons.

<twig:block-image
    class="my-4"
    title="What is Twig?"
    image="/img/home/derafu-dev-programmer.png"
    content="A <a href='https://www.example.com/' target='_blank'>small branch</a>."
    :buttons="[
        {
            text: 'Learn about Twig',
            url: 'https://twig.symfony.com/'
        }
    ]"
/>

<twig:block-image
    class="my-4"
    size="small"
    title="What is <a href='https://www.example.com/' target='_blank'>Twig</a>?"
    image="/img/home/derafu-dev-programmer.png"
    content="A small branch"
    :buttons="[
        {
            text: 'Learn about Twig',
            url: 'https://twig.symfony.com/'
        }
    ]"
/>




---

#### Media List

List of media items.

<twig:block-media-list
    class="mb-5"
    :items="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 1',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 2',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 3',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        }
    ]"
/>

<twig:block-media-list
    class="mb-5"
    :rounded="true"
    :items="[
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 1',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 2',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        },
        {
            image: '/img/home/derafu-dev-programmer.png',
            title: 'Title 3',
            content: '<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>'
        }
    ]"
/>




---

#### Modal

Popup dialog windows.

{# Simple modal #}
<div class="mb-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-1">
        Open simple modal
    </button>
</div>
<twig:block-modal
    id="modal-1"
    title="Modal Title"
    content="This is a basic modal with title and <a href='https://www.example.com/' target='_blank'>close button.</a>"
    :buttons="[
        {
            text: 'Close',
            type: 'secondary',
            dismiss: true
        },
        {
            text: 'Save Changes',
            type: 'primary'
        }
    ]"
/>

{# Complex modal #}
<div class="mt-2 mb-3">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-2">
        Open complex modal
    </button>
</div>
<twig:block-modal
    id="modal-2"
    title="Confirmation Required"
    content="<p>This action cannot be undone. Are you sure you want to continue?</p>"
    size="lg"
    :centered="true"
    :withBackdrop="true"
    :buttons="[
        {
            text: 'Cancel',
            type: 'light',
            dismiss: true
        },
        {
            text: 'Yes, continue',
            type: 'danger',
            attributes: 'onclick=\'handleConfirmation()\''
        }
    ]"
/>

{# Fullscreen modal with scrollable content #}
<div class="mt-3 mb-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-3">
        Open fullscreen modal with scrollable content
    </button>
</div>
<twig:block-modal
    id="modal-3"
    title="Terms and Conditions"
    content="<div style='height: 1000px'>Very long content...</div>"
    size="fullscreen"
    :scrollable="true"
    :buttons="[
        {
            text: 'Accept',
            type: 'success'
        }
    ]"
/>

{# Basic modal #}
<div class="mt-0">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-basic">
        Open basic modal
    </button>
</div>
<twig:block-modal
    id="modal-basic"
    title="Basic Modal"
    content="<p>This is a simple modal with title and close button.</p>"
    :buttons="[
        {
            text: 'Close',
            type: 'secondary',
            dismiss: true
        }
    ]"
/>

{# Modal without close button #}
<div class="mt-2 mb-2">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-no-close">
        Modal without X
    </button>
</div>
<twig:block-modal
    id="modal-no-close"
    title="You can't close me easily"
    content="<p>This modal doesn't have the X button to close.</p>"
    :showClose="false"
    :buttons="[
        {
            text: 'Got it',
            type: 'warning',
            dismiss: true
        }
    ]"
/>

{# Modal with static backdrop #}
<div class="mt-3 mb-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-static">
        Modal that does not close
    </button>
</div>
<twig:block-modal
    id="modal-static"
    title="You must make a decision"
    content="<p>This modal won't close when clicking outside. You must use one of the buttons.</p>"
    :withBackdrop="true"
    :buttons="[
        {
            text: 'Cancel',
            type: 'light',
            dismiss: true
        },
        {
            text: 'Accept',
            type: 'danger',
            dismiss: true
        }
    ]"
/>

{# Modal centered with small size #}
<div class="my-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-sm-centered">
        Modal SM centered
    </button>
</div>
<twig:block-modal
    id="modal-sm-centered"
    title="Small and Centered"
    content="<p>A small modal centered vertically.</p>"
    size="sm"
    :centered="true"
    :buttons="[
        {
            text: 'OK',
            type: 'info',
            dismiss: true
        }
    ]"
/>

{# Modal large with scroll #}
<div class="mt-3 mb-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-lg-scroll">
        Modal large with scroll
    </button>
</div>
<twig:block-modal
    id="modal-lg-scroll"
    title="Terms and Conditions"
    content="<div>
        <h4>1. Introduction</h4>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
    </div>"
    size="lg"
    :scrollable="true"
    :buttons="[
        {
            text: 'Reject',
            type: 'light',
            dismiss: true
        },
        {
            text: 'Accept Terms',
            type: 'success',
            dismiss: true
        }
    ]"
/>

{# Modal extra large with form #}
<div class="mt-2 mb-3">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-xl-form">
        Form in modal XL
    </button>
</div>
<twig:block-modal
    id="modal-xl-form"
    title="User Registration"
    content="<form id='userForm'>
        <div class='row'>
            <div class='col-md-6 mb-3'>
                <label for='firstName' class='form-label'>Name</label>
                <input type='text' class='form-control' id='firstName' required>
            </div>
        </div>
    </form>"
    size="xl"
    :centered="true"
    :buttons="[
        {
            text: 'Cancel',
            type: 'secondary',
            dismiss: true
        },
        {
            text: 'Register',
            type: 'dark',
            attributes: 'onclick="document.getElementById(\'userForm\').submit()"'
        }
    ]"
/>

{# Modal fullscreen #}
<div class="mt-3 mb-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-fullscreen">
        View in full screen
    </button>
</div>
<twig:block-modal
    id="modal-fullscreen"
    title="Fullscreen Mode"
    content="<div class='text-center'>
        <h1 class='display-1'>👋</h1>
        <p class='lead'>This modal takes up the entire screen</p>
    </div>"
    size="fullscreen"
    :buttons="[
        {
            text: 'Exit',
            type: 'outline-primary',
            dismiss: true
        }
    ]"
/>

{# Modal without footer #}
<div class="my-4">
    <button type="button" class="btn btn-light d-block" data-bs-toggle="modal" data-bs-target="#modal-no-footer">
        Modal without footer
    </button>
</div>
<twig:block-modal
    id="modal-no-footer"
    title="Content Only"
    content="<p>This modal has no buttons in the footer, only the close button in the header.</p>"
/>




---

#### Offcanvas

Hidden sidebars.

{# Left Offcanvas (start) #}
<div class="mb-4">
    <button class="btn btn-light d-block" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvas-left">
        Left Menu
    </button>
</div>

<twig:block-offcanvas
    id="offcanvas-left"
    position="start"
    title="Navigation Menu"
    content="<ul class='nav flex-column'>
        <li class='nav-item'><a class='nav-link' href='#'>Home</a></li>
        <li class='nav-item'><a class='nav-link' href='#'>Products</a></li>
        <li class='nav-item'><a class='nav-link' href='#'>Services</a></li>
        <li class='nav-item'><a class='nav-link' href='#'>Contact</a></li>
    </ul>"
/>

{# Right Offcanvas with Form #}
<div class="mt-2 mb-3">
    <button class="btn btn-light d-block" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvas-right">
        Edit Profile
    </button>
</div>

<twig:block-offcanvas
    id="offcanvas-right"
    position="end"
    title="Edit Profile"
    content="<form id='profileForm'>
        <div class='mb-3'>
            <label class='form-label'>Name</label>
            <input type='text' class='form-control'>
        </div>
        <div class='mb-3'>
            <label class='form-label'>Email</label>
            <input type='email' class='form-control'>
        </div>
        <div class='mb-3'>
            <label class='form-label'>Bio</label>
            <textarea class='form-control' rows='3'></textarea>
        </div>
    </form>"
    :buttons="[
        {
            text: 'Cancel',
            type: 'light',
            dismiss: true
        },
        {
            text: 'Save',
            type: 'success',
            attributes: 'onclick="document.getElementById(\'profileForm\').submit()"'
        }
    ]"
/>

{# Top Offcanvas #}
<div class="mt-3 mb-4">
    <button class="btn btn-light d-block" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvas-top">
        Notifications
    </button>
</div>

<twig:block-offcanvas
    id="offcanvas-top"
    position="top"
    title="Notifications"
    :scrollable="true"
    content="<div class='list-group'>
        <a href='#' class='list-group-item list-group-item-action'>
            <div class='d-flex w-100 justify-content-between'>
                <h6 class='mb-1'>New message</h6>
                <small>3 mins ago</small>
            </div>
            <p class='mb-1'>You have a new support message.</p>
        </a>
        <!-- More notifications... -->
    </div>"
/>

{# Bottom Offcanvas without Backdrop #}
<div class="mt-2 mb-3">
    <button class="btn btn-light d-block" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvas-bottom">
        Music Player
    </button>
</div>

<twig:block-offcanvas
    id="offcanvas-bottom"
    position="bottom"
    :withBackdrop="false"
    :showClose="false"
    content="<div class='d-flex align-items-center justify-content-between'>
        <div class='d-flex align-items-center'>
            <img src='/img/home/derafu-dev-programmer.png' width='50' height='50' class='me-3'>
            <div>
                <h6 class='mb-0'>Song Name</h6>
                <small>Artist</small>
            </div>
        </div>
        <div class='btn-group'>
            <button class='btn btn-link'><i class='fas fa-backward'></i></button>
            <button class='btn btn-link'><i class='fas fa-play'></i></button>
            <button class='btn btn-link'><i class='fas fa-forward'></i></button>
        </div>
    </div>"
/>

{# Offcanvas with Scroll and No Backdrop #}
<div class="mt-2 mb-3">
    <button class="btn btn-light d-block" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvas-scroll">
        Documentation
    </button>
</div>

<twig:block-offcanvas
    id="offcanvas-scroll"
    position="end"
    title="Documentation"
    :scrollable="true"
    :withBackdrop="false"
    content="<div>
        <h4>Introduction</h4>
        <p>Lorem ipsum dolor sit amet...</p>
        <h4>Getting Started</h4>
        <p>Sed do eiusmod tempor incididunt...</p>
        <h4>Configuration</h4>
        <p>Ut enim ad minim veniam...</p>
        <!-- More content to demonstrate scroll -->
    </div>"
    :buttons="[
        {
            text: 'Close',
            type: 'secondary',
            dismiss: true
        }
    ]"
/>




---

#### Quote

Quotes with author and note.

<twig:block-quote
    class="my-4"
    content="Lorem ipsum dolor sit amet, consectetur adipiscing <a href='https://www.example.com/' target='_blank'>elit</a>."
    author="John Doe"
    note="Quote"
    image="/img/home/derafu-dev-programmer.png"
/>

{# Example with individual margins #}
<twig:block-quote
    class="my-4"
    content="Another example quote with custom margins."
    author="Jane Smith"
    note="<a href='https://www.example.com/' target='_blank'>Quote example</a>"
/>

{# Example without margins #}
<twig:block-quote
    class="my-4"
    content="A quote without special margins."
    author="Anonymous"
/>




---

#### Scrollspy

Scrollspy component for navigation.

{# Define the contents for the sections #}
{% set section_content_introduccion %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. <a href="https://www.example.com/" target="_blank">Quisquam, quos.</a></p>
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
{% endset %}

{% set section_content_features %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
    <ul>
        <li><strong>Lorem  Ipsum</strong> - Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><strong>Lorem  Ipsum</strong> - Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><strong>Lorem  Ipsum</strong> - Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><strong>Lorem  Ipsum</strong> - Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><strong>Lorem  Ipsum</strong> - Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
    </ul>
{% endset %}

{% set section_content_options %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
    <ul>
        <li><code>Lorem</code>: Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><code>Lorem</code>: Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><code>Lorem</code>: Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><code>Lorem</code>: Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li><code>Lorem</code>: Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
    </ul>
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
{% endset %}

{% set section_content_usage %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
    <ol>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
    </ol>
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
{% endset %}

{% set section_content_advanced %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
    <ul>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
        <li>Lorem ipsum dolor sit amet consectetur adipisicing elit.</li>
    </ul>
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, quos.</p>
{% endset %}

{# Example 1: Vertical Scrollspy #}
<twig:block-scrollspy
    class="my-4 shadow-none"
    style="--scrollspy-list-active-bg: #0066cc;"
    height="100vh"
    :cols="3"
    :sections="[
        {
            id: 'introduction',
            title: 'Lorem ipsum dolor sit amet',
            content: section_content_introduction
        },
        {
            id: 'features',
            title: 'Lorem',
            content: section_content_features
        },
        {
            id: 'options',
            title: 'Lorem',
            content: section_content_options
        }
    ]"
/>

<hr class="my-4"/>

{# Example 2: Horizontal Scrollspy #}
<twig:block-scrollspy
    class="my-4 shadow "
    style="--scrollspy-list-active-bg: #6610f2;"
    height="300px"
    orientation="horizontal"
    :cols="12"
    :sections="[
        {
            id: 'introduction-h',
            title: 'Lorem ipsum dolor sit amet',
            content: section_content_introduction,
        },
        {
            id: 'features-h',
            title: 'Lorem',
            content: section_content_features,
        },
        {
            id: 'options-h',
            title: 'Lorem',
            content: section_content_options,
        },
            {
            id: 'usage-h',
            title: 'Lorem',
            content: section_content_usage,
        }
    ]"
/>




---

#### Stats

Statistics display with values and text.

<twig:block-stats
    class="my-4"
    :stats="[
        {
            value: '$40.000',
            text: 'Base price up to quota of 2.000 <a href=\'https://www.example.com/\' target=\'_blank\'>documents</a>'
        },
        {
            value: '$15',
            text: 'Price per extra document above quota'
        },
        {
            value: '24/7',
            text: 'Technical support available'
        },
        {
            value: '99.9%',
            text: 'Guaranteed uptime'
        }
    ]"
/>

<twig:block-stats
    class="my-4"
    :stats="[
        {
            value: '$40.000',
            text: 'Base price up to quota of 2.000 documents'
        },
        {
            value: '$15',
            text: 'Price per extra document above quota'
        },
        {
            value: '24/7',
            text: 'Technical support available'
        },
        {
            value: '99.9%',
            text: 'Guaranteed uptime'
        }
    ]"
    textPosition="top"
/>

<twig:block-stats
    class="my-4"
    :stats="[
        {
            value: '$40.000',
            text: 'Base price up to quota of 2.000 documents'
        },
        {
            value: '$15',
            text: 'Price per extra document above quota'
        },
        {
            value: '24/7',
            text: 'Technical support available'
        },
        {
            value: '99.9%',
            text: 'Guaranteed uptime'
        },
        {
            value: '99.9%',
            text: 'Guaranteed uptime'
        }
    ]"
/>

<twig:block-stats
    class="my-4"
    :stats="[
        {
            value: '1.000',
            text: 'Customers'
        },
        {
            value: '10',
            text: 'Years'
        },
        {
            value: '8/5',
            text: 'Technical support'
        },
        {
            value: '99.9%',
            text: 'Uptime'
        },
        {
            value: '5',
            text: 'Products'
        },
        {
            value: '3',
            text: 'Countries'
        }
    ]"
/>




---

#### Steps

Step-by-step guide component with variable steps and arrow design.

<twig:block-steps
    class="my-4"
    :steps="[
        {
            icon: 'fa-solid fa-list',
            title: 'Test Set',
            content: 'Standard DTE documents requested by the <a href=\'https://www.sii.cl/factura_electronica/factura_mercado/menu_certificacion.html\' target=\'_blank\'>SII</a> are sent for validation.'
        },
        {
            icon: 'fa-solid fa-file-lines',
            title: 'Simulation',
            content: 'Real DTE examples that the company will issue in production are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Exchange',
            content: 'XML files associated with the response to a DTE exchange are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-file-pdf',
            title: 'PDF Samples',
            content: 'PDFs of all DTE documents from the test set and simulation are sent to the SII. <a href=\'#\' class=\'btn btn-primary\'>Link</a>'
        }
    ]"
    arrowType="straight"
/>

<twig:block-steps
    class="my-4"
    :steps="[
        {
            icon: 'fa-solid fa-list',
            title: 'Test Set',
            content: 'Standard DTE documents requested by the <a href=\'https://www.sii.cl/factura_electronica/factura_mercado/menu_certificacion.html\' target=\'_blank\'>SII</a> are sent for validation.'
        },
        {
            icon: 'fa-solid fa-file-lines',
            title: 'Simulation',
            content: 'Real DTE examples that the company will issue in production are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Exchange',
            content: 'XML files associated with the response to a DTE exchange are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-file-pdf',
            title: 'PDF Samples',
            content: 'PDFs of all DTE documents from the test set and simulation are sent to the SII.'
        }
    ]"
/>

<twig:block-steps
    class="my-4"
    :steps="[
        {
            icon: 'fa-solid fa-list',
            title: 'Test Set',
            content: 'Standard DTE documents requested by the <a href=\'https://www.sii.cl/factura_electronica/factura_mercado/menu_certificacion.html\' target=\'_blank\'>SII</a> are sent for validation.'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Exchange',
            content: 'XML files associated with the response to a DTE exchange are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-file-pdf',
            title: 'PDF Samples',
            content: 'PDFs of all DTE documents from the test set and simulation are sent to the SII.'
        }
    ]"
    arrowType="straight"
/>

<twig:block-steps
    class="my-4"
    :steps="[
        {
            icon: 'fa-solid fa-list',
            title: 'Test Set',
            content: 'Standard DTE documents requested by the <a href=\'https://www.sii.cl/factura_electronica/factura_mercado/menu_certificacion.html\' target=\'_blank\'>SII</a> are sent for validation.'
        },
        {
            icon: 'fa-solid fa-arrows-left-right',
            title: 'Exchange',
            content: 'XML files associated with the response to a DTE exchange are sent to the SII.'
        },
        {
            icon: 'fa-solid fa-file-pdf',
            title: 'PDF Samples',
            content: 'PDFs of all DTE documents from the test set and simulation are sent to the SII.'
        }
    ]"
/>




---

#### Table

Data table component with styling options.

{# Basic table #}
<twig:block-table
    class="my-4"
    caption="Table"
    :headers="[
        [
            {'text': 'ID', 'scope': 'col', 'align': 'center'},
            {'text': 'Name', 'scope': 'col'},
            {'text': 'Email', 'scope': 'col'},
            {'text': 'Status', 'scope': 'col', 'align': 'center'}
        ]
    ]"
    :rows="[
        ['1', '<a href=\'https://www.example.com/\' target=\'_blank\'>John Smith</a>', 'john@example.com', 'Active'],
        ['2', 'Mary Johnson', 'mary@example.com', 'Inactive'],
        ['3', 'Charles Brown', 'charles@example.com', 'Pending']
    ]"
    :columns="[
        {'index': 0, 'width': '80px', 'align': 'center'},
        {'index': 3, 'align': 'center', 'class': 'fw-bold'}
    ]"
    :rowClasses="[
        {'col': 3, 'values': {
            'Active': 'table-success',
            'Inactive': 'table-danger',
            'Pending': 'table-warning'
        }}
    ]"
/>

{# Table with complex headers and footer #}
<twig:block-table
    class="my-4"
    caption="Sales Report 2024"
    :headers="[
        [
            {text: 'Region', scope: 'col', rowspan: '2'},
            {text: 'Quarterly Sales', scope: 'col', colspan: '4', class: 'text-center'},
        ],
        [
            {text: 'Q1', scope: 'col', align: 'end'},
            {text: 'Q2', scope: 'col', align: 'end'},
            {text: 'Q3', scope: 'col', align: 'end'},
            {text: 'Q4', scope: 'col', align: 'end'}
        ]
    ]"
    :rows="[
        ['North', '10,500', '12,300', '11,800', '13,200'],
        ['South', '8,900', '9,200', '9,800', '10,100'],
        ['East', '11,200', '11,500', '12,100', '12,800']
    ]"
    :footer="[
        [
            {text: 'Total', colspan: '1'},
            {text: '30,600', class: 'fw-bold text-end'},
            {text: '33,000', class: 'fw-bold text-end'},
            {text: '33,700', class: 'fw-bold text-end'},
            {text: '36,100', class: 'fw-bold text-end'}
        ]
    ]"
    :columns="[
        {width: '120px'},
        {align: 'end'},
        {align: 'end'},
        {align: 'end'},
        {align: 'end'}
    ]"
    :bordered="true"
    :striped="true"
    :hover="false"
/>

{# Table with actions and toggle #}
<twig:block-table
    class="my-4"
    :headers="[
        [
            {text: 'Product', scope: 'col'},
            {text: 'Category', scope: 'col'},
            {text: 'Stock', scope: 'col', align: 'center'},
            {text: 'Price', scope: 'col', align: 'end'}
        ]
    ]"
    :rows="[
        ['Laptop XPS', 'Computers', '15', '$1,299.99'],
        ['Wireless Mouse', 'Accessories', '45', '$29.99'],
        ['Monitor 27\'\'', 'Displays', '8', '$299.99']
    ]"
    :actions="[
        {
            text: 'Export to Excel',
            icon: 'fas fa-file-excel',
            url: '/export/excel'
        },
        {
            text: 'Export to PDF',
            icon: 'fas fa-file-pdf',
            url: '/export/pdf'
        },
        {type: 'divider'},
        {
            text: 'Print',
            icon: 'fas fa-print',
            onclick: 'window.print()'
        }
    ]"
    :toggleable="true"
    :visible="true"
    :maxHeight="300"
    :hover="false"
/>

{# Minimalist responsive table #}
<twig:block-table
    class="my-4"
    :headers="[
        [
            {text: '#', scope: 'col'},
            {text: 'Title', scope: 'col'},
            {text: 'Date', scope: 'col'},
            {text: 'Status', scope: 'col'}
        ]
    ]"
    :rows="[
        ['1', 'Document 1', '2024-02-22', '<span class=\'badge bg-success\'>Approved</span>'],
        ['2', 'Document 2', '2024-02-21', '<span class=\'badge bg-warning\'>Pending</span>'],
        ['3', 'Document 3', '2024-02-20', '<span class=\'badge bg-danger\'>Rejected</span>']
    ]"
    :small="true"
    :striped="false"
    :bordered="false"
    :hover="false"
/>




---

#### Tabs

Tabbed content interface, with horizontal and vertical layout.

{% set tab_content_1 %}
    <twig:block-text-image
        title="Lorem ipsum dolor sit amet"
        content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque sit amet commodo odio. Mauris sagittis consequat quam interdum laoreet. Vivamus pretium pellentesque ligula, eget euismod turpis maximus sed."
        :buttons="[
            {
                text: 'Learn more',
                url: 'https://www.example.com'
            },
            {
                text: 'Request a FREE trial period',
                url: 'https://www.example.com'
            }
        ]"
        image="/img/home/derafu-dev-programmer.png"
        :insideTabs="true"
    />
{% endset %}

{% set tab_content_2 %}
    <h2>Information</h2>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque sit amet commodo odio. Mauris sagittis consequat quam interdum laoreet. Vivamus pretium pellentesque ligula, eget euismod turpis maximus sed....</p>
{% endset %}

<twig:block-tabs
    class="my-4"
    :tabs="[
        {
            id: 'features',
            title: 'Features',
            icon: 'fa-solid fa-list',
            content: tab_content_1
        },
        {
            id: 'info',
            title: 'Information',
            icon: 'fa-solid fa-info-circle',
            content: tab_content_2
        }
    ]"
/>

<twig:block-tabs
    class="my-4"
    position="vertical"
    :withShadow="true"
    :cols="3"
    :tabs="[
        {
            id: 'features2',
            title: 'hello',
            icon: 'fa-solid fa-list',
            content: tab_content_1
        },
        {
            id: 'info2',
            title: 'Information',
            icon: 'fa-solid fa-info-circle',
            content: tab_content_2
        }
    ]"
/>




---

#### Team

Team members display with roles and social links.

<twig:block-team
    class="my-4"
    :cols="1"
    :members="[
        {
            name: 'John Doe',
            role: 'Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing <a href=\'https://www.example.com/\' target=\'_blank\'>elit.</a href>',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                },
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        }
    ]"
/>

<twig:block-team
    class="my-4"
    :cols="2"
    :members="[
        {
            name: 'John Doe',
            role: 'Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                },
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Jane Smith',
            role: 'Co-Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                }
            ]
        }
    ]"
/>

<twig:block-team
    class="my-4"
    :cols="3"
    :members="[
        {
            name: 'John Doe',
            role: 'Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                },
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Jane Smith',
            role: 'Co-Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Mike Johnson',
            role: 'Developer',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        }
    ]"
/>

<twig:block-team
    class="my-4"
    :cols="4"
    :members="[
        {
            name: 'John Doe',
            role: 'Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Jane Smith',
            role: 'Co-Founder',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Saul Goodman',
            role: 'HR',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-linkedin',
                    text: 'LinkedIn',
                    url: 'https://www.example.com'
                }
            ]
        },
        {
            name: 'Mike Johnson',
            role: 'Developer',
            image: '/img/home/derafu-dev-programmer.png',
            bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            links: [
                {
                    icon: 'fa-brands fa-github',
                    text: 'GitHub',
                    url: 'https://www.example.com'
                }
            ]
        }
    ]"
/>




---

#### Testimonials

Testimonials display with background and image.

<twig:block-testimonials
    class="my-4"
    :testimonials="[
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida.',
            author: 'John Doe',
            image: '/img/home/derafu-dev-programmer.png',
            note: 'Lorem ipsum',
            url: 'https://www.example.com'
        },
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida.',
            author: 'John Doe',
            note: 'Lorem ipsum',
            position: 'left'
        },
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida.',
            author: 'John Doe',
            image: '/img/home/derafu-dev-programmer.png',
            url: 'http://www.example.com',
            position: 'right'
        }
    ]"
/>

<twig:block-testimonials
    class="my-4"
    interval="2000"
    :testimonials="[
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet <a href=\'https://www.example.com/\' target=\'_blank\'>tempus gravida.</a href>',
            author: 'John Doe',
            image: '/img/home/derafu-dev-programmer.png',
            note: 'Lorem ipsum',
            url: 'http://www.example.com'
        },
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida.',
            author: 'John Doe',
            image: '/img/home/derafu-dev-programmer.png',
            url: 'http://www.example.com'
        }
    ]"
/>

<twig:block-testimonials
    class="my-4"
    :testimonials="[
        {
            background: '/img/home/derafu-dev-programmer.png',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend. Fusce aliquet tempus gravida.',
            author: 'John Doe',
            image: '/img/home/derafu-dev-programmer.png',
            note: 'Lorem ipsum'
        }
    ]"
/>




---

#### Text Image

Combined text and image layout.

<twig:block-text-image
    class="my-4"
    image="/img/home/derafu-dev-programmer.png"
    title="Lorem ipsum dolor sit amet"
    content="<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend.</p><p>Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare <a href='https://www.example.com/' target='_blank'>tellus</a> dignissim.</p>"
    :buttons="[
        {
            text: 'Example.com 1',
            url: 'https://www.example.com'
        },
        {
            text: 'Example.com 2',
            url: 'https://www.example.com'
        }
    ]"
/>

<twig:block-text-image
    class="my-4"
    image="/img/home/derafu-dev-programmer.png"
    imagePosition="left"
    title="Lorem ipsum dolor sit amet"
    content="<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend.</p><p>Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim.</p>"
    :buttons="[
        {
            text: 'Example.com',
            url: 'https://www.example.com'
        }
    ]"
/>




---

#### Text Video

Combined text and video layout.

<twig:block-text-video
    class="my-4"
    video="https://www.youtube.com/watch?v=GOAEIMx39-w"
    title="Lorem ipsum dolor sit amet"
    content="<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend.</p><p>Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare <a href='https://www.example.com/' target='_blank'>tellus</a> dignissim.</p>"
    :buttons="[
        {
            text: 'Example.com 1',
            url: 'https://www.example.com'
        },
        {
            text: 'Example.com 2',
            url: 'https://www.example.com'
        }
    ]"
/>

<twig:block-text-video
    class="my-4"
    videoPosition="left"
    video="https://www.youtube.com/watch?v=GOAEIMx39-w"
    title="Lorem ipsum dolor sit amet"
    content="<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi malesuada tellus velit, in fringilla turpis interdum aliquet. Donec eget neque sit amet orci gravida eleifend.</p><p>Fusce aliquet tempus gravida. Nam ullamcorper libero ac velit pharetra, in volutpat sem vulputate. Integer quis suscipit nibh, non tempor enim. Nulla ipsum leo, vulputate nec dolor nec, aliquet porttitor nibh. Donec maximus tellus vitae ornare dignissim.</p>"
    :buttons="[
        {
            text: 'Example.com',
            url: 'https://www.example.com'
        }
    ]"
/>




---

#### Timeline

Chronological event display with configurable alignment.

<twig:block-timeline
    class="my-4"
    linePosition="center"
    :events="[
        {
            date: '2023-06-15',
            title: 'Official Partnership',
            content: 'We become Official RPA Partner in Chile.',
            icon: 'fa-solid fa-handshake fa-fw'
        },
        {
            date: '2022-11',
            title: 'International Expansion',
            content: 'We started receiving requests from clients outside Chile.',
            icon: 'fa-solid fa-globe fa-fw'
        },
        {
            date: '2022-06',
            title: 'International Project',
            content: 'Product development for clients outside Chile.',
            icon: 'fa-solid fa-globe fa-fw'
        },
        {
            date: '2021-05',
            title: 'New Products',
            content: 'Creation of Software 1, Software 2 and <a href=\'https://www.example.com/\' target=\'_blank\'>Software 3</a>.',
            icon: 'fa-solid fa-briefcase fa-fw'
        }
    ]"
/>

<twig:block-timeline
    class="my-4"
    linePosition="left"
    :events="[
        {
            date: '2023-06-15',
            title: 'Official Partnership',
            content: 'We become Official RPA Partner in Chile.',
            icon: 'fa-solid fa-handshake fa-fw'
        },
        {
            date: '2022-11',
            title: 'International Expansion',
            content: 'We started receiving requests from clients outside Chile.',
            icon: 'fa-solid fa-globe fa-fw'
        },
        {
            date: '2022-06',
            title: 'International Project',
            content: 'Product development for clients outside Chile.',
            icon: 'fa-solid fa-globe'
        },
        {
            date: '2021-05',
            title: 'New Products',
            content: 'Creation of Software 1, Software 2 and <a href=\'https://www.example.com/\' target=\'_blank\'>Software 3</a>.',
            icon: 'fa-solid fa-briefcase'
        }
    ]"
/>

<twig:block-timeline
    class="my-4"
    linePosition="right"
    :events="[
        {
            date: '2023-06-15',
            title: 'Official Partnership',
            content: 'We become Official RPA Partner in Chile.',
            icon: 'fa-solid fa-handshake'
        },
        {
            date: '2022-11',
            title: 'International Expansion',
            content: 'We started receiving requests from clients outside Chile.',
            icon: 'fa-solid fa-globe'
        },
        {
            date: '2022-06',
            title: 'International Project',
            content: 'Product development for clients outside Chile.',
            icon: 'fa-solid fa-globe fa-fw'
        },
        {
            date: '2021-05',
            title: 'New Products',
            content: 'Creation of Software 1, Software 2 and <a href=\'https://www.example.com/\' target=\'_blank\'>Software 3</a>.',
            icon: 'fa-solid fa-briefcase fa-fw'
        }
    ]"
/>

<twig:block-timeline
    class="my-4"
    linePosition="left"
    :events="[
        {
            date: '2023',
            title: 'Official Partnership',
            content: 'We become Official RPA Partner in Chile.',
            icon: 'fa-solid fa-handshake'
        },
        {
            date: '2022',
            title: 'International Expansion',
            content: 'We started receiving requests from clients outside Chile.',
            icon: 'fa-solid fa-globe'
        },
        {
            date: '2022',
            title: 'International Project',
            content: 'Product development for clients outside Chile.',
            icon: 'fa-solid fa-globe fa-fw'
        },
        {
            date: '2021',
            title: 'New Products',
            content: 'Creation of Software 1, Software 2 and <a href=\'https://www.example.com/\' target=\'_blank\'>Software 3</a>.',
            icon: 'fa-solid fa-briefcase fa-fw'
        }
    ]"
/>




---

#### Title

Customizable title component.

<twig:block-title
    class="my-4"
    title="Title"
    subtitle="Lorem ipsum dolor sit amet, consectetur <a href='https://www.example.com/' target='_blank'>adipiscing elit.</a>"
/>

<twig:block-title
    class="my-4"
    title="Title"
    subtitle="Lorem ipsum dolor sit amet, consectetur <a href='https://www.example.com/' target='_blank'>adipiscing elit.</a>"
    :border="true"
/>




---

#### Toast

Toast notifications with customizable types.

{% set types = ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark'] %}
{% for type in types %}
    <twig:block-toast
        class="my-2"
        type="{{ type }}"
        title="Toast type: {{ type }}"
        content="Lorem ipsum dolor sit amet, consectetur <a href='https://www.example.com/' target='_blank'>adipiscing elit.</a href>"
        time="5 mins ago"
    />
{% endfor %}




---

#### Video Grid

Grid layout for multiple videos.

<twig:block-video-grid
    class="my-4"
    :cols="3"
    :videos="[
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            title: 'Lorem ipsum',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore <a href=\'https://www.example.com/\' target=\'_blank\'>magna aliqua.</a>',
            buttonText: 'Learn more',
            buttonUrl: '#'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            title: 'Lorem ipsum',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
            buttonText: 'Learn more',
            buttonUrl: ''
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w',
            title: 'Lorem ipsum',
            content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
            buttonText: 'Learn more',
            buttonUrl: '#'
        }
    ]"
/>

<twig:block-video-grid
    class="my-4"
    :cols="2"
    :videos="[
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w'
        },
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w'
        }
    ]"
/>

<twig:block-video-grid
    class="my-4"
    :cols="1"
    :videos="[
        {
            video: 'https://www.youtube.com/watch?v=GOAEIMx39-w'
        }
    ]"
/>




---

#### Video

Video player component.

<twig:block-video
    class="my-4"
    size="normal"
    align="center"
    title="Lorem ipsum dolor sit amet"
    video="https://www.youtube.com/watch?v=GOAEIMx39-w"
    content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat <a href='https://www.example.com/' target='_blank'>nulla pariatur.</a>"
    :buttons="[
        {
            text: 'Learn more',
            url: '#'
        }
    ]"
/>

<twig:block-video
    class="my-4"
    size="small"
    align="center"
    title="Lorem ipsum dolor sit amet"
    video="https://www.youtube.com/watch?v=GOAEIMx39-w"
    content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur."
    :buttons="[
        {
            text: 'Learn more',
            url: '#'
        }
    ]"
/>




---

### Translations

Translations

# Translations

`Derafu\Twig\Extension\TranslationExtension` brings message translation to
Twig templates, powered by [`derafu/translation`](https://www.derafu.dev/docs/core/translation).
It mirrors the structure of Symfony's own Twig translation integration (a
`trans` filter, a `t()` function, a `{% trans %}` block tag, and a
`{% trans_default_domain %}` tag), but without depending on
`symfony/twig-bridge` — that package's only hard requirements are
`symfony/translation-contracts` and `twig/twig`, but it still ships 55 files
(~500KB) of Csrf, Form, HttpKernel, Security, Serializer, and Workflow
extensions this library has no use for. `TranslationExtension` depends only
on `derafu/translation` instead.

Like the rest of this ecosystem, it does nothing unless you explicitly wire
a translator — without one, everything still renders, using ICU formatting
directly instead of a translation catalogue.

## Registering It

Pass an instance in the `extensions` option, the same way you would add
any other Twig extension to `TwigCreator`/`TwigService`:

```php
use Derafu\Twig\Extension\TranslationExtension;
use Derafu\Twig\Service\TwigService;
use Derafu\Translation\TranslatorFactory;

$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    fallbackLocales: ['es', 'en'],
);

$twigService = new TwigService([
    'extra' => false, // Keeps this example scoped to just this extension.
    'extensions' => [
        new TranslationExtension($translator, 'app+intl-icu'),
    ],
]);
```

The constructor takes three optional arguments:

```php
final class TranslationExtension extends AbstractExtension
{
    public function __construct(
        ?TranslatorInterface $translator = null,
        ?string $domain = null,
        ?string $locale = null,
    ) {
    }
}
```

`$domain`/`$locale` are fallbacks used only when a call site doesn't specify
its own — they are never assumed or required. Prefer
`{% trans_default_domain %}` (below) to set a domain per template instead of
relying on this constructor argument, since a single `TranslationExtension`
instance is shared by every template rendered through that Twig
`Environment`.

## The `trans` Filter

```twig
{{ 'Hello {name}!'|trans({'name': user.name}) }}
{{ 'Hello {name}!'|trans({'name': user.name}, 'app+intl-icu') }}
{{ 'Hello {name}!'|trans({'name': user.name}, 'app+intl-icu', 'fr') }}
```

Placeholders use ICU syntax (`{name}`), the same convention used everywhere
else in this ecosystem — never `%name%`. The domain should generally carry
the `+intl-icu` suffix (see
[the ICU MessageFormat guide](https://www.derafu.dev/docs/core/translation)); without it, the
underlying translator falls back to plain `strtr()`, which does not
understand `{name}`-style placeholders.

## The `t()` Function

```twig
{% set message = t('Hello {name}!', {'name': user.name}, 'app+intl-icu') %}
```

Builds a `Derafu\Translation\TranslatableMessage` without translating it —
useful to hand a translatable value to PHP code that will translate it
later, possibly with a different locale.

**Printing it directly does not use the configured translator.** `{{ t(...) }}`
casts the object to a string via `__toString()`, which always applies ICU
formatting only — the same fallback used when no translator is configured
at all. To translate a message immediately within a template, use the
`trans` filter or the `{% trans %}` tag below, both of which call the
translator directly; reach for `t()` only when the translation needs to
happen somewhere else, later.

## The `{% trans %}` Block Tag

```twig
{% trans %}Save{% endtrans %}
{% trans with {'name': user.name} %}Hello {name}!{% endtrans %}
{% trans with {'name': user.name} from 'app+intl-icu' %}Hello {name}!{% endtrans %}
{% trans with {'name': user.name} from 'app+intl-icu' into 'fr' %}Hello {name}!{% endtrans %}
```

Unlike Symfony's own `trans` tag, parameters are **never** auto-detected by
scanning the message text for `%name%` occurrences — that convention
predates ICU and is incompatible with it. Here, parameters always go
through `with`, explicitly, and placeholders in the text are ICU (`{name}`),
matching the `trans` filter.

The message must be plain text. Interpolating a Twig expression
(`{% trans %}Hello {{ user.name }}!{% endtrans %}`) raises a `SyntaxError`
at compile time: the translation id would depend on a runtime value and
would never match an entry in the translation catalogue.

> **Never use the bare `#` ICU plural shorthand — in any of `trans`, `t()`,
> or `{% trans %}`.** A literal `{#` in raw template text is always lexed
> by Twig itself as the start of a `{# comment #}`, before this extension's
> code ever runs, breaking the whole template outright (or, worse, silently
> consuming content up to the next stray `#}`). That alone rules out the
> `{% trans %}` tag for any ICU plural/select message using `#`
> (`{count, plural, one {# item} other {# items}}`), since its body is raw
> template text.
>
> A `{#` inside a Twig *string literal* — e.g. the message argument to the
> `trans` filter — is lexed literally and is safe **when only Twig's own
> extensions are registered**. That safety is not guaranteed once
> `symfony/ux-twig-component` is also registered (the runtime behind
> `<twig:...>` component tags): a real case surfaced where the exact same
> `{#`, inside a `trans` filter's string argument, in a template that both
> used a `<twig:...>` component and `{% extends %}`, broke the template
> with an unrelated-looking error
> (`A template that extends another one cannot include content outside
> Twig blocks`) — nothing in the message pointed at `{#` as the cause. The
> exact mechanism inside `ux-twig-component` was not identified (it is a
> third-party dependency), but bisection on the real template confirmed
> the `{#` substring as the trigger.
>
> **The rule that holds regardless of which extensions are registered:**
> never write the bare `#` shorthand in an ICU plural/select message. This
> applies to `trans`, `t()`, and `{% trans %}` alike.
>
> The fix is **not** to reference the same argument again as `{count}`:
> real ICU (PHP's `MessageFormatter`, used both by the no-translator
> fallback and, through Symfony, by a real translator) throws
> `U_ARGUMENT_TYPE_MISMATCH` when the same argument name is used both as
> the plural selector and as a literal reference inside a branch — `#`
> exists specifically to avoid that conflict, it is not interchangeable
> with a named reference to the same argument. The safe fix is to pass the
> same value under **two different argument names**: one used only for
> plural selection, one only for display:
>
> ```twig
> {{ '{count, plural, one {{n} item} other {{n} items}}'|trans({'count': items|length, 'n': items|length}, 'app+intl-icu') }}
> ```

## The `{% trans_default_domain %}` Tag

Sets a default domain for every `trans` filter call and `{% trans %}` block
that follows it in the same template or block, and doesn't have its own
domain:

```twig
{% trans_default_domain 'app+intl-icu' %}

{{ 'Save'|trans }}
{% trans %}Cancel{% endtrans %}
{{ 'Delete'|trans({}, 'admin+intl-icu') }} {# explicit domain still wins #}
```

The domain doesn't need to be a literal string — a dynamic expression works
too, evaluated once regardless of how many `trans` calls use it:

```twig
{% trans_default_domain app.locale == 'es' ? 'es+intl-icu' : 'en+intl-icu' %}
```

The scope is the enclosing template or `{% block %}` — a
`trans_default_domain` set inside a block does not leak to the rest of the
template, and the template's own domain (if any) is restored once the block
ends.

## Fallback Without a Translator

`trans`, `t()`, and `{% trans %}` all work with no `Translator` configured
at all — every one of them falls back to
`TranslatableMessage::__toString()`, which still applies ICU formatting
(interpolating `{name}`-style placeholders correctly) even though nothing
gets translated:

```twig
{# No translator registered: renders "Hello Juan!" verbatim. #}
{{ 'Hello {name}!'|trans({'name': user.name}) }}
```

This is unlike `symfony/twig-bridge`, whose own no-translator fallback uses
a plain `strtr()`-based identity translator that does not understand ICU
placeholders at all.




---

## Markdown Project

Derafu Markdown

# Derafu Markdown




---

### Introduction

PHP Markdown Rendering Library

# PHP Markdown Rendering Library

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/markdown/main)
![CI Workflow](https://github.com/derafu/markdown/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/markdown)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/markdown)
![Total Downloads](https://poser.pugx.org/derafu/markdown/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/markdown/d/monthly)

**Derafu Markdown** is a PHP library that provides a powerful Markdown rendering engine with support for advanced extensions. It leverages `league/commonmark` and additional features to enhance Markdown processing for documentation, blogs, and dynamic content.

## Features

- 📝 **Full Markdown Support**: Standard CommonMark and GitHub Flavored Markdown (GFM).
- 📚 **Extended Capabilities**: TOC, footnotes, mentions, permalinks, embeds, and more.
- 🎨 **Custom Attributes**: Add CSS classes and IDs to elements.
- 🔗 **External Link Handling**: Open in new tabs, add `nofollow`, etc.
- 🛠 **Highly Configurable**: Fine-tune Markdown behavior with options.
- 📦 **Easy Integration**: Works standalone or within any PHP project.
- 🏷 **MIT Licensed**: Open-source and free to use.

> [!INFO] Admonition Extension
>
> This library includes an admonition extension to process common messages. For example: tip, info and warning.

## Installation

Install via Composer:

```bash
composer require derafu/markdown
```

## Usage

### Basic Rendering

```php
use Derafu\Markdown\Service\MarkdownCreator;
use Derafu\Markdown\Service\MarkdownService;

$markdownService = new MarkdownService(new MarkdownCreator());

echo $markdownService->render('example.md');
```

### Rendering with Layout

```php
$markdownService->render('example.md', [
    '__view_layout' => 'layout.php',
    '__view_title' => 'My Markdown Page'
]);
```

## Available Extensions

### ✅ **GitHub Flavored Markdown (GFM)**
- Task lists:

```markdown
- [x] Completed
- [ ] Pending
```

- Tables:

```markdown
| Name  | Age |
|-------|-----|
| John  | 25  |
| Alice | 30  |
```

### 📌 **Table of Contents (TOC)**

```markdown
## Section 1
## Section 2
```

### 🔗 **Header Permalinks**

```markdown
### Important Header
```

Generates an anchor link like `#important-header`.

### 📝 **Footnotes**

```markdown
Here is a reference[^1].

[^1]: Footnote text.
```

### 🏷 **Custom Attributes**

```markdown
### Title {.custom-class}
```

### 🔗 **External Links Handling**

```markdown
[Google](https://www.google.com)
```

Adds attributes like `rel="noopener noreferrer"`.

### 📌 **Mentions & Issues**

```markdown
Hello @user, check issue #123.
```

Links to GitHub profiles and issues.

### 🎥 **Embeds**

```markdown
https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

Automatically embeds videos.

## Advanced Configuration

You can customize the behavior of Markdown processing by passing an options array to `MarkdownCreator`:

```php
$options = [
    'environment' => [
        'mentions' => [
            '@' => ['generator' => 'https://github.com/%s'],
            '#' => ['generator' => 'https://github.com/derafu/markdown/issues/%d']
        ]
    ]
];

$creator = new MarkdownCreator($options);
```

## Template Metadata Support

Markdown templates can include metadata in YAML format:

```markdown
---
__view_title: "Markdown Template Guide"
---
```




---

### Guide

Template Usage Guide

# Template Usage Guide

This document is designed to help you maximize the capabilities of Markdown within your application. By default, various extensions are configured to expand Markdown functionalities, allowing you to create dynamic and well-styled content easily.

## 1. Introduction to Markdown

Markdown is a lightweight markup language that allows you to write plain text documents and easily convert them into HTML. Its simple syntax makes it a popular choice for documentation, blogs, and other web applications. Below are some basic Markdown examples:

### Headings

```markdown
# Level 1 Heading

## Level 2 Heading

### Level 3 Heading
```

### Emphasis

```markdown
**Bold Text**

*Italic Text*

~~Strikethrough Text~~
```

### Lists

```markdown
- Unordered list item
- Another item

1. Ordered list item
2. Another item
```

### Links and Images

```markdown
[Link to Google](https://www.google.com)

![Alternative Image Text](https://www.example.com/image.jpg)
```

## 2. Markdown Extensions

You can extend Markdown capabilities with various extensions that enhance your content. Below is a description of the included extensions and how to use them.

### 2.1. GitHub Flavored Markdown (GFM)

GFM is an extended version of Markdown used on GitHub, adding features such as tables, task lists, and syntax-highlighted code blocks. To use GFM, simply write your Markdown content, and the extension will handle the rest.

#### Examples:

**Task Lists**:

```markdown
- [x] Completed task
- [ ] Pending task
```

**Tables**:

```markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
```

**Code Blocks**:

```markdown
```php
echo "This is PHP code";
```

### 2.2. Automatic Table of Contents (TOC)

The Table of Contents (TOC) extension allows you to automatically generate an index based on the document's headings. To include a TOC, simply place `[TOC]` where you want it to appear.

#### Example:

```markdown
## Section 1
Content of section 1.

## Section 2
Content of section 2.
```

### 2.3. Header Permalinks

Permalinks allow headers to have permanent links that users can copy and share easily. This extension automatically generates permalinks for all headers.

#### Example:

```markdown
### Important Header
```

This will automatically generate the permalink `#content-important-header`.

### 2.4. Footnotes

Footnotes allow you to add references or clarifications without disrupting the text flow. Use the syntax `[^1]` to mark a footnote and define its content at the bottom of the document.

#### Example:

```markdown
Here is a phrase with a footnote[^1].

[^1]: This is the footnote, appearing at the end of the document.
```

### 2.5. Definitions

Definition lists allow you to create glossaries or descriptive lists easily.

#### Example:

```markdown
Term 1
: Definition for term 1.

Term 2
: Definition for term 2.
```

### 2.6. Custom Attributes

This extension allows you to add custom HTML attributes to specific Markdown elements.

#### Example:

```markdown
### Header with Custom ID {.my-css-class}
```

### 2.7. External Links

You can define how external links are handled. You can configure them to open in a new window, add attributes like `nofollow`, and more.

#### Example:

```markdown
[External Link](https://www.google.com)
```

This will generate a link that opens in a new window with additional attributes like `rel="noopener noreferrer"`.

### 2.8. Mentions

Mentions allow you to link, by default, to GitHub profiles or issues directly from Markdown.

#### Example:

```markdown
Hello @user, please check issue #123.
```

This will generate links to `https://github.com/user` and `https://github.com/derafu/markdown/issues/123`.

### 2.9. Embeds

The embed extension allows you to insert content from sites like YouTube directly into your document.

#### Example:

```markdown
https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

This will embed the YouTube video instead of just displaying the link.

## 3. Advanced Options

Check the `MarkdownCreator` service to see the extensive customization options available for handling Markdown in your application. You can modify aspects such as:

- ID prefixes for permalinks.
- Custom styles for footnotes and tables.
- Advanced settings for mentions and embeds.

### Assigning Options

You must assign options when creating the `MarkdownCreator` service by passing an array with the options you want to modify.

Example:

```php
$options = [
    'environment' => [
        'mentions' => [
            '@' => [
                'prefix' => 'https://github.com/',
                'pattern' => '[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}(?!\w)',
                'generator' => 'https://github.com/%s',
            ],
            '#' => [
                'prefix' => '#',
                'pattern' => '\d+',
                'generator' => 'https://github.com/derafu/markdown/issues/%d',
            ],
        ],
    ],
];
$creator = new MarkdownCreator($options);
```

## 4. Template Metadata Block

Markdown templates allow the inclusion of a metadata block placed at the beginning of the file. These metadata entries are in `YAML` format, and all defined keys will be passed to the rendered layout and available as extracted variables in it.

Example:

```markdown
---
__view_title: "Markdown Template Usage Guide"
---
```

With this metadata block, the `__view_title` index will be assigned to the layout data and can be used later as a variable within it.

## 5. Conclusion

The Markdown renderer used by this library, along with the preconfigured extensions, provides a powerful Markdown template rendering engine that allows you to create rich and dynamic documents effortlessly. With support for various extensions and advanced settings, you can fully customize the Markdown experience in your application.




---

## Form Project

Derafu Form

# Derafu Form




---

### Introduction

Declarative Forms, Seamless Rendering

# Declarative Forms, Seamless Rendering

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/form/main)
![CI Workflow](https://github.com/derafu/form/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/form)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/form)
![Total Downloads](https://poser.pugx.org/derafu/form/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/form/d/monthly)

A modern PHP form library that leverages a declarative, schema-based approach to form definition and rendering, compatible with JSON Forms while providing a powerful backend-centric workflow.

> [!NOTE] WIP
>
> Work In Progress.

## Key Features

- **Schema-Based Form Definition**: Define forms using structured arrays that clearly separate data schemas from UI layouts.
- **Backend-First Approach**: Built for PHP developers who want control over form generation with minimum effort.
- **Symfony-Compatible Twig Extensions**: Familiar syntax for Symfony developers, minimizing learning curve.
- **Decoupled Rendering System**: Separate your form logic from its presentation with specialized renderers.
- **JSON Forms Compatibility**: Define once, use anywhere - same schema can be used with frontend JSON Forms library.
- **Automatic Form Generation**: Generate form UI schemas automatically from your data models.
- **Extensible Architecture**: Easily add custom types, layouts and renderers.
- **Translatable, Optionally**: Validation error messages and input action
  labels (show/hide password, copy, etc.) can be translated by wiring an
  optional translator — see [Translations](translations).

## Why Choose This Library?

### Compared to Traditional PHP Form Libraries

Traditional PHP form libraries often tightly couple form definition with HTML generation, making it difficult to separate concerns. This library takes a different approach:

1. **Declarative Rather Than Imperative**: Define _what_ your form should be rather than _how_ it should be built, step by step.
2. **Clear Separation of Concerns**: Schema (data structure) is separate from UI schema (presentation) and data (values).
3. **Powerful Layouts Without HTML Knowledge**: Create complex, multi-column layouts without writing HTML.

### Compared to Frontend-Only Solutions

Unlike frontend-only form builders, this library:

1. **Keeps Validation Logic Server-Side**: Where it belongs for security-critical applications.
2. **Provides PHP-Native Form Definition**: No need to write JavaScript to define your forms.
3. **Works With or Without JavaScript**: Generate the same forms for both traditional and SPA applications.

## Installation

Install the library using Composer:

```shell
composer require derafu/form
```

## Basic Usage

### Creating a Simple Form

```php
// Define the form structure.
$definition = [
    'schema' => [
        'type' => 'object',
        'properties' => [
            'name' => [
                'type' => 'string',
                'title' => 'Full Name',
            ],
            'email' => [
                'type' => 'string',
                'format' => 'email',
                'title' => 'Email Address',
            ],
        ],
        'required' => ['name', 'email'],
    ],
    'uischema' => [
        'type' => 'VerticalLayout',
        'elements' => [
            [
                'type' => 'Control',
                'scope' => '#/properties/name',
            ],
            [
                'type' => 'Control',
                'scope' => '#/properties/email',
            ],
        ],
    ],
    'data' => [
        'name' => '',
        'email' => '',
    ],
];

// Create the form.
$form = $formFactory->create($definition);
```

### Rendering with Twig

```twig
{# Simple rendering of the entire form. #}
{{ form(form) }}

{# Or with more control over individual components. #}
{{ form_start(form) }}
    {{ form_row(form.fields.name) }}
    {{ form_row(form.fields.email) }}
    <button type="submit" class="btn btn-primary">Submit</button>
{{ form_end(form) }}
```

## Automatic Schema Generation

The library can automatically generate a schema from your data:

```php
$definition = [
    'data' => [
        'name' => 'John Doe',
        'email' => 'john.doe@example.com',
        'age' => 34,
        'birthdate' => "1990-01-01",
    ],
];

// Schema and UI schema will be automatically generated.
$form = $formFactory->create($definition);
```

## Integration with JSON Forms

This library's form definitions are compatible with the [JSON Forms](https://jsonforms.io) JavaScript library, allowing you to use the same definitions for both server-side and client-side rendering:

```html
<div id="json-form-container"></div>
```

```javascript
// https://raw.githubusercontent.com/derafu/form/refs/heads/main/assets/js/jsonforms-viewer.js
import './jsonforms-viewer.js';

// Render the form and save the reference.
const formDefinition = {{ jsonFormsDefinition | json_encode | raw }};
const formInstance = window.renderJsonForm('json-form-container', formDefinition);
// You can now use `formInstance` to get the form data or its errors.
```

### Development Requirements

To render forms using JSON Forms you must install:

```shell
npm install @jsonforms/core @jsonforms/react @jsonforms/material-renderers \
    react react-dom @mui/material @emotion/react @emotion/styled
```

## Form Layouts

The UI schema supports various layout types by default:

- **VerticalLayout**: Fields stacked vertically.
- **HorizontalLayout**: Fields arranged horizontally.
- **Group**: Logical grouping of fields, often with a label.
- **Categorization**: Tab-based layouts for complex forms.

Example:

```php
$uischema = [
    'type' => 'VerticalLayout',
    'elements' => [
        [
            'type' => 'Group',
            'label' => 'Personal Information',
            'elements' => [
                ['type' => 'Control', 'scope' => '#/properties/name'],
                ['type' => 'Control', 'scope' => '#/properties/email'],
            ],
        ],
        [
            'type' => 'Group',
            'label' => 'Address',
            'elements' => [
                ['type' => 'Control', 'scope' => '#/properties/street'],
                ['type' => 'Control', 'scope' => '#/properties/city'],
            ],
        ],
    ],
];
```




---

### Translations

Translations

# Translations

`derafu/form` has two independent, optional translation surfaces. Both are
powered by [`derafu/translation`](https://www.derafu.dev/docs/core/translation), and both do
nothing unless you explicitly wire a translator — without one, everything
renders in English exactly as before.

## 1. Validation Error Messages

`FormDataProcessor` runs field values through
[`derafu/data-processor`](https://www.derafu.dev/docs/data/data-processor) rules. When a rule
fails, it throws a `Derafu\DataProcessor\Exception\ValidationException` (or
one of the other translatable exceptions from that package — see
[its Translations guide](https://www.derafu.dev/docs/data/data-processor)). `FormDataProcessor`
accepts an optional translator and locale; when given, it translates each
error before adding it to the result:

```php
final class FormDataProcessor implements FormDataProcessorInterface
{
    public function __construct(
        FormRulesResolverInterface $resolver,
        ProcessorInterface $processor,
        UiSchemaRuleEvaluatorInterface $evaluator = new UiSchemaRuleEvaluator(),
        ?TranslatorInterface $translator = null,
        ?string $locale = null,
    ) {
    }
}
```

Without a translator, `getErrors()` returns the untranslated (English)
messages — the exact same behavior as before this parameter existed.

## 2. Input Action Labels

Controls rendered with the `Control` UI schema type can declare
`options.actions` — input-group buttons like "show/hide password",
"generate a random password", or "copy the field's value". Their labels
(and the default copy confirmation message) are resolved by
`InputActionResolver`, which also accepts an optional translator:

```php
final class InputActionResolver
{
    public function __construct(
        ?TranslatorInterface $translator = null,
        ?string $locale = null,
    ) {
    }
}
```

An explicit `label` or `message` given directly in `options.actions` is
always used as-is and never translated — only the three built-in defaults
are:

```php
[
    'type' => 'Control',
    'scope' => '#/properties/password',
    'options' => [
        'actions' => ['toggle-password'],
    ],
]
```

`InputActionResolver` isn't wired into the rendering pipeline directly —
`ElementRendererProvider` (used internally by `FormRendererFactory`)
forwards it to `ControlRenderer`. To use a translator-aware resolver, pass
your own `ElementRendererProvider` via the `element_renderers` factory
option (see [Activating It](#activating-it-plain-php) below).

## What Ships

`derafu/form` includes:

- `resources/translations/form+intl-icu.es.php` — a Spanish translation
  for the four strings `InputActionResolver` can produce (validation error
  messages come from `derafu/data-processor`'s own translations instead —
  `derafu/form` doesn't duplicate them).
- `Derafu\Form\Translation\FormTranslationResourceProvider` — a
  `TranslationResourceProviderInterface` implementation pointing at that
  directory.

Neither does anything on its own — `derafu/form` is a library, it doesn't
build or own a `Translator`.

## Activating It (Plain PHP)

```php
use Derafu\DataProcessor\ProcessorFactory;
use Derafu\DataProcessor\Translation\DataProcessorTranslationResourceProvider;
use Derafu\Form\Processor\FormDataProcessor;
use Derafu\Form\Processor\FormRulesResolver;
use Derafu\Form\Translation\FormTranslationResourceProvider;
use Derafu\Translation\TranslatorFactory;

$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    fallbackLocales: ['es', 'en'],
    resourceProviders: [
        new DataProcessorTranslationResourceProvider(), // Validation error messages.
        new FormTranslationResourceProvider(),           // Input action labels.
    ],
);

$processor = new FormDataProcessor(
    new FormRulesResolver(),
    ProcessorFactory::create(),
    translator: $translator,
    locale: 'es',
);
```

For the action labels, build the renderer with a translator-aware
`ElementRendererProvider`:

```php
use Derafu\Form\Factory\FormRendererFactory;
use Derafu\Form\Renderer\ElementRendererProvider;
use Derafu\Form\Renderer\Support\InputActionResolver;

$formRenderer = FormRendererFactory::create([
    'element_renderers' => new ElementRendererProvider(
        actionResolver: new InputActionResolver($translator, 'es'),
    ),
]);
```

## Activating It (Dependency Injection)

If your application uses `symfony/dependency-injection`, import all three
recipe files. `form-services.yaml` already registers `InputActionResolver`
and `ElementRendererProvider` as autowired services, and wires
`FormRendererInterface`'s `element_renderers` option to that
`ElementRendererProvider` — nothing extra to configure beyond registering
your own `Translator`:

```yaml
imports:
    - { resource: '../vendor/derafu/translation/resources/config/translation-services.yaml' }
    - { resource: '../vendor/derafu/data-processor/resources/config/data-processor-services.yaml' }
    - { resource: '../vendor/derafu/form/resources/config/form-services.yaml' }

services:
    Symfony\Component\Translation\Translator:
        factory: ['Derafu\Translation\TranslatorFactory', 'create']
        arguments:
            $defaultLocale: 'es'
            $fallbackLocales: ['es', 'en']
            $resourceProviders: !tagged_iterator derafu_translation.resource_provider
```

Both `DataProcessorTranslationResourceProvider` and
`FormTranslationResourceProvider` are already tagged
`derafu_translation.resource_provider` in their respective recipe files, so
they're picked up automatically. `FormDataProcessor` and
`InputActionResolver` both autowire `?TranslatorInterface`, so they resolve
to the `Translator` above via the alias `translation-services.yaml`
provides — no explicit argument wiring needed for either of them.




---

### Examples

Examples of how to use the form component.

# Form Examples




---

#### From Data

The simplest form, created from data only.






---

#### Control

The default controls provided by the form library.






---

#### User Registration

Form to create a new user account.






---

#### User Login

A user login form with username, password and 2FA options.






---

#### User Profile with Cards

User profile form with grouped sections in cards.






---

#### User Profile with Tabs

User profile form with tabs and cards.






---

#### Setup Wizard

Multi-step wizard for account setup.






---

#### Invoice Issuance

Form for creating invoices with basic fields and line items.






---

#### Advanced Invoice Search

Complex search form for filtering invoices with conditional fields.






---

#### E-Invoicing Configuration

Comprehensive configuration form for electronic invoicing.






---

#### Contact Form

Simple contact form with default values and validation.






---

#### User Registration

Complex user registration form with nested fields and validation.






---

#### Collection

Collections and arrays in forms.






---

#### Editors

Different editors using controls.






---

#### Product Ecommerce

Product creation form with data processing rules.






---

#### Rules

JSON Forms rules in UI Schema.






---

#### Cascade

Select options in a cascade.






---

## Contact Form

Contact Form

# Contact Form

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/contact-form/main)
![CI Workflow](https://github.com/derafu/contact-form/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/contact-form)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/contact-form)
![Total Downloads](https://poser.pugx.org/derafu/contact-form/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/contact-form/d/monthly)

## Requirements

The`derafu/form` and `derafu/data-processor` packages installed and configured in `services.yaml`.

Check the configuration in the [website skeleton](https://github.com/derafu/website/blob/main/config/services.yaml).

## Quick Start

Install the package:

```shell
composer require derafu/contact-form
```

Import the routes to your `routes.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/contact-form/resources/config/contact-form-routes.yaml' }
```

Import the services to your `services.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/contact-form/resources/config/contact-form-services.yaml' }
```

Copy the `templates/contact/index.html.twig` and `templates/contact/success.html.twig` to your project.

If you want to use the default templates (and not copy them), add the templates path to your service configuration:

```yaml
Derafu\Renderer\Contract\RendererInterface:
    factory: ['Derafu\Renderer\Factory\RendererFactory', 'create']
    lazy: true
    arguments:
        $options:
            paths:
                - '%kernel.project_dir%/vendor/derafu/contact-form/resources/templates'
```

Configure the environment variables:

```yaml
# Source of the form for identifying it in the webhook.
# Useful for multiple forms in the same webhook.
FORM_CONTACT_SOURCE=derafu.dev

# URL and secret key for processing the contact form.
# Get the URL from the webhook service you are using.
# The secret key will be used to sign the payload using HMAC.
FORM_CONTACT_WEBHOOK_URL=
FORM_CONTACT_WEBHOOK_SECRET_KEY=

# Site and secret key for protect forms with captcha.
# Get the keys from https://www.hcaptcha.com/
CAPTCHA_SITE_KEY=
CAPTCHA_SECRET_KEY=
```




---

## JS Project

Derafu JS

# Derafu JS




---

### Introduction

Why use a JS framework if we can do all from scratch?

# Why use a JS framework if we can do all from scratch?

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/js/main)
![CI Workflow](https://github.com/derafu/js/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/js)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/js)

This library provides a collection of utility functions for common web development tasks, organized into modular components for better maintainability and flexibility.

## Structure

The library is organized into the following modules:

### Main Modules

- `src/derafu.js` - Main module (exports all functions under the `derafu` namespace).

### Core Modules

- `src/tabs.js` - Tab management functions.
- `src/ui.js` - User interface functions (popups, tables, notifications, copy/paste, etc.).
- `src/utils.js` - Basic utility functions (password generation, cookies, language detection, number formatting, etc.).

### Validation Modules

- `src/validation/l10n-cl.js` - Chilean validation functions (RUT validation, etc.).

### Form Modules

- `src/form/fields.js` - Form field management functions.
- `src/form/tables.js` - Dynamic table functions.
- `src/form/validation.js` - Form validation functions.

### Compatibility Modules

- `src/__.js` - Main compatibility layer (exports all functions under the `__` namespace).
- `src/form.js` - Form compatibility layer (exports all form functions under the `Form` namespace).

## Quick Start

Import using the CDN of the module you need, for example UI module:

```html
<script src="https://cdn.jsdelivr.net/npm/derafu-js@0.1.0/src/ui.js"></script>
```

Then use the function you need, for example notify function:

```javascript
UI.notify('Hello World!');
```

**Note**: Remember to load the dependencies first, in this example notyf is used for notifications.

## Usage

### Browser Usage

Load the modules in the correct order:

```html
<!-- Load individual modules -->
<script src="src/utils.js"></script>
<script src="src/ui.js"></script>
<script src="src/validation/l10n-cl.js"></script>
<script src="src/tabs.js"></script>
<script src="src/form/validation.js"></script>
<script src="src/form/fields.js"></script>
<script src="src/form/tables.js"></script>

<!-- Load compatibility layers -->
<script src="src/__.js"></script>
<script src="src/form.js"></script>
```

Then use the functions:

```javascript
// Using the compatibility layer (recommended for existing code).
__.generatePassword(12);
__.notify('Hello World!');
Form.check('myForm');

// Using individual modules (recommended for new code).
Utils.generatePassword(12);
UI.notify('Hello World!');
FormValidation.check('myForm');
```

### Node.js Usage

```javascript
const Utils = require('./src/utils.js');
const UI = require('./src/ui.js');

Utils.generatePassword(12);
UI.notify('Hello World!');
```

## Validation and Testing

Run the validation and test suite:

```bash
npm install
npm run format:check
npm run lint:check
npm run test
```




---

### Features

Features of the library.

# Features

## Utility Functions

- Password generation with cryptographic randomness.
- Cookie management.
- User language detection.
- Number formatting with locale support.
- Empty value checking.
- Integer/float validation.
- Object key extraction.
- String selector with object property concatenation.

## UI Functions

- Popup window management.
- Dynamic table creation.
- Notifications (with Notyf/Bootbox support).
- Clipboard operations (copy/paste).
- Social sharing (WhatsApp, etc.).
- Loading dialogs.
- Alert and confirmation dialogs.
- Smooth scrolling.
- URL deeplink management.
- Print functionality.

## Validation Functions

- Chilean RUT validation and formatting.
- Form field validation with multiple check types.
- Email validation (single and multiple).
- Date format validation.
- Phone number validation.
- Integer/real number validation.

## Form Functions

- Form submission via POST.
- Password field visibility toggle.
- Field expansion for long text.
- Dynamic form field initialization.
- Checkbox group management.
- Select option management.
- Dynamic table row management.

## Tab Functions

- Tab initialization and management.
- URL-based tab navigation.
- Magic link generation.
- Modal integration.
- Form element integration.




---

### Dependencies

Minimal dependencies for the library.

# Dependencies

The library is written in **pure vanilla JavaScript** but is designed to integrate seamlessly with popular external libraries when available. The code gracefully handles the absence of these dependencies.

> [!CHECK] Why Vanilla JS?
>
> See <http://vanilla-js.com>

The library has minimal dependencies and works with:

- Modern browsers (ES6+).
- jQuery (for some form functions).
- Bootstrap (for UI components).
- Bootbox (for dialogs).
- Notyf (for notifications, optional)

## Useful Dependencies

### Bootstrap

Used for tab management and modal functionality:

- Tab initialization and navigation (`src/tabs.js`).
- Modal instance management.
- Bootstrap classes and data attributes.

### jQuery

Used for enhanced form field functionality:

- Select2 integration for improved select fields.
- Datepicker integration for date inputs.
- Dynamic field initialization.

### Notyf

Enhanced notifications (falls back to basic alerts):

- Toast notifications with icons.
- Configurable duration and positioning.
- Multiple notification types.

### Bootbox

Enhanced dialog boxes:

- Confirmation dialogs.
- Prompt dialogs for field editing.
- Customizable dialog options.

## Graceful Degradation

The library includes conditional checks to ensure functionality even when external dependencies are not available:

```javascript
// Example: jQuery availability check.
if (typeof window.jQuery !== 'function') {
    console.error('window or jQuery is not available.');
    return;
}

// Example: Bootstrap availability check.
if (typeof bootstrap !== 'undefined') {
    new bootstrap.Tab(element).show();
}
```

## Installation Recommendations

For full functionality, include these dependencies in your project:

```html
<!-- Bootstrap CSS and JS -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/js/bootstrap.bundle.min.js"></script>

<!-- jQuery (for enhanced form features) -->
<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>

<!-- Font Awesome (for icons in the UI) -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/css/all.min.css" rel="stylesheet" />

<!-- Optional: Bootbox for dialogs -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootbox.js/6.0.4/bootbox.all.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootbox.js/6.0.4/bootbox.locales.min.js"></script>

<!-- Optional: Notyf for notifications -->
<link href="https://cdn.jsdelivr.net/npm/notyf@3.10.0/notyf.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/notyf@3.10.0/notyf.min.js"></script>
```




---

## HTML Project

UX Components for HTML in PHP

# UX Components for HTML in PHP

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/html/main)
![CI Workflow](https://github.com/derafu/html/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/html)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/html)
![Total Downloads](https://poser.pugx.org/derafu/html/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/html/d/monthly)

A few, legacy, HTML components rendered only with PHP.

You want modern components? See [UX Components for Twig](https://www.derafu.dev/docs/ui/twig).

> [!NOTE] WIP
>
> Work In Progress.

## Table

...

## Form

...




---

## Chart Project

PHP Chart Library

# PHP Chart Library

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/chart/main)
![CI Workflow](https://github.com/derafu/chart/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/chart)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/chart)
![Total Downloads](https://poser.pugx.org/derafu/chart/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/chart/d/monthly)

Derafu Chart is a PHP library for creating diverse charts. The library is designed to generate charts entirely in PHP using GD or other renderers. It supports a variety of chart types and is easy to extend.

## Features

- 📊 Multiple chart types: Bar, Line, Pie, Radar, Waterfall, and more.
- ⚙️ Fully customizable options.
- 📦 Lightweight and easy to integrate.
- 🖼️ Output in PNG and flexible rendering options.
- 💡 Extensible via custom renderers.
- 🧩 Encodable to JSON for interoperability.
- 🏷️ Open-source under the MIT license.

## Installation

You can install the library using Composer:

```bash
composer require derafu/chart
```

## Usage

You can choose the style that best suits your coding preferences or project requirements:

- Creating a Chart with the Factory.
- Creating a Chart with Method Chaining.

Both approaches allow flexibility depending on whether you prefer array-based configuration or object-oriented method chaining.

### Creating a Chart with the Factory

Here’s how to create a simple bar chart using the `ChartFactory`:

```php
use Derafu\Chart\ChartFactory;
use Derafu\Chart\Enum\ChartType;

$chart = (new ChartFactory())->renderFromArray([
    'type' => ChartType::BAR,
    'title' => 'Ventas',
    'label_x' => 'Mes',
    'label_y' => 'Ventas',
    'datasets' => [
        [
            'points' => [
                'Enero' => 10000,
                'Febrero' => 12000,
                'Marzo' => 1200,
                'Abril' => 1350,
                'Mayo' => 5000,
                'Junio' => 5000,
                'Julio' => 5000,
                'Agosto' => 5000,
                'Septiembre' => 15000,
            ],
        ],
    ],
]);

file_put_contents('chart.png', $chart);
```

### Creating a Chart with Method Chaining

Here’s how to create the same bar chart using method chaining:

```php
use Derafu\Chart\Chart;
use Derafu\Chart\Dataset;
use Derafu\Chart\Enum\ChartType;

$chart = (new Chart(ChartType::BAR))
    ->setTitle('Ventas')
    ->setLabelX('Mes')
    ->setLabelY('Ventas')
    ->addDataset(
        (new Dataset())
            ->setLabel('2024')
            ->setColor('blue')
            ->addPoints([
                'Enero' => 10000,
                'Febrero' => 12000,
                'Marzo' => 1200,
                'Abril' => 1350,
                'Mayo' => 5000,
                'Junio' => 5000,
                'Julio' => 5000,
                'Agosto' => 5000,
                'Septiembre' => 15000,
            ])
    );

file_put_contents('chart.png', $chart->render());
```

## Chart Types

Here is an overview of the chart types supported, with examples.

### 1. Area Chart

Displays continuous data trends over time or categories. Ideal for showing volume and trends.

![Area Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-area.png)

### 2. Bar Chart

Shows discrete data comparisons using vertical bars. Perfect for categorical comparisons.

![Bar Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-bar.png)

### 3. Bubble Chart

Highlights relationships and distributions. Bubble size represents a third dimension.

![Bubble Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-bubble.png)

### 4. Horizontal Bar Chart

Provides an alternative for displaying bar data, especially useful when labels are long.

![Horizontal Bar Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-horizontal_bar.png)

**Text Output Example**:

```plaintext
Chart name: horizontal_bar

                                     Ventas

Enero      │ ██████████████████████████ 10.000
Febrero    │ ███████████████████████████████ 12.000
Marzo      │ ███ 1.200
Abril      │ ███ 1.350
Mayo       │ █████████████ 5.000
Junio      │ █████████████ 5.000
Julio      │ █████████████ 5.000
Agosto     │ █████████████ 5.000
Septiembre │ ██████████████████████████████████████ 15.000
           └────────────────────────────────────────────────────
           0         4K        8K        12K       16K       20K
```

### 5. Pie Chart

Represents proportions in a dataset. Great for visualizing percentages.

![Pie Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-pie.png)

### 6. Radar Chart

Compares multiple variables across multiple dimensions. Ideal for skill or performance analysis.

![Radar Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-radar_1.png)

### 7. Scatter Plot

Shows relationships between two variables using points. Commonly used for distribution analysis.

![Scatter Plot](https://www.derafu.dev/img/content/docs/ui/chart/chart-scatter.png)

### 8. Waterfall Chart

Visualizes cumulative changes in value over a sequence. Useful for profit and loss analysis.

![Waterfall Chart](https://www.derafu.dev/img/content/docs/ui/chart/chart-waterfall.png)

## Roadmap

- 🔍 Export charts to JSON (e.g., Chart.js, regression libraries).
- 📈 Support trendlines and regression models.
- 🔄 Add SVG rendering support.
- 🌐 Add more internationalization options.




---

## Vite Plugin D2 Project

A Vite plugin to convert D2 diagrams to Images

# A Vite plugin to convert D2 diagrams to Images

A Vite plugin that converts [D2](https://d2lang.com/) diagram files to SVG during the build process.

## Installation

```bash
npm install --save-dev vite-plugin-d2
```

Make sure you have D2 installed globally:

```bash
npm install -g d2
```

Or follow the official installation instructions at: [https://d2lang.com/tour/install/](https://d2lang.com/tour/install/)

## Usage

Add the plugin to your `vite.config.js`:

```js
import vitePluginD2 from 'vite-plugin-d2';

export default {
  plugins: [
    vitePluginD2({
      // Options (all optional).
      theme: 0,              // D2 theme (number).
      layout: 'dagre',       // Layout engine.
      sketch: false,         // Enable sketch mode.
      dark: false,           // Enable dark mode.
      pad: 10,               // Padding.
      diagramsDir: './assets/diagrams',  // Input directory for D2 files.
      outputDir: null,       // Custom output dir (uses Vite's outDir if null).
      outputFormat: 'svg',   // Output format (currently only 'svg').
      verbose: false         // Enable verbose output logging.
    })
  ]
};
```

## How it works

The plugin searches for `.d2` files in the specified directory (`diagramsDir`, defaults to `./assets/diagrams`). During the build process, this plugin will:

1. Find all `.d2` files in the specified directory.
2. Convert them to SVG using the D2 CLI.
3. Place the generated SVG files in the output directory.

For example, if you have:

- `./assets/diagrams/architecture.d2`

The plugin will generate:

- `./dist/architecture.svg` (or in your configured output directory).

## Output Directory Configuration

By default, the plugin will output the SVG files to Vite's configured build output directory (`build.outDir`, which defaults to `dist`).

You can customize the output location by setting the `outputDir` option. The relative structure of files within the `diagramsDir` will be preserved in the output.

## Example D2 File

```
# Example D2 diagram.
shape: sequence_diagram
actor User
app: Application
db: Database

User -> app: Request data
app -> db: Query
db -> app: Results
app -> User: Display data
```

## Options

| Option       | Type         | Default             | Description                                                |
|--------------|--------------|---------------------|------------------------------------------------------------|
| theme        | number       | 0                   | D2 theme number                                            |
| layout       | string       | 'dagre'             | Layout engine (e.g., 'dagre', 'elk')                       |
| sketch       | boolean      | false               | Enable sketch/hand-drawn mode                              |
| dark         | boolean      | false               | Enable dark mode                                           |
| pad          | number       | 10                  | Padding around the diagram                                 |
| diagramsDir  | string       | './assets/diagrams' | Directory containing D2 files                              |
| outputDir    | string\|null | null                | Custom output directory (uses Vite's build.outDir if null) |
| outputFormat | string       | 'svg'               | Output format (currently only 'svg' is supported)          |
| verbose      | boolean      | false               | Enable verbose output logging                              |

## Advanced Usage

### Custom Input and Output Directories

You can specify custom directories for your D2 files and the generated SVGs:

```js
vitePluginD2({
  diagramsDir: './src/diagrams',  // Custom input directory.
  outputDir: './public/images',   // Custom output directory.
  verbose: true                   // Enable detailed logging.
})
```

### Styling Options

Customize the appearance of your diagrams:

```js
vitePluginD2({
  theme: 3,           // Use theme number 3.
  sketch: true,       // Enable sketch mode for hand-drawn appearance.
  dark: true,         // Enable dark mode.
  pad: 20             // Add more padding (20px).
})
```

## Troubleshooting

If you encounter issues:

1. Make sure D2 is properly installed and available in your PATH.
2. Check if the input directory exists and contains .d2 files.
3. Enable verbose mode (`verbose: true`) to see detailed logs.
4. Verify you have the necessary permissions to write to the output directory.




---

## Content Project

Where knowledge becomes product

# Where knowledge becomes product




---

### Introduction

What derafu/content is and how its plugins fit together.

# Where knowledge becomes product

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/content/main)
![CI Workflow](https://github.com/derafu/content/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/content)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/content)
![Total Downloads](https://poser.pugx.org/derafu/content/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/content/d/monthly)

Your content — documentation, FAQs, courses, blogs — is not just text. It's a valuable asset that can be packaged, reused, and leveraged like a digital product.

`derafu/content` is a PHP library that turns a directory of Markdown files into a content website: pages, navigation, tags, search and an interface AI agents can call directly. Every plugin adds one content type or one capability on top of the same core.

## Two kinds of configuration

Every plugin has, potentially, two independent configuration surfaces, and it is important not to confuse them:

1. **Plugin configuration**, in the website's `services.yaml`, under `derafu.content.config.plugins.<name>`. This is set once by whoever runs the website (which directory to scan, which URL to call, whether a feature is enabled at all).
2. **Content frontmatter**, the YAML block at the top of each Markdown file (`---title: ...---`). This is set by whoever writes a specific piece of content (its title, tags, whether it's a draft, etc.).

Both are documented per plugin, but the frontmatter fields are mostly the same across every content type — see [Content frontmatter](./frontmatter) for the fields shared by all of them. Each plugin's page only documents what it adds or overrides on top of that shared set.

## Content hierarchy

Content types that support nesting (Docs, Academy, FAQ, Pages) build their hierarchy from the filesystem: a subdirectory represents a level of nesting, and it needs a file with the *same name* as the directory to represent that level itself. For example:

```text
docs/
  facturacion.md              # Represents the "facturacion" section itself.
  facturacion/
    anular-dte.md              # A child of that section.
```

Without `facturacion.md`, the loader has no content item to attach `facturacion/anular-dte.md` to, and the whole subdirectory is silently skipped — it will not show up in listings, search, or the API export. This is the single most common cause of "my content doesn't show up."

## Missing content is a 404, not a 500

Requesting a URI that doesn't exist (or a draft outside a local environment) throws `Derafu\Content\Exception\ContentNotFoundException`, which is mapped to **404 Not Found** — across every content plugin (Academy, Blog, Docs, FAQ, Pages) and [Storage](./storage) attachments alike, since they all resolve through the same `ContentRegistryInterface::get()`. A draft that isn't allowed is treated the same way on purpose, so a 403 doesn't reveal that it exists.

## Plugins

- **[Academy](./academy)**: Course management (course → module → lesson hierarchy).
- **[API](./api)**: Bulk JSON export of the content, meant for external indexing/RAG pipelines.
- **[Blog](./blog)**: Blog management.
- **[Docs](./docs)**: Documentation management.
- **[FAQ](./faq)**: FAQ management.
- **[MCP](./mcp)**: Exposes the content as an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server, so AI agents (Claude Code, Claude Desktop, Cursor, etc.) can search and fetch it directly as tools instead of relying on stale training data.
- **[Pages](./pages)**: Standalone pages management, rendered under a `/pages` prefix by default so it doesn't conflict with hand-authored flat pages.
- **[Search](./search)**: Semantic search engine integration, with an optional LLM-based conversational answer ("ask") grounded on the indexed content.
- **[Sitemap](./sitemap)**: XML sitemap of every indexable content item, for search engines.
- **[Storage](./storage)**: Attachment storage and download management.

Every content item can also be rendered as HTML, Markdown or PDF, on top of the JSON used by the API and MCP plugins — see [PDF and Markdown export](./exports) for what those two add beyond the raw content (video/quiz rendering, bundling a whole section into one file, download buttons on the HTML view).




---

### Content Frontmatter

The YAML frontmatter fields shared by every content type (Academy, Blog, Docs, FAQ, Pages).

# Content frontmatter

Every Markdown content file starts with a YAML frontmatter block:

```markdown
---
title: "How to void a DTE"
description: "Steps to void an electronic tax document"
tags: ["billing", "chile"]
draft: false
---

The body of the content, in Markdown, starts here.
```

These fields are defined once, in `AbstractContentItem`, and apply to **every** content type (Academy lessons/modules/courses, Blog posts, Docs, FAQ questions, Pages). A plugin's own page only lists fields it adds or overrides on top of this shared set — if a plugin's page doesn't mention a field from this table, it behaves exactly as described here.

Unknown keys are not rejected: the frontmatter schema allows undefined keys, so a plugin (or a Twig template) can read a custom field with `item.metadata('my_field')` without declaring it anywhere first.

## Identity and SEO

| Field | Type | Default | Description |
|---|---|---|---|
| `title` | string | file name | Title of the content. |
| `description` | string | auto (see `preview` below) | Meta description and card/preview text. `summary` is a deprecated alias. |
| `keywords` | array of strings | `[]` | Extra keywords added to the `<meta name="keywords">` tag, on top of the tags. |
| `image` | string | none | Absolute or relative URL used for `og:image` and card previews. |
| `video` | string | none | Video URL. YouTube "watch" URLs are automatically rewritten to embed URLs. |
| `slug` | string | slugified file name | Overrides the URL segment used for this item. |
| `tags` | array of strings | `[]` | Tags shown on the item and used to filter listings (`/type/tags/{tag}`). |
| `authors` | string, or array of strings/objects (`{name, slug}`) | `Anonymous` | `author` (singular) is a deprecated alias. |

## Publishing

| Field | Type | Default | Description |
|---|---|---|---|
| `draft` | bool | `false` | Drafts are only visible when `APP_ENV=local` or the request host is `localhost`; hidden otherwise. |
| `unlisted` | bool | `false` | Still reachable by direct URL, but excluded from listings/tag pages unless explicitly filtered by `id`/`uri`. |
| `date` | string or timestamp | `YYYY-MM-DD-` prefix in the file name, or file creation time | Publish date. `created` is a deprecated alias. |
| `last_update` | string or timestamp | file modification time | Shown as "last updated on". |
| `deprecated` | bool, string or timestamp | `false` | `true` uses the file's modification time; a string/timestamp sets a specific deprecation date. |
| `indexable` | bool | `!draft && !unlisted && !deprecated`, and at least 100 characters of body | Whether the item should be considered for the `/api/content.json` export and, from there, external indexing (Qdrant, etc.). |
| `searchable` | bool | `!draft && !unlisted && !deprecated` | Whether the item should be considered a candidate for the site's own search (`search` plugin) — independent of `indexable`. |
| `time` | int (minutes) | auto-estimated from word count (200 wpm) | Reading time. Set it explicitly when the estimate is off (code-heavy pages, etc.). |

## Sidebar and table of contents

| Field | Type | Default | Description |
|---|---|---|---|
| `pagination_label` | string | `title` | Label used in the previous/next pagination links. |
| `sidebar_label` | string | `title` | Label used in the sidebar, which can differ from the page title. |
| `sidebar_position` | int | descending by `date` (newest first) | `order` is a deprecated alias. Lower sorts first. |
| `sidebar_class_name` | string | none | Extra CSS class added to the sidebar entry. |
| `sidebar_custom_props` | array | `[]` | Arbitrary data made available to the sidebar template. |
| `hide_title` | bool | `false` | Hides the `<h1>` rendered from `title`. |
| `hide_table_of_contents` | bool | `false` (`true` for Blog and FAQ) | Hides the in-page table of contents. |
| `toc_min_heading_level` | int (2-6) | `2` | Minimum heading level included in the table of contents. |
| `toc_max_heading_level` | int (2-6) | `6` | Maximum heading level included in the table of contents. |

## Authoring helpers

| Field | Type | Default | Description |
|---|---|---|---|
| `has_twig` | bool | auto-detected (`<twig:` in the body) | Whether the Markdown body should be rendered as Twig before being rendered as Markdown, so it can use Twig components. |

Content is organized hierarchically on the filesystem for the plugins that support nesting — see [Content hierarchy](./introduction#content-content-hierarchy) for the "one file per directory level" rule that trips people up most often.




---

### Academy Plugin

Course management, with a course → module → lesson hierarchy.

# Academy plugin

Manages online courses with a three-level hierarchy: **course → module → lesson**. Each level is a content item on its own (with its own title, description, tags, etc.), built from the filesystem structure — see [Content hierarchy](./introduction#content-content-hierarchy).

```text
resources/content/academy/
  getting-started.md                       # Course.
  getting-started/
    introduction.md                        # Module.
    introduction/
      what-is-this.md                      # Lesson.
      how-it-works.md                      # Lesson.
```

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.academy`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            academy:
              path: 'resources/content/academy'
              academyTitle: 'Academy'
              academyDescription: 'Do you want to learn about a topic? Start a course with us!'
```

| Option | Type | Default | Description |
|---|---|---|---|
| `path` | string | `resources/content/academy` | Directory scanned for course content, relative to the website root. |
| `academyTitle` | string | `Academy` | Title used for the academy's own SEO metadata. |
| `academyDescription` | string | `Do you want to learn about a topic? Start a course with us!` | Description used for the academy's own SEO metadata. |
| `include` | array of glob patterns | `['**.{markdown,md}']` | Files considered content, relative to `path`. |
| `exclude` | array of glob patterns | `[]` | Files excluded even if matched by `include`. |
| `showReadingTime` | bool | `true` | Whether to show the estimated reading time. |
| `showLastUpdateAuthor` | bool | `true` | Whether to show who last updated the lesson. |
| `showLastUpdateTime` | bool | `true` | Whether to show when the lesson was last updated. |
| `tags` | array of strings, or string | `[]` | Predefined tags for the academy. |
| `onInlineTags` | `ignore`\|`log`\|`warn`\|`throw` | `warn` | What to do when a lesson uses a tag that isn't in the predefined `tags` list. |

## Content frontmatter

Courses and modules use exactly the [generic content frontmatter](./frontmatter), nothing added.

Lessons add one field:

| Field | Type | Default | Description |
|---|---|---|---|
| `test` | string | none | A reference to a JSON quiz attachment: either `?attachment=<filename>`, or a literal path ending in `/_attachments/<filename>` (see [Storage](./storage)) — both resolve to the same local attachment. Parsed into a structured test, shown as an interactive quiz on the lesson's own page, and rendered in full in the [PDF and Markdown exports](./exports). Also switches the lesson's sidebar icon. A `test` value that resolves to neither form is passed through as-is to the quiz widget instead, unparsed. |

`time` on a course or module is not read from its own frontmatter — it is always the sum of its lessons' `time` (explicit or estimated).

## Quiz JSON format

```json
{
    "title": "Introduction quiz",
    "description": "Check what you remember from this lesson.",
    "questions": [
        {
            "type": "multiple_choice",
            "text": "Which of these is correct?",
            "options": [
                { "text": "Option A", "is_correct": true },
                { "text": "Option B", "is_correct": false }
            ],
            "allow_multiple": false,
            "explanation": "Option A is correct because..."
        },
        {
            "type": "true_false",
            "text": "This statement is true.",
            "answer": true,
            "explanation": "..."
        }
    ]
}
```

| Field | Type | Description |
|---|---|---|
| `title` | string | Title of the test. |
| `description` | string | Optional description. |
| `questions[].type` | `multiple_choice`\|`true_false` | Question type. A `true_false` question needs no `options` — its two options ("True"/"False") are generated from `answer`. |
| `questions[].options[].is_correct` | bool | Whether this option is a correct answer. More than one can be `true` when `allow_multiple` is `true`. |
| `questions[].explanation` | string | Shown in the PDF/Markdown exports' answer key, and in the lesson's own interactive quiz when an answer is marked incorrect. |




---

### Blog Plugin

Blog management, with archive, tags and an RSS feed.

# Blog plugin

Manages blog posts: listing, tag pages (`/blog/tags/{tag}`), a date archive (`/blog/archive/{archive}`) and an RSS feed (`/blog/rss.xml`).

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.blog`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            blog:
              path: 'resources/content/blog'
              blogTitle: 'Blog'
              postsPerPage: 10
```

| Option | Type | Default | Description |
|---|---|---|---|
| `path` | string | `resources/content/blog` | Directory scanned for posts, relative to the website root. |
| `blogTitle` | string | `Blog` | Title used for the blog's own SEO metadata. |
| `blogDescription` | string | `Thoughts, stories, and the latest from our world.` | Description used for the blog's own SEO metadata. |
| `blogSidebarCount` | int | `5` | Number of recent posts shown in the sidebar. |
| `blogSidebarTitle` | string | `Recent posts` | Title of the recent-posts sidebar. |
| `include` | array of glob patterns | `['**.{markdown,md}']` | Files considered content, relative to `path`. |
| `exclude` | array of glob patterns | `[]` | Files excluded even if matched by `include`. |
| `postsPerPage` | int | `10` | Posts per page in the listing. |
| `showReadingTime` | bool | `true` | Whether to show the estimated reading time. |
| `feedOptions` | array | see below | RSS feed configuration (`/blog/rss.xml`). |
| `showLastUpdateAuthor` | bool | `true` | Whether to show who last updated the post. |
| `showLastUpdateTime` | bool | `true` | Whether to show when the post was last updated. |
| `tags` | array of strings, or string | `[]` | Predefined tags for the blog. |
| `onInlineTags` | `ignore`\|`log`\|`warn`\|`throw` | `warn` | What to do when a post uses a tag that isn't in the predefined `tags` list. |

### `feedOptions`

| Option | Type | Default | Description |
|---|---|---|---|
| `limit` | int | `20` | Number of posts included in the feed. |
| `title` | string | `blogTitle` | Overrides the feed title. |
| `description` | string | `blogDescription` | Overrides the feed description. |
| `copyright` | string | none | Copyright line of the feed. |
| `language` | string | none | Feed language. |
| `sortPosts` | `descending`\|`ascending` | `descending` | Sort order of the posts in the feed. |

## Content frontmatter

Blog posts use the [generic content frontmatter](./frontmatter), with one override:

| Field | Type | Default | Description |
|---|---|---|---|
| `hide_table_of_contents` | bool | `true` | Overrides the generic default of `false` — blog posts hide the table of contents unless explicitly re-enabled. |




---

### Docs Plugin

Documentation management, with a sidebar and nested sections.

# Docs plugin

Manages documentation pages, nested arbitrarily deep — see [Content hierarchy](./introduction#content-content-hierarchy). Renders as HTML, Markdown or PDF depending on the requested format (`Accept` header, or `.md`/`.pdf` suffix) — see [PDF and Markdown export](./exports) for what the last two add, including bundling a whole section into one file with `?full=1`.

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.docs`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            docs:
              path: 'resources/content/docs'
              sidebarDepth: 5
```

| Option | Type | Default | Description |
|---|---|---|---|
| `path` | string | `resources/content/docs` | Directory scanned for docs, relative to the website root. |
| `include` | array of glob patterns | `['**.{markdown,md}']` | Files considered content, relative to `path`. |
| `exclude` | array of glob patterns | `[]` | Files excluded even if matched by `include`. |
| `sidebarPath` | bool | `true` | Whether to show the sidebar, auto-generated from the content hierarchy. There is no support for a custom, manually curated sidebar file — sort/label docs via `sidebar_position`/`sidebar_label` in their frontmatter instead. |
| `sidebarCollapsible` | bool | `true` | Whether sidebar categories can be collapsed. |
| `sidebarCollapsed` | bool | `true` | Whether sidebar categories start collapsed. |
| `sidebarDepth` | int | `5` | Maximum nesting depth shown in the sidebar. |
| `showLastUpdateAuthor` | bool | `true` | Whether to show who last updated the doc. |
| `showLastUpdateTime` | bool | `true` | Whether to show when the doc was last updated. |
| `breadcrumbs` | bool | `true` | Whether to show breadcrumbs above the doc. |
| `tags` | array of strings, or string | `[]` | Predefined tags for the docs. |
| `onInlineTags` | `ignore`\|`log`\|`warn`\|`throw` | `warn` | What to do when a doc uses a tag that isn't in the predefined `tags` list. |

## Content frontmatter

Docs use the [generic content frontmatter](./frontmatter), plus a few fields read directly by the docs template (not part of the shared schema, but supported the same way via arbitrary metadata):

| Field | Type | Default | Description |
|---|---|---|---|
| `show_title` | bool | `false` | Renders `# {title}` at the top of the body — useful together with `hide_title: true` if you want the title placed differently than the default heading. |
| `show_description` | bool | `false` | Renders the `description` right below the title inside the body. |
| `iframe` | string | none | URL embedded as a full-width `<iframe>` below the content. |
| `openapi` | string | none | URL of an OpenAPI/Swagger spec; renders a full Swagger UI below the content instead of (or in addition to) the Markdown body. |
| `show_source` | bool | `false` | Shows the raw source of the file (Markdown or Twig) in a code block below the content. |
| `show_children` | bool | `false` | Renders a card grid linking to this doc's direct children (title + description), useful for section landing pages. |

`hide_table_of_contents` keeps the generic default (`false`) for this plugin.




---

### FAQ Plugin

FAQ management, with nested sections and a sidebar.

# FAQ plugin

Manages frequently asked questions, nested arbitrarily deep — see [Content hierarchy](./introduction#content-content-hierarchy). Structurally very similar to [Docs](./docs), just under `/faq` instead of `/docs`.

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.faq`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            faq: ~
```

| Option | Type | Default | Description |
|---|---|---|---|
| `path` | string | `resources/content/faq` | Directory scanned for questions, relative to the website root. |
| `include` | array of glob patterns | `['**.{markdown,md}']` | Files considered content, relative to `path`. |
| `exclude` | array of glob patterns | `[]` | Files excluded even if matched by `include`. |
| `sidebarPath` | bool | `true` | Whether to show the sidebar, auto-generated from the content hierarchy. There is no support for a custom, manually curated sidebar file — sort/label questions via `sidebar_position`/`sidebar_label` in their frontmatter instead. |
| `sidebarCollapsible` | bool | `true` | Whether sidebar categories can be collapsed. |
| `sidebarCollapsed` | bool | `true` | Whether sidebar categories start collapsed. |
| `sidebarDepth` | int | `5` | Maximum nesting depth shown in the sidebar. |
| `showLastUpdateAuthor` | bool | `false` | Whether to show who last updated the question. |
| `showLastUpdateTime` | bool | `true` | Whether to show when the question was last updated. |
| `breadcrumbs` | bool | `true` | Whether to show breadcrumbs above the question. |
| `tags` | array of strings, or string | `[]` | Predefined tags for the FAQ. |
| `onInlineTags` | `ignore`\|`log`\|`warn`\|`throw` | `warn` | What to do when a question uses a tag that isn't in the predefined `tags` list. |

## Content frontmatter

FAQ questions use the [generic content frontmatter](./frontmatter), with one override and one addition:

| Field | Type | Default | Description |
|---|---|---|---|
| `hide_table_of_contents` | bool | `true` | Overrides the generic default of `false` — questions hide the table of contents unless explicitly re-enabled. |
| `show_children` | bool | `false` | Renders a card grid linking to this question's direct children (title + description), useful for section landing pages. |




---

### Pages Plugin

Standalone pages management, rendered as HTML, Markdown, PDF or JSON.

# Pages plugin

Manages standalone pages (an "about us", a landing page, changelog, etc.), including `.html.twig` files in addition to Markdown. Same content model and format negotiation (HTML/Markdown/PDF/JSON) as [Docs](./docs)/[FAQ](./faq), just without a listing/tag view — pages are meant to be linked directly, not browsed.

## Route and the `/pages` prefix

| Route | Path | Description |
|---|---|---|
| `pages_page` | `GET /pages/{uri}` | Shows a page. Format negotiated the same way as every other content plugin (`Accept` header, or `.md`/`.pdf`/`.json` suffix). |

The route is registered under `/pages` **on purpose**, not at the root (`/about` instead of `/pages/about`). The `{page:.+}` pattern is a catch-all, and the router tries routes with parameters *before* it tries file-based routes (`Derafu\Routing\Parser\FileSystemParser`, used for standalone Twig pages placed directly in `templates/pages/` by the website itself, with no content model). A catch-all with no prefix would shadow every one of those file-based pages: the router would never even get to ask the file-system parser about a URI this route already claims, since it checks parsers in order and stops at the first one that matches.

We verified this in practice: with the plugin enabled and content under `resources/content/pages/`, every existing hand-written route (static ones, and file-based ones from `templates/pages/`) kept working exactly as before — only URIs actually starting with `/pages/` are affected.

If a website wants pages at the root anyway, it can register its own route pointing at the same handler instead of importing this one:

```yaml
pages_page:
  path: /{page:.+}
  handler: 'Derafu\Content\Plugin\Pages\PagesController::show'
```

Registering that **before** any route that relies on `FileSystemParser`'s auto-discovery turns this trade-off off for that whole website: from then on, every flat page must be a content item (title/tags/draft/etc. via frontmatter), not a hand-authored Twig template dropped into `templates/pages/`. Pick one mechanism per website, not both, once this is unprefixed.

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.pages`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            pages:
              path: 'resources/content/pages'
```

| Option | Type | Default | Description |
|---|---|---|---|
| `path` | string | `resources/content/pages` | Directory scanned for pages, relative to the website root. |
| `include` | array of glob patterns | `['**.{markdown,md,html.twig}']` | Files considered content, relative to `path`. Unlike other plugins, this also matches `.html.twig` files. |
| `exclude` | array of glob patterns | `[]` | Files excluded even if matched by `include`. |
| `showLastUpdateAuthor` | bool | `false` | Whether to show who last updated the page. |
| `showLastUpdateTime` | bool | `false` | Whether to show when the page was last updated. |

## Content frontmatter

Pages use exactly the [generic content frontmatter](./frontmatter), nothing added.




---

### PDF and Markdown Export

What the PDF and Markdown exports add on top of the raw content, and how to bundle a whole section into one file.

# PDF and Markdown export

Every content item (Academy, Blog, Docs, FAQ, Pages) renders as HTML, Markdown, PDF or JSON — format negotiated via the `Accept` header, or a `.md`/`.pdf`/`.json` suffix on the URL. HTML is the normal browsing experience and JSON is the same shape used by [API](./api)/[MCP](./mcp); this page covers what is specific to the PDF and Markdown exports.

## Root-relative URLs are resolved to absolute ones

A content body written for the website itself references images and internal links with root-relative paths (`/img/foo.png`, `/docs/other-page`). Neither export has a "current page" to resolve a root-relative path against, so both make the body self-contained wherever it ends up — an LLM's context window, someone else's Markdown viewer, a PDF saved to disk:

- **Markdown**: both images and internal links are rewritten to absolute URLs.
- **PDF**: only links are rewritten. Images are left root-relative on purpose — the PDF engine resolves them from the local filesystem instead of fetching them over HTTP, which is slower and, on a single-worker server, can tie up the whole process waiting on a request back to itself.

## Video and quiz are shown, not just left in the frontmatter

A frontmatter `video` (see [Content frontmatter](./frontmatter)) is a plain URL in YAML that neither export would otherwise surface anywhere a reader (or an LLM) would notice it:

- **PDF**: a clickable YouTube thumbnail linking to the watch page, or a plain link for a non-YouTube URL.
- **Markdown**: the same thumbnail and link, as a Markdown image wrapped in a link.

An [Academy](./academy) lesson's `test` (quiz) is rendered in full — every option, not only the correct one, plus the explanation, since the wrong options and the explanation are real information (useful to know what an answer is commonly confused with, or why it's wrong):

- **PDF**: the questions with checkbox-style options first (to answer on paper), then a dedicated "Answers" section on its own page, with the correct option(s) checked and the explanation for each question.
- **Markdown**: each question as a GFM task list (`- [x]`/`- [ ]`, the correct option(s) checked), followed by the explanation as a blockquote.

## Bundling a whole section: `?full=1`

Content types with children — a Docs or FAQ section, an Academy course or module — accept `?full=1` on their `.pdf`/`.md` URL to bundle the whole subtree into a single file, instead of just the current item with a short list of links to its children:

- **PDF**: a cover page, a real table of contents with page numbers, then every descendant on its own page (Docs/FAQ children recursively; an Academy course's modules and, nested under each, its lessons).
- **Markdown**: every descendant's title and full body appended after the current item's, with heading levels reflecting how deep it is nested.

`?full=1` on an item with no children is a no-op: it falls through to the regular, single-item export.

## Download buttons on the HTML view

Every content page shows small, always-visible buttons for its PDF and Markdown exports, next to the tags/last-updated line — plain buttons, not a dropdown, so there is nothing to discover before they can be used:

- **PDF** opens inline: browsers render it in their own viewer, which already has its own save/print controls.
- **Markdown** downloads instead of opening inline: a browser has no native Markdown renderer, so opening it in a tab just shows unstyled raw text. A "Copy" button next to it copies the Markdown source straight to the clipboard — handy for pasting into an LLM — and confirms with a [Notyf](https://cdn.jsdelivr.net/npm/notyf@3.10.0/) toast when the site has it loaded, falling back to a brief change of the button's own text otherwise.

"Full" (and "Full Copy") variants of these buttons appear next to the regular ones whenever the item actually has children to bundle.




---

### API Plugin

Bulk JSON export of the content, meant for external indexing/RAG pipelines.

# API plugin

Exposes a single endpoint, `GET /api/content.json`, that returns every **indexable** item across every content plugin (Academy, Blog, Docs, FAQ, Pages) as a flat JSON list, via `ContentService::allContent()` — the same aggregation the [Sitemap](./sitemap) plugin uses. This is the feed an external pipeline (e.g. a tokenizer that loads embeddings into Qdrant) is meant to consume, and it is the source of truth external tools index against — not a page-by-page crawl of the website.

```json
{
    "meta": {
        "count": 424,
        "url": "https://example.com/",
        "generated": "2026-08-17 16:52:39"
    },
    "data": [
        {
            "id": "docs_doc_facturacion_anular-dte",
            "checksum": "b256587c...",
            "type": "docs",
            "category": "doc",
            "uri": "facturacion/anular-dte",
            "link": "https://example.com/docs/facturacion/anular-dte.json",
            "image": null,
            "title": "Anular un DTE",
            "description": "Pasos para anular un Documento Tributario Electrónico",
            "authors": [{ "name": "Anonymous", "slug": "anonymous" }],
            "tags": [{ "name": "facturacion", "slug": "facturacion", "count": 12 }],
            "date": "2026-03-12",
            "last_update": "2026-03-12",
            "time": 2
        }
    ]
}
```

Items with an empty body (`data()`), or that are not `indexable` (see [generic frontmatter](./frontmatter)), are skipped.

## Configuration (`services.yaml`)

None. Enabling the plugin (`api: ~`) is all that's needed — it has no options of its own, it only reads whatever the Academy/Blog/Docs/FAQ/Pages plugins already loaded.

```yaml
parameters:
    derafu.content.config:
        plugins:
            api: ~
```

## Filtering

The endpoint accepts the same filters as [`ContentRegistry::filter()`](https://github.com/derafu/content) as query parameters — for example `/api/content.json?type=docs&tag=facturacion&limit=20&page=1`. Useful keys: `type`, `category`, `tag`, `author`, `search`, `year`+`month`, `indexable`, `searchable`, `limit`, `page`.

## Content frontmatter

Not applicable — this plugin has no content items of its own, it aggregates the ones from the plugins that do.




---

### Sitemap Plugin

XML sitemap of every indexable content item, for search engines.

# Sitemap plugin

Exposes a single endpoint, `GET /sitemap.xml`, listing every **indexable** item across every content plugin (Academy, Blog, Docs, FAQ, Pages) — for search engine crawlers, not for AI agents (that's [MCP](./mcp)) nor for an indexing pipeline (that's [API](./api)). Deliberately does not emit `<changefreq>`/`<priority>`: modern crawlers (Google included) ignore both, so there is nothing to configure there.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://example.com/docs/facturacion/anular-dte</loc>
        <lastmod>2026-03-12T17:11:58+00:00</lastmod>
    </url>
</urlset>
```

Items with `indexable: false` (see [generic frontmatter](./frontmatter)) are skipped — the same rule the [API](./api) plugin's export uses.

## Configuration (`services.yaml`)

None. Enabling the plugin (`sitemap: ~`) is all that's needed.

```yaml
parameters:
    derafu.content.config:
        plugins:
            sitemap: ~
```

## Content frontmatter

Not applicable — this plugin has no content items of its own, it aggregates the ones from the plugins that do, the same way the [API](./api) plugin does (via `ContentService::allContent()`).




---

### MCP Plugin

Exposes the content as an MCP (Model Context Protocol) server for AI agents.

# MCP plugin

Exposes the content of the website as an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server, so AI agents (Claude Code, Claude Desktop, Cursor, claude.ai connectors, etc.) can search and fetch it directly as tools during their own conversation — instead of relying on stale training data or scraping HTML.

This is a different consumption channel than the [API](./api) plugin: the API plugin is a one-shot bulk export meant for an indexing pipeline (Qdrant, etc.); the MCP plugin is a live, callable interface for any MCP-capable agent.

## Endpoint

A single route, `POST /api/mcp` (also accepts `DELETE` to end a session, and `OPTIONS` for CORS preflight). It deliberately has **no `.json` suffix**: unlike every other endpoint in this package, its response is not always JSON — it can also be `text/event-stream` (SSE) when the protocol needs to keep the connection open mid-call. The MCP protocol negotiates that per-request via the `Accept` header, not via the URL, and every real MCP client already expects a plain endpoint URL with no extension.

It speaks JSON-RPC 2.0 over the "Streamable HTTP" transport of the [official PHP MCP SDK](https://github.com/modelcontextprotocol/php-sdk) (`mcp/sdk`), synchronously — there is no event loop involved, it fits the same request/response model as every other controller in this package.

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.mcp`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            mcp:
              ask:
                enabled: true
```

| Option | Type | Default | Description |
|---|---|---|---|
| `server_name` | string | `derafu-content` | Name announced to MCP clients during the `initialize` handshake. |
| `server_version` | string | `1.0.0` | Version announced to MCP clients during the `initialize` handshake. |
| `session_path` | string | a subdirectory of `sys_get_temp_dir()` | Directory where MCP sessions are persisted on disk between requests (a session is created on `initialize` and referenced by later calls via the `Mcp-Session-Id` header; since each request builds a new server instance, this cannot live in memory). Point it at something under the website's `var/` directory for a more durable/cleanable location. |
| `session_ttl` | int | `3600` | Time to live, in seconds, of a persisted session. |
| `ask.enabled` | bool | `false` | Whether the `ask` tool (LLM-backed conversational answers) is registered. See [Tools](#content-tools) below. |

This plugin does not handle authentication nor rate limiting — that is not its responsibility. If the endpoint needs to be protected, do it at the HTTP stack level (e.g. with the middlewares of `derafu/http`), before this controller is reached.

### The `mcp/sdk` dependency

`mcp/sdk` is a `require-dev` dependency (with a `suggest` entry) of `derafu/content`, not a hard `require`. If you enable this plugin, add it explicitly to **your own** `composer.json`:

```json
{
    "require": {
        "mcp/sdk": "^0.7"
    }
}
```

If you don't enable the plugin, nothing needs it: hitting `/api/mcp` without it installed and without the plugin configured fails with a normal "plugin not found" error, exactly like hitting `/api/search.json` without the `search` plugin configured — it does not affect any other endpoint of the website.

## Tools

| Tool | Always registered? | Description |
|---|---|---|
| `search_content` | yes | Semantic search across the indexed content, delegating to the [Search](./search) plugin's engine (Qdrant, or whatever is configured there). Accepts an optional `source` (`academy`, `blog`, `docs`, `faq`, `pages`, or `all`) to scope the search; omitting it or passing `all` searches every source at once. |
| `get_content` | yes | Fetch a single item by source and URI: full Markdown body plus metadata (title, tags, dates, authors). |
| `list_content` | yes | Browse/filter the items of a source (academy, blog, docs, faq, pages), optionally by tag, category or free-text search. |
| `list_tags` | yes | List the tags used in a source, with how many items use each one. |
| `ask` | only if `ask.enabled: true` | Ask a natural-language question and get a conversational answer from the LLM configured in the [Search](./search) plugin, grounded on the indexed content. |

`ask` is opt-in because, unlike the other four tools (which only ever read from the indexed content), it depends entirely on the quality of whatever LLM backend answers it — a bad or failed answer there makes the whole MCP server look unreliable, even though the rest of the tools never touch an LLM at all.

## Content frontmatter

Not applicable — this plugin has no content items of its own, it reuses whichever content plugins (Academy, Blog, Docs, FAQ, Pages) are already enabled.




---

### Search Plugin

Search engine integration, with an optional LLM-based conversational answer.

# Search plugin

Provides a search page and API that proxy to an **external** search engine — this plugin does not index anything itself, it queries whatever semantic/full-text search service you point it at (in practice, a service backed by Qdrant, fed by the [API](./api) plugin's export). It optionally also proxies to an LLM to answer questions conversationally, grounded on that same indexed content.

## Routes

| Route | Path | Description |
|---|---|---|
| `search` | `GET /search` | Search page (HTML). |
| `search_api` | `GET /api/search.json?q=...` | Search results as JSON. |
| `search_llm_query` | `GET /api/search/llm.json?q=...` | Conversational answer from the LLM (see [LLM backend](#content-llm-backend) below). |

## Configuration (`services.yaml`)

Enabled under `derafu.content.config.plugins.search`:

```yaml
parameters:
    derafu.content.config:
        plugins:
            search:
              url: 'https://search.example.com/api/search?collection=%s&base_url=%s&text=%s'
              collection: 'my-site'
              base_url: 'https://example.com'
              llm_url: 'https://api.openai.com'
              llm_model: 'gpt-4o-mini'
              llm_api_key: '%env(OPENAI_API_KEY)%'
```

| Option | Type | Default | Description |
|---|---|---|---|
| `url` | string | *(required)* | `sprintf()` template for the search engine's URL. See [URL template](#content-url-template) below. |
| `collection` | string | none | Collection/index identifier, URL-encoded and injected into `url`. |
| `base_url` | string | none | Base URL of the website, URL-encoded and injected into `url` (useful when the search backend serves more than one site). |
| `llm_url` | string | none | Base URL of the LLM backend. Leave unset to disable the `ask` tool ([MCP](./mcp)) and make `search_llm_query` fail. |
| `llm_model` | string | none | Model name sent to the LLM backend. **Required if `llm_url` is set** — there is no generic default, since no single model name makes sense across every provider. `llm()` throws immediately with a clear message if `llm_url` is configured without it, instead of silently sending an empty model name to your backend. |
| `llm_api_key` | string | none | API key sent as `Authorization: Bearer <key>`. |
| `llm_completions_path` | string | `/v1/chat/completions` | Path of the chat completions endpoint, appended to `llm_url`. See [LLM backend](#content-llm-backend). |

### URL template

`url` is a `sprintf()` template consumed in this order — trailing placeholders can be omitted:

1. `%s` → collection (only if both `collection` and `base_url` are set).
2. `%s` → base URL (only if both `collection` and `base_url` are set).
3. `%s` → the URL-encoded search query (always present, always last).

If `collection` or `base_url` is not configured, `url` is expected to have a single `%s` for the query only.

## LLM backend

The `llm_*` options configure a client for **any backend exposing an OpenAI-compatible chat completions endpoint** — the `{model, messages}` request / `choices[0].message.content` response shape that has become a de facto standard. With no code changes, that covers:

- OpenAI itself (`llm_url: https://api.openai.com`, default `llm_completions_path`).
- [OpenRouter](https://openrouter.ai) (`llm_url: https://openrouter.ai/api`, default `llm_completions_path`, `llm_model` like `anthropic/claude-sonnet-4.5`) — itself proxies Claude, Gemini, Llama, etc. through the same shape.
- Anthropic's own [OpenAI-compatible endpoint](https://platform.claude.com/docs/en/api/openai-sdk) (`llm_url: https://api.anthropic.com`, default `llm_completions_path`).
- Self-hosted [Open WebUI](https://openwebui.com) — needs `llm_completions_path: /api/chat/completions` instead of the default, since it does not follow the standard path.
- Groq, Together AI, Ollama, Azure OpenAI (`Authorization: Bearer` variant), and most other providers.

A backend that does not speak this protocol at all (a provider's native, non-compatible API) is not supported today, but the client is behind an interface (`Derafu\Content\Plugin\Search\Contract\LlmClientInterface`) precisely so an alternative implementation can be swapped in later without touching `SearchController` or the `ask` MCP tool.

Failures from either the search engine or the LLM backend (unreachable host, non-200 response, unexpected response shape) surface as `SearchUpstreamException`, mapped to **502 Bad Gateway** — not a generic 500 — since the request to this website was fine, it's whatever it depends on that failed. The error message includes whatever detail the upstream returned (`error`/`error.message`/`detail`, depending on the provider).

## Content frontmatter

Not applicable — this plugin has no content items of its own; `searchable` (see [generic frontmatter](./frontmatter)) is read by whoever builds the external search index, not by this plugin.




---

### Storage Plugin

Attachment storage and download management for any content type.

# Storage plugin

Serves file attachments that live next to a content item — images, PDFs, quiz files for an [Academy](./academy) lesson, etc. — through a single, uniform URL, regardless of which content plugin owns the item.

## Attachment convention

An attachment is any file placed in a `_attachments/` subdirectory next to its content file, named after that file (without extension):

```text
resources/content/academy/getting-started/introduction/what-is-this.md
resources/content/academy/getting-started/introduction/what-is-this/_attachments/
  cheat-sheet.pdf
  quiz.json
```

`what-is-this.md`'s attachments are exactly the files under `what-is-this/_attachments/`. Reference one from frontmatter as `?attachment=<filename>` — see the `test` field of [Academy](./academy) lessons for a real example.

## Route

| Route | Path | Description |
|---|---|---|
| `content_storage_download` | `GET /{type}/{uri}/_attachments/{attachment}` | Downloads an attachment. `type` is the content type (`docs`, `academy`, etc.), `uri` is the item's URI. |

## Configuration (`services.yaml`)

None. Enabling the plugin (`storage: ~`) is all that's needed — it has no options of its own, it only serves whatever attachments already exist next to items loaded by the other content plugins.

```yaml
parameters:
    derafu.content.config:
        plugins:
            storage: ~
```

## Content frontmatter

Not applicable — attachments are files on disk, not content items, and are not referenced through frontmatter fields of their own (beyond however a specific plugin points at them, like Academy's `test`).




---

### Content Cache

What the built-in content cache does and does not speed up, and how to swap its backend.

# Content cache

Every content plugin that supports nesting (Academy, Blog, Docs, FAQ, Pages) builds its item tree by scanning the filesystem and parsing the YAML frontmatter of every single file — on every request, since this package has no build step and no long-running process. The content cache exists to avoid redoing that scan-and-parse work on every request; it is not a general-purpose page cache.

## What it caches

Exactly one thing: the **already-built item tree** of a content registry (the result of `AbstractContentRegistry::all()`) — titles, tags, dates, hierarchy, everything derived from frontmatter. It is keyed by the plugin's `path` + `include` + `exclude` options, so two registries pointed at the same content share one cache entry regardless of which plugin instantiated them first.

This benefits every operation that needs to look at more than one item — listings, tag pages, the sidebar, [Sitemap](./sitemap), and [API](./api)'s `allContent()` export — since those are exactly the operations that today pay the "read and parse everything" cost on every request, whether or not the specific page requested needed most of that data.

## What it does **not** cache

To avoid false expectations:

- **Rendered output.** HTML, Markdown, PDF and JSON responses are all still generated fresh on every request — Twig compilation, the `markdown`/`twig` filters, PDF generation. Caching the index does not cache a page.
- **HTTP-level caching.** No `Cache-Control` or `ETag` header is set by any content controller. A reverse proxy or CDN in front of the site would still treat every request as uncacheable unless configured to do otherwise, independently of this feature.
- **[Search](./search)'s external calls.** Queries to the search engine and the LLM backend are never cached — they hit the configured `url`/`llm_url` on every call.
- **[MCP](./mcp) tool responses.** Each tool call resolves fresh against the (possibly cached) registries; the MCP layer itself adds no caching of its own.
- **[Storage](./storage) attachment downloads.** Files are streamed from disk on every request.

In short: this makes it cheaper to *know what content exists and what it's about*. It does not make any specific page's response faster to render or serve.

## Default: a real filesystem cache, no configuration needed

Caching is on by default, with no service to run. The package's own `content-services.yaml` (imported by every site that enables this package) wires a `Symfony\Component\Cache\Adapter\FilesystemAdapter` under namespace `derafu_content`, 60-second TTL, rooted at `%kernel.cache_dir%` — the exact same `var/cache/<env>/` directory the rest of a `derafu/kernel`-based app already uses (compiled container, etc.). Concretely, that means `var/cache/dev/derafu_content/` in a `dev` environment, `var/cache/prod/derafu_content/` in `prod`, and so on — clearing it is `rm -rf var/cache/<env>/derafu_content`, the same mental model as clearing any other cache in the app, nothing extra to remember.

`Derafu\Content\ContentContext` itself defaults to a `FilesystemAdapter` under the system temp directory if no cache pool is injected at all — that fallback only matters if this package is used standalone, outside the shipped `services.yaml` (e.g. directly in PHP, or in this package's own test suite). Any real site importing `content-services.yaml` gets the `var/cache/<env>/derafu_content` location described above, not the temp directory.

## Freshness

Each cache entry expires after 60 seconds. There is no manual invalidation and no filesystem-change detection: editing a Markdown file is not reflected instantly, only once its registry's entry expires (up to 60 seconds later) or the process restarts. This is a deliberate trade-off — a short TTL removes the "rescan everything on every request" cost without needing any invalidation logic — but it does mean content changes are not instantaneous the way they were without caching.

On a multi-worker or multi-server deployment, each worker/server builds and caches its own copy independently unless they share the cache backend (e.g. all pointed at the same Redis instance) — see below.

## Disabling the cache: `cache.enabled`

Enabled under `derafu.content.config`:

```yaml
parameters:
    derafu.content.config:
        cache:
            enabled: true
```

| Option | Type | Default | Description |
|---|---|---|---|
| `enabled` | bool | `true` | Whether the content cache is used at all. When `false`, `ContentContext::cache()` returns `null` and every registry falls back to `AbstractContentRegistry`'s own `null`-cache path: it rescans and reparses on every request, with no pool involved. |

This package reads that value as a plain boolean — it does not know about environments or kernels. Sourcing it from an environment variable, with whatever per-environment default a site wants, is entirely the site's own `services.yaml` concern:

```yaml
parameters:
    derafu.content.config:
        cache:
            enabled: '%env(bool:DERAFU_CONTENT_CACHE_ENABLED)%'
```

`DERAFU_CONTENT_CACHE_ENABLED` then comes from wherever the site already resolves per-environment values (a `.env`/`.env.local` cascade, a `when@dev:` config block using `%kernel.environment%`, etc.) — this package never reads `$_SERVER['APP_ENV']` or the kernel for this decision, only the boolean it's handed.

## Using a different cache backend

The cache pool is the `derafu_content.cache` service, typed against `Psr\Cache\CacheItemPoolInterface` (PSR-6) where it's injected into `ContentContext`. A site's own `services.yaml` is loaded after the package's, so redefining that same service ID replaces it outright — no need to touch `ContentContextInterface`'s own definition:

```yaml
services:
    derafu_content.cache:
        class: Symfony\Component\Cache\Adapter\RedisAdapter
        arguments:
            $redis: '@Redis'
            $namespace: 'derafu_content'
            $defaultLifetime: 60
```

This is the right move on a multi-worker or multi-server deployment: with the default `FilesystemAdapter`, each worker/server builds and caches its own copy independently; pointing `derafu_content.cache` at a shared backend (Redis, Memcached) instead means they all share one cache instead of duplicating the work. This is a different concern than `cache.enabled` above: swapping the backend still caches, just somewhere shared; `cache.enabled: false` skips caching altogether regardless of which backend is wired.

## Content frontmatter

Not applicable — caching operates on already-loaded items, it adds no frontmatter fields of its own.





---
Last updated on 09/09/2026