Formatting guide ¶

A button with text

Button text

A button with a shadow

A button with an outline

A button that fills the width of the page

User Guides Operators Guide Guided Setup

Some buttons in a container

Card carousel¶

Caution

This formatting option is unused. Please ask the Amperity docs team before using it.

Use the .. card-carousel:: directive to create a horizontal scrolling set of cards. Set an integer value between 1 and 4 to configure the number of visible cards on the page.

Do this

.. card-carousel:: 2

   .. card:: Card 1

      Lorem ipsum dolor set atemit.

   .. card:: Card 2

      Lorem ipsum dolor set atemit.

   .. card:: Card 3

      Lorem ipsum dolor set atemit.

   .. card:: Card 4

      Lorem ipsum dolor set atemit.

For this

Card 1

Lorem ipsum dolor set atemit.

Card 2

Lorem ipsum dolor set atemit.

Card 3

Lorem ipsum dolor set atemit.

Card 4

Lorem ipsum dolor set atemit.

Example carousel

Step 1

Create a sandbox.

Step 2

Access the sandbox.

Step 3

Make configuration changes in the sandbox.

Step 4

Run the updated workflow from within the sandbox, including sandbox validations, to verify changes.

Step 5

Promote configuration changes to your production tenant.

Cards¶

Use the following card types:

Clickable cards
Standalone card

Note

Cards are used in grids.

Clickable cards¶

Use the .. card:: directive to add a clickable card to a page, and the configure the type of link.

Use the :link: attribute to define the URL, anchor reference, or topic filename.
Use the :link-type: attribute to define :doc: or :ref: link types.
Optional. Use the :link-alt: attribute to add alt text on hover.

The following types of clickable cards are available:

Cards with cross-site links
Cards with external links
Cards with links to topic headings within the same collection
Cards with links to topics within the same collection

Cards with cross-site links¶

Cards can link to pages in Amperity documentation that are not within the same collection.

Do this

.. card:: Card with cross-site link
   :link: https://docs.amperity.com/operators/api_profile.html
   :link-alt: Profile API

   This card links to https://docs.amperity.com/operators/api_profile.html.

For this

Card with cross-site link

This card links to https://docs.amperity.com/operators/api_profile.html.

Profile API

Cards with external links¶

Cards can link to external web pages.

Do this

.. card:: Card with external link
   :link: https://docs.amperity.com

   This card links to https://docs.amperity.com.

For this

Card with external link

This card links to https://docs.amperity.com.

Cards that link to sections¶

Cards can link to topic headings within the same collection.

Do this

.. card:: Card that links to topic heading within the same collection
   :link: rst-cards-standalone
   :link-type: ref
   :link-alt: Standalone cards

For this

Card that links to topic heading within the same collection

Standalone cards

Cards that link to topics¶

Cards can link to topics within the same collection.

Do this

.. card:: Card that links to topic within the same collection
   :link: styles
   :link-type: doc

   This is a card that uses a ``:doc:`` link to the Amperity Style Guide.

For this

Card that links to topic within the same collection

This is a card that uses a :doc: link to the Amperity Style Guide.

https://docs.amperity.com/user/index.html

Standalone cards¶

Use the .. card:: directive to add a standalone card to a page. This acts like an admonition, but without a title and with a neutral border that applies a subtle callout to a paragraph.

Do this

.. card:: What is UID2?

   .. include:: ../../amperity_reference/source/uid2.rst
      :start-after: .. uid2-overview-start
      :end-before: .. uid2-overview-end

For this

What is UID2?

Unified ID 2.0 (UID2) is an open-source framework that enables deterministic identity for advertising opportunities across the open internet for participants with access to the advertising ecosystem. UID2 is a standalone solution with a unique namespace and privacy controls that help participants meet local market requirements.

Code blocks¶

The .. code-block:: directive is defined by Sphinx:

.. code-block:: language
   :caption: sphinx.ext.todo
   :class: dark-code
   :emphasize-lines: 2,10-15
   :linenos:

   extensions = [
     "sphinx.ext.todo",
   ]
   todo_include_todos = True

where “language” is one of the code language highlight options.

Use :linenos: to add line numbers to the left side of a code block.
Use :emphasize-lines: to add emphasis to lines in a code block.
Use :caption: to add a title to a code block.
Use :class: with a value of “dark-code” to force a code sample to always be shown in dark mode formatting.

Captions¶

A caption is the title for a code block. Use the :caption: attribute to apply a string that becomes the title of the code block.

Do this

