# Topic box

A custom directive that creates graphical boxes (cards) for navigation and content organization.

## Syntax

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

   <text>
```

## Options

The `topic-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                           | Topic box title.                                                                                                                                                                                                             |
| `class`       | string |                                                           |                                       | Custom CSS class.                                                                                                                                                                                                            |
| `icon`        | string |                                                           | icon-home                             | A list of CSS classes to render icons, separated by comma or space.                                                                                                                                                          |
| `image`       | string |                                                           | /_static/img/mascots-2/enterprise.svg | Path to the image. The image should be located in the project’s `_static` folder.                                                                                                                                            |
| `link`        | string |                                                           | getting-started                       | 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`).                                  |
| `link_target` | string |                                                           | auto                                  | Defines if the link should be opened in a new tab or not. Available values: auto, \_blank, \_self. Defaults to auto. When set to auto, external links will open in a new tab while internal links will open in the same tab. |
| `anchor`      | string |                                                           | Getting Started >                     | Text for the call to action.                                                                                                                                                                                                 |

## Link resolution

The topic-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
.. topic-box::
    :title: ScyllaDB
    :link: https://scylladb.com
    :anchor: Learn more

# Absolute path (from project root)
.. topic-box::
    :title: Getting Started
    :link: /getting-started/installation
    :anchor: Learn more

# Relative path (same directory)
.. topic-box::
    :title: Code Blocks
    :link: code-blocks
    :anchor: Learn more

# Parent directory
.. topic-box::
    :title: Parent Section
    :link: ../getting-started/installation
    :anchor: Learn more

# Index file
.. topic-box::
    :title: Examples
    :link: index
    :anchor: Learn more
```

Renders:


            
                <div class="cell topic-box ">
                    <a class="card" href="https://scylladb.com" target="_blank">
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">ScyllaDB</h3>
                </div>
                <div class="topic-box_\_body">
            
            
                <div class="topic-box_\_anchor">Learn more
                 <i class="icon-newtab" aria-hidden="true"></i>
                </div>
                
            </div>
            </a></div>
            
            
                <div class="cell topic-box ">
                    <a class="card" href="../getting-started/installation.md" >
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Getting Started</h3>
                </div>
                <div class="topic-box_\_body">
            
            
                <div class="topic-box_\_anchor">Learn more</div>
                
            </div>
            </a></div>
            
            
                <div class="cell topic-box ">
                    <a class="card" href="code-blocks.md" >
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Code Blocks</h3>
                </div>
                <div class="topic-box_\_body">
            
            
                <div class="topic-box_\_anchor">Learn more</div>
                
            </div>
            </a></div>
            
            
                <div class="cell topic-box ">
                    <a class="card" href="../getting-started/installation.md" >
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Parent Section</h3>
                </div>
                <div class="topic-box_\_body">
            
            
                <div class="topic-box_\_anchor">Learn more</div>
                
            </div>
            </a></div>
            
            
                <div class="cell topic-box ">
                    <a class="card" href="index.md" >
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Examples</h3>
                </div>
                <div class="topic-box_\_body">
            
            
                <div class="topic-box_\_anchor">Learn more</div>
                
            </div>
            </a></div>
            
## Grid support

To display topic boxes in responsive grid layouts, use the [Grid](https://sphinx-theme.scylladb.com/master/examples/grid.md) directive. The grid directive is specifically designed to work with topic boxes and supports Foundation’s grid system for responsive layouts.

## Usage

### Topic with icon

Using:

```rst
.. topic-box::
    :title: Lorem Ipsum
    :icon: icon-github
    :link: #
    :anchor: Lorem ipsum

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

Results in:


            
                <div class="cell topic-box ">
                    <a class="card" href="#" >
                
                <div class="topic-box_\_head">
                
            <div class="topic-box_\_icon">
                <i class="icon-github"></i>
            </div>
            
                <h3 class="topic-box_\_title">Lorem Ipsum</h3>
                </div>
                <div class="topic-box_\_body">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.


            
                <div class="topic-box_\_anchor">Lorem ipsum</div>
                
            </div>
            </a></div>
            
### Topic with image

Using:

```rst
.. topic-box::
    :title: Lorem Ipsum
    :image: /_static/img/mascots-2/enterprise.svg
    :link: #
    :anchor: Lorem ipsum

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

Results in:


            
                <div class="cell topic-box ">
                    <a class="card" href="#" >
                
                <div class="topic-box_\_head">
                
            <div class="topic-box_\_icon"">
                <img src="/_static/img/mascots-2/enterprise.svg"/>
            </div>
            
                <h3 class="topic-box_\_title">Lorem Ipsum</h3>
                </div>
                <div class="topic-box_\_body">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.


            
                <div class="topic-box_\_anchor">Lorem ipsum</div>
                
            </div>
            </a></div>
            
### Topic with external link

Using:

```rst
.. topic-box::
    :title: Lorem Ipsum
    :link: https://scylladb.com
    :anchor: Lorem ipsum

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

Results in:


            
                <div class="cell topic-box ">
                    <a class="card" href="https://scylladb.com" target="_blank">
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Lorem Ipsum</h3>
                </div>
                <div class="topic-box_\_body">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.


            
                <div class="topic-box_\_anchor">Lorem ipsum
                 <i class="icon-newtab" aria-hidden="true"></i>
                </div>
                
            </div>
            </a></div>
            
### Topic with external link (same tab)

Using:

```rst
.. topic-box::
    :title: Lorem Ipsum
    :link: https://scylladb.com
    :link_target: _self
    :anchor: Lorem ipsum

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

Results in:


            
                <div class="cell topic-box ">
                    <a class="card" href="https://scylladb.com" >
                
                <div class="topic-box_\_head">
                
                <h3 class="topic-box_\_title">Lorem Ipsum</h3>
                </div>
                <div class="topic-box_\_body">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.


            
                <div class="topic-box_\_anchor">Lorem ipsum</div>
                
            </div>
            </a></div>
            
### Product topic

Using:

```rst
.. topic-box::
    :title: Lorem Ipsum
    :link: #
    :image: /_static/img/mascots-2/enterprise.svg
    :class: topic-box--product

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

Results in:


            
                <div class="cell topic-box topic-box--product">
                    <a class="card" href="#" >
                
                <div class="topic-box_\_head">
                
            <div class="topic-box_\_icon"">
                <img src="/_static/img/mascots-2/enterprise.svg"/>
            </div>
            
                <h3 class="topic-box_\_title">Lorem Ipsum</h3>
                </div>
                <div class="topic-box_\_body">
            
Lorem ipsum dolor sit amet, consectetur adipiscing elit.


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