# 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.                                                                                                                                                                           |
| `cta`                  | string |                                                           | Learn more                                 | Call to action text next to the button.                                                                                                                                                     |
| `button_icon`          | string |                                                           | fa fa-home                                 | A list of CSS classes to render an icon, separated by comma or space.                                                                                                                       |
| `button_icon_position` | string |                                                           | left                                       | Position of the icon in relation to the text. Available values: `left`, `right`. Defaults to `left`.                                                                                        |
| `button_icon_link`     | flag   |                                                           |                                            | If set, applies the CTA color to the icon.                                                                                                                                                  |
| `button text`          | string |                                                           | Lorem ipsum                                | Text for the call to action.                                                                                                                                                                |
| `button_style`         | string |                                                           | bold                                       | Apply specific style to the button. Available values: `default`, `bold`. Defaults to `default`.                                                                                             |
| `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_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  None' aria-hidden='true'></i>Project Name
                </button>
                </a>
                </div></div></div>

### Hero box with button & icon

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :image: /_static/img/mascots/scylla-enterprise.svg
    :button_url: #
    :button_icon: fa fa-github
    :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>

### Hero box with button & icon (position right)

Using:

```rst
.. hero-box::
    :title: Lorem Ipsum
    :image: /_static/img/mascots/scylla-enterprise.svg
    :button_url: #
    :button_icon: fa fa-github
    :button_icon_position: right
    :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">
                Project Name<i class='icon icon--right  fa fa-github' aria-hidden='true'></i>
                </button>
                </a>
                </div></div></div>

### Hero box with bold button

Using:

```rst
.. hero-box::
    :title: Lorem ipsum
    :button_text: Project Name
    :button_url: #
    :button_style: bold

    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>
                <a href="#">
                <button class="hero_\_button button hero_\_button--bold">
                <i class='icon icon--left  None' aria-hidden='true'></i>Project Name
                </button>
                </a>
                </div></div></div>

### Hero with colored button

Using:

```rst
.. hero-box::
    :title: Lorem ipsum
    :button_text: Project Name
    :button_url: #
    :button_icon_link:

    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>
                <a href="#">
                <button class="hero_\_button button">
                <i class='icon icon--left icon--link None' aria-hidden='true'></i>Project Name
                </button>
                </a>
                </div></div></div>

### Hero box button with CTA

Using:

```rst
.. hero-box::
    :title: Lorem ipsum
    :button_text: Project Name
    :button_url: #
    :cta: Learn more

    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>
                <a href="#">
                <button class="hero_\_button button">
                <i class='icon icon--left  None' aria-hidden='true'></i>Project Name <span class='hero_\_cta'>Learn more</span>
                </button>
                </a>
                </div></div></div>

### Hero box with everything

```rst
.. hero-box::
    :title: Lorem ipsum
    :image: /_static/img/mascots/scylla-enterprise.svg
    :button_text: Project Name
    :button_url: #
    :button_style: bold
    :button_icon: fa fa-github
    :button_icon_position: right
    :button_icon_link:
    :cta: Learn more
    :search_box:

    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 hero_\_button--bold">
                Project Name <span class='hero_\_cta'>Learn more</span><i class='icon icon--right icon--link fa fa-arrow-right' aria-hidden='true'></i>
                </button>
                </a>
                
                    <div class="hero_\_search-wrapper">
                        <div class="hero_\_search-box search-box search-box--hero">
                            <ci-search></ci-search>
                        </div>
                    </div>
                    </div></div></div>