.. code-block:: python
   :caption: campaigns.py
   :linenos:

   import requests
   import json
   import csv

   # URL for Campaigns endpoint
   url = "https://tenant-name.amperity.com/api/campaigns"

   # Required headers
   headers = {
     'accept': 'application/json',
     'authorization': 'Bearer token', # add token here
     'amperity-tenant': 'tenant-name',
     'api-version': 'version'
   }

   # Query parameter for data template IDs
   payload = {
     # 'destination_data_template_id': ''
   }

   # Get the response from the Campaigns endpoint
   response = requests.request("GET", url, headers=headers, params=payload)
   response_json = response.json()

   # Extract headers from the first data entry
   headers = list(response_json["data"][0].keys())

   # Specify the output CSV file path
   csv_file_path = "campaigns.csv"

   # Write data to a CSV file
   with open(csv_file_path, mode='w', newline='') as file:
     writer = csv.DictWriter(file, fieldnames=headers)
     writer.writeheader()
     for entry in response_json["data"]:
       writer.writerow(entry)

   print("CSV file generated successfully.")

For this

campaigns.py¶

import requests
import json
import csv

# URL for Campaigns endpoint
url = "https://tenant-name.amperity.com/api/campaigns"

# Required headers
headers = {
  'accept': 'application/json',
  'authorization': 'Bearer token', # add token here
  'amperity-tenant': 'tenant-name',
  'api-version': 'version'
}

# Query parameter for data template IDs
payload = {
  # 'destination_data_template_id': ''
}

# Get the response from the Campaigns endpoint
response = requests.request("GET", url, headers=headers, params=payload)
response_json = response.json()

# Extract headers from the first data entry
headers = list(response_json["data"][0].keys())

# Specify the output CSV file path
csv_file_path = "campaigns.csv"

# Write data to a CSV file
with open(csv_file_path, mode='w', newline='') as file:
  writer = csv.DictWriter(file, fieldnames=headers)
  writer.writeheader()
  for entry in response_json["data"]:
    writer.writerow(entry)

print("CSV file generated successfully.")

Dark code¶

You can force code blocks to always use their dark code styles using the :class: with its value set to “dark-mode”.

Do this

.. code-block:: python
   :class: dark-code

   html_theme_options = {
       "dark_code": True
   }

For this

html_theme_options = {
    "dark_code": True
}

Line emphasis¶

Emphasize specific lines within a code block using the :emphasize-lines: attribute. Use a dash for sequential emphasis and a comma for separated emphasis. For example:

:emphasize-lines: 3-5 will emphasize lines 3 through 5.
:emphasize-lines: 3, 5 will emphasize lines 3 and 5, but not 4.
:emphasize-lines: 1, 3, 5-7, 25 will emphasize only lines 1, 3, 5, 6, 7, and 24.

Do this

.. code-block:: django
   :emphasize-lines: 1, 3, 5-7, 25

   {% extends "!nav-docs.html" %}
   {% set some_jinja = "12345" %}
   {% set navItems = [
     {
       "title": "Start Here",
       "iconClass": "fas fa-arrow-alt-circle-right fa-fw",
       "subItems": [
         {
           "title": "Start Here",
           "hasSubItems": false,
           "url": "/some_file.html"
         },
         {
           "title": "FAQ",
           "hasSubItems": false,
           "url": "/faq.html"
         },
         {
           "title": "Additional Resources",
           "hasSubItems": false,
           "url": "/resources.html"
         },
       ]
     },
   ] -%}

For this

{% extends "!nav-docs.html" %}
{% set some_jinja = "12345" %}
{% set navItems = [
  {
    "title": "Start Here",
    "iconClass": "fas fa-arrow-alt-circle-right fa-fw",
    "subItems": [
      {
        "title": "Start Here",
        "hasSubItems": false,
        "url": "/some_file.html"
      },
      {
        "title": "FAQ",
        "hasSubItems": false,
        "url": "/faq.html"
      },
      {
        "title": "Additional Resources",
        "hasSubItems": false,
        "url": "/resources.html"
      },
    ]
  },
] -%}

Line numbers¶

Add line numbers to code blocks using the :linenos: attribute.

Do this

.. code-block:: json
   :linenos:

   {
     "foo": [
       {
         "one": "12345",
         "two": "abcde",
         "three": "words"
       },
     ],
   }

For this

{
  "foo": [
    {
      "one": "12345",
      "two": "abcde",
      "three": "words"
    },
  ],
}

Tip

This attribute is sometimes picky and the build breaks and you discover that it works fine with four spaces instead of three, with everything aligned with the four spaces instead of three. Ask for help from the docs team if you run into this issue.

Code language highlights¶

Amperity uses the following code language highlights for differentiation within documentation. The highlighting applies to the use case within the technical content and is not always intended to match a specific code language.

Command shells
Config files
Data tables
HTML
JSON
JSON with Jinja
None
Python
REST APIs
reStructuredText
Ruby
Shell scripts
SQL queries
YAML
YAML with Jinja

Command shells¶

Assign console as the name of the code block for code blocks with command lines.

Important

Do not use the :linenos: attribute with command shells.

Do this

.. code-block:: console

   $ service stop

For this

$ service stop

Config files¶

Assign text as the name of the code block for code blocks with configuration settings.

Do this

.. code-block:: text
   :linenos:

   spark.setting.hours 1h
   spark.setting.option -User.timezone=UTC
   spark.setting.memory 20g

