Was this page helpful?
Topic box¶
A custom directive that creates graphical boxes (cards) for navigation and content organization.
Syntax¶
.. topic-box::
<options>
<text>
Options¶
The topic-box directive supports the following options:
Option |
Type |
Required |
Example Value |
Description |
|---|---|---|---|---|
|
string |
Lorem ipsum |
Topic box title. |
|
|
string |
Custom CSS class. |
||
|
string |
icon-home |
A list of CSS classes to render icons, separated by comma or space. |
|
|
string |
/_static/img/mascots-2/enterprise.svg |
Path to the image. The image should be located in the project’s |
|
|
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 |
|
|
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. |
|
|
string |
Getting Started > |
Text for the call to action. |
Link resolution¶
The topic-box directive handles different types of links:
External links (e.g. https://example.com)
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:
# 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:
Grid support¶
To display topic boxes in responsive grid layouts, use the Grid 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:
.. topic-box::
:title: Lorem Ipsum
:icon: icon-github
:link: #
:anchor: Lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Results in:
Topic with image¶
Using:
.. 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:
Topic with external link¶
Using:
.. topic-box::
:title: Lorem Ipsum
:link: https://scylladb.com
:anchor: Lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Results in:
Topic with external link (same tab)¶
Using:
.. 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:
Product topic¶
Using:
.. 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: