# Hero box

A custom directive to create a header on the root `index.rst` file.

#### WARNING
Do not use the `hero-box` on the subordinate `index.rst` files.

## 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.                                                                                                                                                                           |
| `button_icon` | string |                                                           | fa fa-home                                 | A list of CSS classes to render an icon, separated by comma or space.                                                                                                                       |
| `button text` | string |                                                           | Lorem ipsum                                | Text for the call to action.                                                                                                                                                                |
| `button_url`  | string |                                                           |                                            | Relative link or external URL for the call to action. Do not use leading and trailing (“/”) symbols to define relative links. (e.g. instead of `/getting-started/`, use `getting-started`). |
| `image`       | string |                                                           | /_static/img/mascots/scylla-enterprise.svg | Path to the image. The image should be located in the project’s `_static` folder.                                                                                                           |
| `search_box`  | flag   |                                                           |                                            | If set, displays the site’s search box.                                                                                                                                                     |

## Usage

### Default

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Results in:


            <div class="hero ">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

</div></div></div></div>

### Hero box with image

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :image: /_static/img/mascots/scylla-enterprise.svg

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Results in:


            <div class="hero ">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                <img src="/_static/img/mascots/scylla-enterprise.svg" />
                
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

</div></div></div></div>

### Hero box with search box

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :search_box:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Results in:


            <div class="hero ">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

</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>

### Hero box with button

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :image: /_static/img/mascots/scylla-enterprise.svg
    :button_icon: fa fa-github
    :button_url: #
    :button_text: Project Name

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Results in:


            <div class="hero ">
                <div class="hero-wrapper">
                    <div class="hero_\_img">
                    
                <img src="/_static/img/mascots/scylla-enterprise.svg" />
                
                    </div>
                    <div class="hero-header">
                        <h1 class="hero_\_title">Lorem Ipsum</h1>
                        <div class="hero_\_text">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

</div>
                <a href="#">
                <button class="hero_\_button button">
                <i class='icon icon--left  fa fa-github' aria-hidden='true'></i>Project Name
                </button>
                </a>
                </div></div></div>