For this

spark.setting.hours 1h
spark.setting.option -User.timezone=UTC
spark.setting.memory 20g

Data tables¶

Assign mysql as the name of the code block for code blocks that show the inputs and outputs of processing data.

Important

Do not use the :linenos: attribute with data tables.

Do this

.. code-block:: mysql

   --------- ---------
    column1   column2
   --------- ---------
    value     value
    value     value
    value     value
   --------- ---------

For this

--------- ---------
 column1   column2
--------- ---------
 value     value
 value     value
 value     value
--------- ---------

HTML¶

Assign html as the name of the code block for code blocks with HTML.

Do this

.. code-block:: html
   :linenos:

   <div class="admonition warning">
     <p class="first admonition-title">Custom warning</p>
     <p class="last">The text for a custom warning that is built from raw HTML.</p>
   </div>

For this

<div class="admonition warning">
  <p class="first admonition-title">Custom warning</p>
  <p class="last">The text for a custom warning that is built from raw HTML.</p>
</div>

JSON¶

Assign json as the name of the code block for code blocks with JSON structures.

Do this

.. code-block:: json
   :linenos:

   {
     "foo": [
       {
         "one": "12345",
         "two": "abcde",
         "three": "words"
       },
     ]
   }

For this

{
  "foo": [
    {
      "one": "12345",
      "two": "abcde",
      "three": "words"
    },
  ],
}

JSON with Jinja¶

Some code blocks will refuse to parse when json is assigned to the code block. For these code blocks try using django, which supports non-standard JSON structures, such as those that combined JSON and Jinja templating.

Do this

.. code-block:: django
   :linenos:

   {% extends "!nav-docs.html" %}
   {% set some_jinja = "12345" %}
   {% set navItems = [
     {
       "title": "Start Here",
       "iconClass": "fas fa-arrow-alt-circle-right fa-fw",
       "subItems": [
         {
           "title": "Start Here",
           "hasSubItems": false,
           "url": "/some_file.html"
         },
         {
           "title": "FAQ",
           "hasSubItems": false,
           "url": "/faq.html"
         },
         {
           "title": "Additional Resources",
           "hasSubItems": false,
           "url": "/resources.html"
         },
       ]
     },
   ] -%}

For this

{% extends "!nav-docs.html" %}
{% set some_jinja = "12345" %}
{% set navItems = [
  {
    "title": "Start Here",
    "iconClass": "fas fa-arrow-alt-circle-right fa-fw",
    "subItems": [
      {
        "title": "Start Here",
        "hasSubItems": false,
        "url": "/some_file.html"
      },
      {
        "title": "FAQ",
        "hasSubItems": false,
        "url": "/faq.html"
      },
      {
        "title": "Additional Resources",
        "hasSubItems": false,
        "url": "/resources.html"
      },
    ]
  },
] -%}

None¶

Assign none as the name of the code block for situations that require code block-like formatting or in any situation where another code block name creates a build error.

Do this

.. code-block:: none
   :linenos:

   This is a none block. It is formatted as if it were code, but is not actually code.

   Can include code-like things:

   function_foo()
     does: something
   end

For this

This is a none block. It is formatted as if it were code, but is not actually code.

Can include code-like things:

function_foo()
  does: something
end

Python¶

Assign python as the name of the code block for Python code samples.

Do this

.. code-block:: python
   :linenos:

   import requests
   import json
   import csv

   # URL for Campaigns endpoint
   url = "https://tenant-name.amperity.com/api/campaigns"

   # Required headers
   headers = {
     'accept': 'application/json',
     'authorization': 'Bearer token', # add token here
     'amperity-tenant': 'tenant-name',
     'api-version': 'version'
   }

   # Query parameter for data template IDs
   payload = {
     # 'destination_data_template_id': ''
   }

   # Get the response from the Campaigns endpoint
   response = requests.request("GET", url, headers=headers, params=payload)
   response_json = response.json()

   # Extract headers from the first data entry
   headers = list(response_json["data"][0].keys())

   # Specify the output CSV file path
   csv_file_path = "campaigns.csv"

   # Write data to a CSV file
   with open(csv_file_path, mode='w', newline='') as file:
     writer = csv.DictWriter(file, fieldnames=headers)
     writer.writeheader()
     for entry in response_json["data"]:
       writer.writerow(entry)

   print("CSV file generated successfully.")

For this

import requests
import json
import csv

# URL for Campaigns endpoint
url = "https://tenant-name.amperity.com/api/campaigns"

# Required headers
headers = {
  'accept': 'application/json',
  'authorization': 'Bearer token', # add token here
  'amperity-tenant': 'tenant-name',
  'api-version': 'version'
}

# Query parameter for data template IDs
payload = {
  # 'destination_data_template_id': ''
}

# Get the response from the Campaigns endpoint
response = requests.request("GET", url, headers=headers, params=payload)
response_json = response.json()

# Extract headers from the first data entry
headers = list(response_json["data"][0].keys())

