# Hero box

A custom directive that creates prominent header sections at the top of landing.

## Syntax

```rst
.. hero-box::
   <options>

   <text>
```

## Options

The `hero-box` directive supports the following options:

| Option                 | Type   | Required                                                  | Example Value                         | Description                                                                                                                                |
|------------------------|--------|-----------------------------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `title`                | string | <i class="inline-icon icon-check" aria-hidden="true"></i> | Lorem ipsum                           | Hero box title.                                                                                                                            |
| `class`                | string |                                                           |                                       | Custom CSS class.                                                                                                                          |
| `cta`                  | string |                                                           | Learn more                            | Call to action text.                                                                                                                       |
| `image`                | string |                                                           | /_static/img/mascots-2/enterprise.svg | Path to the image. The image should be located in the project’s `_static` folder.                                                          |
| `button_style`         | string |                                                           | bold                                  | Button style. Available values: bold.                                                                                                      |
| `button_icon`          | string |                                                           | icon-github                           | A list of CSS classes to render icons, separated by comma or space.                                                                        |
| `button_icon_position` | string |                                                           | right                                 | Icon position. Available values: left, right.                                                                                              |
| `button_icon_link`     | flag   |                                                           |                                       | If present, the icon will be rendered as a link.                                                                                           |
| `button_url`           | string |                                                           | getting-started                       | Relative link or external URL for the call to action.                                                                                      |
| `button_text`          | string |                                                           | Learn more                            | Button text.                                                                                                                               |
| `search_box`           | flag   |                                                           |                                       | If present, a search box will be rendered.                                                                                                 |
| `content_page`         | flag   |                                                           |                                       | If present, adds vertical padding suitable for content pages. By default (without this flag), the hero box is optimized for landing pages. |
| `ai_chatbot_id`        | string |                                                           | my-chatbot-id                         | AI chatbot ID to use for the Ask AI button. Requires the `search_box` option to be present.                                                |

## Link resolution

The hero-box directive handles different types of links:

1. External links (e.g. [https://example.com](https://example.com))
2. Internal links with different path formats:
   \* Absolute paths (e.g. /getting-started/installation)
   \* Relative paths (e.g. code-blocks)
   \* Parent directory references (e.g. ../getting-started)
   \* Index files (e.g. index)

Examples:

```rst
# External link
.. hero-box::
    :title: External Resources
    :text: Visit our website for more information
    :button_text: Learn more
    :button_url: https://scylladb.com
    :button_icon: icon-external-link
    :button_icon_position: right

# Internal link (absolute)
.. hero-box::
    :title: Getting Started
    :text: Learn how to install and configure ScyllaDB
    :button_text: Learn more
    :button_url: /getting-started/installation
    :button_icon: icon-arrow-right
    :button_icon_position: right

# Internal link (relative)
.. hero-box::
    :title: Code blocks
    :text: Learn how to install and configure ScyllaDB
    :button_text: Learn more
    :button_url:code-blocks
    :button_icon: icon-arrow-right
    :button_icon_position: right

# Internal link (relative)
.. hero-box::
    :title: Related Topics
    :text: Check out these related guides
    :button_text: Learn more
    :button_url: ../getting-started/installation
    :button_icon: icon-folder
    :button_icon_position: left
```

## Usage

### Basic usage

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :button_text: Learn more
    :button_url: #
    :button_icon: icon-arrow-right
    :button_icon_position: right
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                <a href="#">
                <button class="hero_\_button button">
                Learn more<i class='icon icon--right  icon-arrow-right' aria-hidden='true'></i>
                </button>
                </a>
                </div></div></div>

### With image

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :image: /_static/img/mascots-2/enterprise.svg
    :button_text: Learn more
    :button_url: #
    :button_icon: icon-arrow-right
    :button_icon_position: right
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                <img src="/_static/img/mascots-2/enterprise.svg" />
                
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                <a href="#">
                <button class="hero_\_button button">
                Learn more<i class='icon icon--right  icon-arrow-right' aria-hidden='true'></i>
                </button>
                </a>
                </div></div></div>

### With search box

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :search_box:
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                    <div class="hero_\_search-wrapper">
                        <div class="hero_\_search-box search-box search-box--hero">
                            <ci-search></ci-search>
                        </div>
                    </div>
                    </div></div></div>

### With custom AI chatbot ID

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :search_box:
    :ai_chatbot_id: my-custom-chatbot-id
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                    <div class="hero_\_search-wrapper">
                        <div class="hero_\_search-box search-box search-box--hero">
                            <ci-search></ci-search>
                        </div>
                <div class="hero_\_ask-ai">
                    <biel-button project="ddfdo8m94k"
                        header-title="ScyllaDB chatbot"
                        button-position="default"
                        modal-position="bottom-right"
                        button-style="dark">Ask AI</biel-button>
                </div>
                    </div>
                    </div></div></div>

### With bold button

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :button_text: Learn more
    :button_url: #
    :button_icon: icon-arrow-right
    :button_icon_position: right
    :button_style: bold
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                <a href="#">
                <button class="hero_\_button button hero_\_button--bold">
                Learn more<i class='icon icon--right  icon-arrow-right' aria-hidden='true'></i>
                </button>
                </a>
                </div></div></div>

### With icon as link

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    :button_text: Learn more
    :button_url: #
    :button_icon: icon-arrow-right
    :button_icon_position: right
    :button_icon_link:
    :content_page:
```

Results in:


            <div class="hero " style="margin-top: 2em; margin-bottom: 2em;">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            </div>
                <a href="#">
                <button class="hero_\_button button">
                Learn more<i class='icon icon--right icon--link icon-arrow-right' aria-hidden='true'></i>
                </button>
                </a>
                </div></div></div>