# Specify the output CSV file path
csv_file_path = "campaigns.csv"

# Write data to a CSV file
with open(csv_file_path, mode='w', newline='') as file:
  writer = csv.DictWriter(file, fieldnames=headers)
  writer.writeheader()
  for entry in response_json["data"]:
    writer.writerow(entry)

print("CSV file generated successfully.")

REST APIs¶

Assign rest as the name of the code block for code blocks with simple REST API examples.

Important

Do not use the :linenos: attribute with REST API examples unless the request or response has more than one line.

Do this

.. code-block:: rest
   :linenos:

   https://www.yoursite.com/endpoint/{some_endpoint}

For this

1https://www.yoursite.com/endpoint/{some_endpoint}

Note

Use the JSON code block style for the JSON request and response parts of the REST API.

reStructuredText¶

Assign rst as the name of the code block for code blocks with reStructuredText formatting.

Do this

.. code-block:: rst
   :linenos:

   This is some *reStructured* **Text** formatting.

   .. code-block:: none

      that has some(code);

For this

This is some *reStructured* **Text** formatting.

.. code-block:: none

   that has some(code);

Ruby¶

Assign ruby as the name of the code block for Ruby code samples.

Do this

.. code-block:: ruby
   :linenos:

   require 'uri'
   require 'net/http'

   url = URI("https://tenant-name.amperity.com/api/campaigns")

   http = Net::HTTP.new(url.host, url.port)
   http.use_ssl = true

   request = Net::HTTP::Get.new(url)
   request["accept"] = 'application/json'
   request["authorization"] = 'Bearer token'
   request["amperity-tenant"] = 'tenant-name'
   request["api-version"] = '2024-04-01'
   request["destination_data_template_id"] = 'ab-1CDEfGHIj'

   response = http.request(request)
   puts response.read_body

For this

require 'uri'
require 'net/http'

url = URI("https://tenant-name.amperity.com/api/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer token'
request["amperity-tenant"] = 'tenant-name'
request["api-version"] = '2024-04-01'
request["destination_data_template_id"] = 'ab-1CDEfGHIj'

response = http.request(request)
puts response.read_body

Shell scripts¶

Assign bash as the name of the code block for code blocks with shell script examples.

Do this

.. code-block:: bash
   :linenos:

   # The product and version information.
   readonly MARKUP_PRODUCT="markup-app"
   readonly MARKUP_VERSION="1.23.45-6"
   readonly MARKUP_RELEASE_DATE="2019-04-01"

For this

# The product and version information.
readonly MARKUP_PRODUCT="markup-app"
readonly MARKUP_VERSION="1.23.45-6"
readonly MARKUP_RELEASE_DATE="2019-04-01"

SQL queries¶

Assign sql as the name of the code block for code blocks with Spark SQL or Presto SQL examples.

Do this

.. code-block:: sql
   :linenos:

   SELECT *
   FROM Customers
   WHERE Last_Name='Smith'

For this

SELECT *
FROM Customers
WHERE Last_Name='Smith'

YAML¶

Assign yaml as the name of the code block for code blocks with YAML.

Do this

.. code-block:: yaml
   :linenos:

   config:
     - some_setting: 'value'
     - some_other_setting: 12345

For this

config:
  - some_setting: 'value'
  - some_other_setting: 12345

YAML with Jinja¶

Assign salt as the name of the code block for code blocks with YAML that embeds Jinja templating.

Do this

.. code-block:: salt
   :linenos:

   {%- set some_jinja = "12345" %}

   config:
     - some_setting: 'value'
     - some_other_setting: {{ some_jinja }}

For this

{%- set some_jinja = "12345" %}

config:
  - some_setting: 'value'
  - some_other_setting: {{ some_jinja }}

Why salt?

Using salt seems like an odd way to specify a code block that contains both Jinja and YAML.

SaltStack is a configuration management tool similar to Ansible, Chef, and Puppet. SaltStack uses a mix of Jinja and YAML to define system states. The salt lexer exists in Pygments originally because of how SaltStack defines system states, their use of Python and documentation built via Sphinx, and the need for a lexer that could parse a file with code samples that contain both Jinja and YAML.

Code block with sidebar¶

Code blocks can be configured to have a sidebar on the right side. In general do not use sidebars with code samples. The width of the topic just is not wide enough in most cases. This formatting option should be used sparingly and only if it improves understanding technical content.

Welcome to Chuck Data¶

                            .:::::::::
                          -----------=++
                        -***::::--::----:*#=
                      .**- %%%+:::+:---::#@@@
                     .:*+:.%++++==+:::==+#-+@
                     :#-.:===============*#%%
                   -:%:  .@@-        :@@=
                 :-:+=:-: ==%    +++. ==%    +#*
                   ::::=+=      +++++-     .+++
                 :--::+++++++@@@%   +@@@++++++%:...
                :+#*::=++++=@@@@@@ @@@@@@*+++%%%%-
               :::::#::=*#+=-@@@.. ..-@@-++*#%@
               ..:=*:::=*%%%*----@@@*---+#%%%%
                +=::::--+%%%%###++++++##%%%%%@
              :+::::::=++#%%%%%%%%%%%%%%%%#*+@
             #:::::::-++++%%%%%%@@@@@@%%%%*++%@
           .=-:::::::-++++*%%%@@@@@@@@@%%+++++@
           -*::::::::--=+++#%%@@@@@@@@@%#==+++@
          =+::------::--=++--#%%@@@@@@%%-++++%@
         *=:::---=+++-::--=+::+%%@@@%#+:=+++*%
         *=::---=++++++-::-    .%%%%:    =+#@
         *=::---=+++++#%#=    :+@@@@#-    =-
         *=::----=++++#%%%%  @@@@@@@@@@  --.
         **-:::----===:*%%@@@@@@@@@@@@@%-=*=
       ++-*+:::-------:*%%@@@@@@@@@@@@#--+#=
   :==--:::=#::::::::::*%%%@@@@@@@@%%*=--++-
  ==----::::-*:::::::::*%%%%@@@@@@%#-:::--
 #-::::::*#=   :        -%%%%%%%%%
 :------          ......:-------  .........

   ________  ___  ___  ___  ___  ________  ___  __
  |\   ____\|\  \|\  \|\  \|\  \|\   ____\|\  \|\  \
  \ \  \___|\ \  \\\  \ \  \\\  \ \  \___|\ \  \/  /|_
   \ \  \    \ \   __  \ \  \\\  \ \  \    \ \   ___  \
    \ \  \____\ \  \ \  \ \  \\\  \ \  \____\ \  \\ \  \
     \ \_______\ \__\ \__\ \_______\ \_______\ \__\\ \__\
      \|_______|\|__|\|__|\|_______|\|_______|\|__| \|__|

    ________  ________  _________  ________
   |\   ___ \|\   __  \|\___   ___\\   __  \
   \ \  \_|\ \ \  \|\  \|___ \  \_\ \  \|\  \
    \ \  \ \\ \ \   __  \   \ \  \ \ \   __  \
     \ \  \_\\ \ \  \ \  \   \ \  \ \ \  \ \  \
      \ \_______\ \__\ \__\   \ \__\ \ \__\ \__\
       \|_______|\|__|\|__|    \|__|  \|__|\|__|

Dropdowns¶

A dropdown shows a title string and a box that expands when the reader clicks it.

Do this

.. dropdown:: Dropdown title
   :icon: code

   Dropdown content

For this

Tip

Dropdowns should be used to present information that a reader does not need to see immediately and the title should identify what information appears.

Dropdowns should not be used when a section title should appear in the right-side navigation.

Content within a dropdown cannot be included elsewhere unless the entire dropdown is included. Inclusions may be used within a dropdown.

Expanded dropdowns¶

Use the :open: attribute to configure a dropdown to be expanded by default.

Do this

.. dropdown:: Dropdown title
   :open:

   This is the content of a dropdown that is configured to be expanded by default.

For this

Tip

Use an expanded dropdown within a series of dropdowns to show the best option or the default.

Escape characters¶

Use a backslash to override special meaning for characters, such as backslash or grave characters, to show the intended character.

Figures¶

Use the .. figure:: directive for images that require dark mode and light mode versions. Use the .. images:: directive for images that do not require both versions.

A figure requires two image configurations. Use the :figclass: attribute to specify “light-only” or “dark-only”. Be sure to configure the correct image path for dark and light mode.

Do this

.. figure:: ../../amperity_base/source/_static/connector-braze.png
   :figclass: light-only
   :width: 140 px
   :align: left

.. figure:: ../../amperity_base/source/_static/connector-braze-dark.png
   :figclass: dark-only
   :width: 140 px
   :align: left

For this

Grids¶

Use grids to build a list of links to other sections and pages in a topic collection or to pages outside Amperity documentation. Configure grids using a variety of linking options and apply Font Awesome or Octicon icons for additional flair. For example:

Amperity User Guides

Browse a collection of user guides to learn how to configure Amperity to support a variety of marketing and analytics use cases.

Amperity Operator Guides

Learn how to configure Amperity to support your brand’s marketing use cases. Load and shape datasets, build customer profiles, and enable downstream workflows.

https://docs.amperity.com/user/index.html

Style Guide

Contribute to Amperity content. Follow the style guide to ensure your contributions fit in.

Formatting Guide

Use reStructuredTest to format pages within Amperity documentation.

Formatting guide

Grid configuration options¶

Each grid has the following configuration options:

Columns
Gutter
Apply icons to grids
Link to external pages
Link to headers within topics
Link to topics
Padding
Surface

Important

Try to use the default values for gutter and padding and try to keep the number of columns to “1 1 2 2”. Use link types as needed.

Columns¶

The grid directive supports configuration for up to 4 screen resolution sizes.

For example:

.. grid:: 1 1 2 2
   :padding: 3
   :gutter: 4

The “1 1 2 2” values define the number of columns visible at extra small (1), small (1), medium (2), and large (2) screen resolutions. These will change as the screen resolution changes, including for responsive browser behaviors.

A grid should never have more than 4 columns at any screen resolution. 3 columns can work if the content within all grids is consistent and similar. The first two values should always be “1” and “1”.

Gutter¶

A gutter is the distance between individual cards in a grid. If it is too low the cards are too close together and if it is too large the cards are too far apart. When a grid does not have a gutter and the container class is surface the content appears as if there is a single card, but each individual grid is still formatted within the grid.

The values for :gutter: must be between “0” and “4”. Use “0” for no gutter. Use “1” for an extra small gutter, “2” for a small gutter, “3” for a medium gutter, and “4” for a large gutter. The default value is “4”.

Do this

.. grid:: 1 1 2 2
   :gutter: 4

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

For this

Setup guide

Style guide

Apply icons to grids¶

Apply icons to grids using Font Awesome or Octicons.

Grids and Font Awesome¶

Use Font Awesome icons within cards in a grid.

Do this

.. grid:: 1 1 2 2
   :gutter: 2
   :padding: 0
   :class-row: surface

   .. grid-item-card:: |u-euro| Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: |u-dollar| Style guide
      :link-type: doc
      :link: styles

For this

€ Setup guide

$ Style guide

Grids and Octicons¶

Use Octicons icons within cards in a grid.

Do this

.. grid:: 1 1 2 2
   :gutter: 2
   :padding: 0
   :class-row: surface

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

For this

Setup guide

Style guide

Link to external pages¶

Use the :link-type: option with a value of url for an external link. This does not require appending |ext_link| because the external link indicator icon is appended automatically by grid formatting.

Note

When :link-type: is not specified url is the default value.

Do this

.. grid-item-card:: Links
   :link-type: url
   :link: https://docs.amperity.com

For this

Links

Link to headers within topics¶

Use the :link-type: option with a value of ref for a link that behaves the same way as links to topic headings within the same collection.

Do this

.. grid-item-card:: Reference links
   :link-type: ref
   :link: rst-links

For this

Reference links

Links

Link to topics¶

Use the :link-type: option with a value of doc for a link that behaves the same way as links to topics within the same collection.

Do this

.. grid-item-card:: Terminology
   :link-type: doc
   :link: terminology

For this

Terminology

Padding¶

Padding is the distance from the outside edge to the location of the card. The default value for :padding: is “3”.

The values for :padding: must be between “0” and “5”. Use “0” for no padding. Use “1” - “5” to increase the distance from the outside edge.

Do this

.. grid:: 1 1 2 2
   :padding: 3

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

For this

Setup guide

Style guide

Surface¶

Surface defines if the grid has an outline or a solid background. When :class-container: surface is applied, each grid has a solid background.

Do this

.. grid:: 1 1 2 2
   :class-container: surface

   .. grid-item-card:: :octicon:`star` Setup guide
      :link-type: doc
      :link: setup

   .. grid-item-card:: :octicon:`zap` Style guide
      :link-type: doc
      :link: styles

For this

Setup guide

Style guide

Header levels¶

Up to four header levels may be used within a topic.

H1 headers are identified with equals symbols: ======
H2 headers are identified with dash symbols ------
H3 headers are identified with plus symbols ++++++
H4 headers are identified with carat symbols ^^^^^^

All header lengths must be 50 characters.

Headers are configured like this:

H1
==================================================

H2
--------------------------------------------------

H3
++++++++++++++++++++++++++++++++++++++++++++++++++

H4
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Note

H5 header levels are not supported.

Instead use bold strings like headers. See custom admonitions for an example of using bold strings in place of H5 headers.

Header markup length¶

All headers must be 50 characters long. This helps identify the header structure within a file.

All header strings cannot exceed the 50 character limit of the header and should be closer to 25 characters. This helps header structures be clean and organized and makes them easier to scan.

Icons¶

Amperity docs supports using the following icon libraries within documentation:

Font Awesome
Octicons

Note

Lucide icons are used within the Amperity Docs theme and may not be used within documentation pages.

Font Awesome¶

Font Awesome is an icon library supported by this theme and is the icon library that is used within Amperity. Use the same Font Awesome icon in documentation as used within Amperity. Prefer Font Awesome icons over Octicons. Amperity Docs support using any of the “brands”, “solid”, and “regular” icons.

Tip

Font Awesome icons work inline in paragraphs and lists and within admonitions.

Name	Do this	For this
Australian Dollar	\|u-dollar\|	$
Badge checkmark	\|system-yes\|
British Pound	\|u-pound\|	£
External link indicator	\|ext_link\|
GitHub	\|fa-github\|

Important

Font Awesome icons must be configured in the /amperity-docs/shared/names.txt file before they can be used in Amperity Docs.

Lucide¶

Lucide icons are embeded in CSS and appear in the navigation, are the toggle for switching between light, dark, and default modes, and in admonitions. Custom Lucide icons must be configured within CSS. Lucide icons may not be used inline in paragraphs, lists, or admonitions.

Octicons¶

Octicons is an icon library supported by this theme. Amperity Docs prefers Font Awesome icons over Octicons, where possible.

Tip

Octicons icons work inline in paragraphs and lists and within admonitions.

Some examples:

Name	Do this	For this
Alert	:octicon:`alert`
Bell	:octicon:`bell`
Book	:octicon:`book`
Browser	:octicon:`clock`
Clock	:octicon:`browser`

Images¶

Add images to the documentation using the .. images:: directive.

Use :width: to set the width of an image in pixels or percent.
Use :alt: to provide alt text for the image.
Use :align: to configure the location of the image on the page. Always set this value to “left”.
Use :no-scaled-link: to prevent the image from being clickable.

Important

You must use figures for images that require differentiation between dark and light mode.

Do this

.. code-block:: rst

   .. image:: ../../amperity_base/source/_static/card-chuck-data.png
      :width: 400 px
      :alt: Chuck Data
      :align: left
      :class: no-scaled-link

For this

Inclusions¶

Amperity content is designed to be reusable across content collections.

Content can be included

From a file
From a section within a topic

From a file¶

The /shared directory in Amperity docs has a collection of files that contain shareable content.

/shared directory contents¶

credentials_settings.rst
destinations_settings.rst
terms.rst

Inside these topics are reusable paragraphs. terms.rst contains ALL of the glossary terms used across ALL Amperity documentation. From terms.rst they are shared into the glossary and also into any other topic that needs that term.

For example:

**Moveable Ink**

.. term-moveable-ink-start

Moveable Ink helps marketers design dynamic creatives for personalized content experiences that combine business logic with access to real-time customer profiles.

.. term-moveable-ink-end

Moveable Ink is an entry in the terms.rst file. The title of the term–Moveable Ink–is followed by section references that surround a paragraph.

The glossary term for Moveable Ink is:

Moveable Ink helps marketers design dynamic creatives for personalized content experiences that combine business logic with access to real-time customer profiles.

The section references are:

“.. term-moveable-ink-start”
“.. term-moveable-ink-end”

To include the glossary term for Moveable Ink into a topic, such as into the Amperity glossary or into topics that mention Moveable Ink, use the .. include:: directive.

.. include:: ../../shared/terms.rst
   :start-after: .. term-moveable-ink-start
   :end-before: .. term-moveable-ink-end

The value for .. include:: is the relative path to the file with the sharable content.
Use the section reference start string–“.. term-moveable-ink-start”–as the value for the :start-after: attribute.
Use the section reference end string–“.. term-moveable-ink-end”–as the value for the :end-before: attribute.

Do this

.. include:: ../../shared/terms.rst
   :start-after: .. term-moveable-ink-start
   :end-before: .. term-moveable-ink-end

For this

Moveable Ink helps marketers design dynamic creatives for personalized content experiences that combine business logic with access to real-time customer profiles.

Glossary terms

The Amperity glossary formats inclusions differently than other topics. Each glossary term has a unique anchor reference and is formatted as a defintion list.

.. _m-moveable-ink:

**Moveable Ink**
   .. include:: ../../shared/terms.rst
      :start-after: .. term-moveable-ink-start
      :end-before: .. term-moveable-ink-end

From a topic¶

Every section in every topic in every collection is configured for sharing and may be reused.

For example:

/amperity_reference/source/uid2.rst¶

.. uid2-overview-start

Unified ID 2.0 (UID2) is an `open-source framework <https://unifiedid.com/docs/intro>`__ |ext_link| that enables deterministic identity for advertising opportunities across the open internet for participants with access to the advertising ecosystem. UID2 is a standalone solution with a unique namespace and privacy controls that help participants meet local market requirements.

.. uid2-overview-end

The section references are:

“.. uid2-overview-start”
“.. uid2-overview-end”

To include the paragraph into another topic use the .. include:: directive.

.. include:: ../../amperity_reference/source/uid2.rst
   :start-after: .. uid2-overview-start
   :end-before: .. uid2-overview-end

The value for .. include:: is the relative path to the file with the sharable content. All content collections have a /source/ directory within the path.
Use the section reference start string–“.. uid2-overview-start”–as the value for the :start-after: attribute.
Use the section reference end string–“.. uid2-overview-end”–as the value for the :end-before: attribute.

Do this

.. include:: ../../amperity_reference/source/uid2.rst
   :start-after: .. uid2-overview-start
   :end-before: .. uid2-overview-end

For this

Start and end policy¶

Adding the section reference start and end strings is a step completed during topic development. All content is written to be reusable even if it is not reused.

Inline markup¶

Paragraphs, lists, and other strings of text behave here like they do in any text editor, with line breaks before and after. Use any of these formatting options within paragraphs, lists, and tables:

Badges
Bold
Code strings
Italics

Badges¶

Badges are colored block of solid or outlined text for use inline within paragraphs, lists, and tables. Badges are not admonitions. Use badges sparingly as a way to draw the reader’s eye to information. For example, to call out New, Updated, or Deprecated features or for Required or Optional configuration settings.

Do this

:bdg-light:`New`

:bdg-success:`Updated`

:bdg-warning:`Deprecated`

For this

New

Updated

Deprecated

Badge types¶

The following table shows the available badge types by color. The theme-defined badge names, such as :bdg-primary: and :bdg-info-line: are mapped to Amperity-defined accent colors. The examples use “Solid” and “Outlined” as placeholder names. The name is a writer-defined string for the badge. Keep badge names short. One or two words.

Accent color	Solid badge	Outlined badge
	Do this :bdg-primary:`Solid` For this Solid	Do this :bdg-primary-line:`Outlined` For this Outlined
	Do this :bdg-secondary:`Solid` For this Solid
	Do this :bdg-success:`Solid` For this Solid	Do this :bdg-success-line:`Outlined` For this Outlined
	Do this :bdg-info:`Solid` For this Solid	Do this :bdg-info-line:`Outlined` For this Outlined
	Do this :bdg-danger:`Solid` For this Solid	Do this :bdg-danger-line:`Outlined` For this Outlined
	Do this :bdg-warning:`Solid` For this Solid	Do this :bdg-warning-line:`Outlined` For this Outlined
	Do this :bdg-dark:`Solid` For this Solid	Do this :bdg-dark-line:`Outlined` For this Outlined
	Do this :bdg-light:`Solid` For this Solid
	Do this :bdg-muted:`Solid` For this Solid

Bold¶

Use two asterisks ** around the word to apply bold formatting: **bold**. For example: this is bold content.

Caution

You may not use bold in headers or within the text strings for hyperlinks.

Code strings¶

Use two backticks around an inline code string.

Do this

This is an ``inline() code*string``.

For this

This is an inline() code*string.

Tip

Use sparingly. For SQL function and operator names use bold emphasis.

Italics¶

Use a single asterisk * around the word to apply italics formatting: *italics*. For example: this is italicized content.

Caution

You may not use italics in headers or within the text strings for hyperlinks.

Links¶

Use the following types of links within documentation.

Badges as links
Cross-site links
External links
Links to topic headings within the same collection
Links to topics within the same collection

Badges as links¶

A badge, in certain situtions, may be used in place of a cross-site or external link.

Do this

:bdg-link-primary:`https://docs.amperity.com`

:bdg-link-primary-line:`https://docs.amperity.com`

For this

Use cases for single sign-on (SSO)

Tip

Review the list of badge types. The difference between using a badge inline versus a link is:

This

:bdg-primary:`https://docs.amperity.com`

:bdg-link-primary-line:`https://docs.amperity.com`

For this

https://docs.amperity.com

Cross-site¶

A cross-site link is a link to a page in Amperity docs that is not in the same docs collection. The syntax for a cross-site link is:

`string <../relative/path/to/page.html#anchor-references-are-ok>`__

Replace “string” with text.
Replace “../relative/path/to/page.html” with the relative URL. For example: ../reference/sso.html or ../reference/sso.html#use-cases.
Be sure to append the double underscores.
Do not add |ext_link| to the end because the reader will not leave the Amperity docs site.

Do this

`Use cases for single sign-on (SSO) <../reference/sso.html#use-cases>`__

For this

Important

Internal links defined by relative paths omit the target="_blank" property from the link.

Internal links with relative paths will open in the same browser tab.
Internal links with full HTTPS path will open in a new browser tab like external links.

This behavior is managed by the “remove target from internal links” Javascript in /_templates/partials/extra-head.html.

External¶

An external link is a link to a page that exists outside Amperity documentation. The syntax for an external link is:

`string <URL>`__ |ext_link|

Replace “string” with text.
Replace “URL” with the full URL. For example: https://wwww.braze.com/docs/ or https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content.
Be sure to append the double underscores.
Use |ext_link| to apply an icon that indicates the link takes the reader from the Amperity docs site.

Do this

`Braze documentation <https://www.braze.com/docs/>`__ |ext_link|

For this

Braze documentation

Headers in same site¶

A reference link is a link to an anchor reference located within the same document collection. The anchor reference must be unique.

Do this

:ref:`rst-links-reference`

or:

:ref:`Headers in same site <rst-links-reference>`

For this

Headers in same site

A reference link without the “string” value uses the header string just below the anchor reference. Use the “string” value to blend reference links into the language you use in a paragraph, a list, or a table.

Important

You cannot use reference links to link to a section in a topic located in another document collection. Use an external link within the docs site to define the link.

Note

The link in the example is self-referential. You should not do this.

Topics in same site¶

A topic link is a link to a topic, such as to the Amperity Style Guide located within the same document collection. The topic reference must be a filename.

Do this

:doc:`styles`

or:

:doc:`Amperity Style Guide <styles>`

For this