Shortcode Gallery

Reference for supported content shortcodes, visual helpers, and migration syntax

This page documents the authoring helpers available in the Astro docs site. Use native Markdown when it meets the need; reach for shortcodes when you need styled UI components.

Markdown rendering

Standard Markdown works out of the box. No shortcodes needed for these patterns.

Text formatting

Usage (Markdown)

**Bold text**, *italic text*, and ~~strikethrough text~~.

Use `inline code` for UI labels, API parameters, and literal values.

Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> to open the command palette.

Rendered

Bold text, italic text, and ~~strikethrough text~~.

Use inline code for UI labels, API parameters, and literal values.

Press Ctrl + Shift + P to open the command palette.

Links and images

Usage (Markdown)

Visit the [Soracom User Console](https://console.soracom.io) or see the [API reference](/api-reference).

![Soracom logo](/images/soracom-logo.svg)

Rendered

Visit the Soracom User Console or see the API reference.

Blockquotes

Usage (Markdown)

> Connectivity is the foundation of IoT. Without reliable data transfer,
> even the best sensors are just expensive paperweights.

Rendered

Connectivity is the foundation of IoT. Without reliable data transfer, even the best sensors are just expensive paperweights.

Lists

Usage (Markdown)

Unordered list:

- Activate your SIM
- Register the device
- Configure the group

Ordered list:

1. Log in to the User Console
2. Navigate to SIM Management
3. Click **Register SIM**

Task list:

- [x] Create account
- [x] Order SIM
- [ ] Activate SIM
- [ ] Connect device

Rendered

Unordered list:

Activate your SIM
Register the device
Configure the group

Ordered list:

Log in to the User Console
Navigate to SIM Management
Click Register SIM

Task list:

Create account
Order SIM
Activate SIM
Connect device

Tables

Usage (Markdown)

| Plan | Data rate | Region |
|------|-----------|--------|
| plan01s | Up to 2 Mbps | Global |
| plan01s-LDV | Low data volume | Global |
| planArc01 | Varies | Global |

Rendered

Plan	Data rate	Region
plan01s	Up to 2 Mbps	Global
plan01s-LDV	Low data volume	Global
planArc01	Varies	Global

Horizontal rules

Usage (Markdown)

Content above the rule.

---

Content below the rule.

Rendered

Content above the rule.

Content below the rule.

Callouts

Use GitHub-style callout syntax for info, warning, and alert notices:

Usage (Markdown)

> [!INFO]
> Info notice for helpful context.

> [!WARNING]
> Warning for content that needs extra attention.

> [!ALERT]
> Critical information that must not be missed.

Rendered

Info notice for helpful context.

Warning for content that needs extra attention.

Critical information that must not be missed.

Code blocks

Usage (Markdown)

```bash
soracom --version
```

Rendered

soracom --version

Mermaid diagrams

Usage (Markdown)

```mermaid
flowchart LR
  Device --> Gateway --> Cloud
```

Rendered

flowchart LR
  Device --> Gateway --> Cloud

Glossary tooltips

Terms defined in the glossary are auto-linked. No shortcode needed.

Usage (Markdown)

SIM, LoRaWAN, and SIM card.

Rendered

SIM, LoRaWAN, and SIM card.

Shortcodes

Custom authoring helpers that compile to SDS-styled UI. Block-level shortcodes use the fenced form:

:::name ...args key="value"
...content...
:::/name

Callouts (semantic)

Use semantic callouts for domain-specific notices. For generic info/warning/alert, use the Markdown callout syntax above.

Supported types: api, fees, cli, beta, preview, new.

Usage (Markdown)

:::notice type="api"
Use this callout for API-specific limits, auth, or behavior notes.
:::/notice

:::notice type="fees"
Highlight pricing, billing, or cost-impacting details.
:::/notice

:::notice type="cli"
Use this callout for CLI tips and command guidance.
:::/notice

:::notice type="beta"
Beta features are available for early feedback.
:::/notice

:::notice type="preview"
This feature is in preview and may change before GA.
:::/notice

:::notice type="new"
New in this release: automated SIM activation.
:::/notice

Rendered

API

Use this callout for API-specific limits, auth, or behavior notes.

Fees

Highlight pricing, billing, or cost-impacting details.

CLI

Use this callout for CLI tips and command guidance.

Beta

Beta features are available for early feedback.

Preview

This feature is in preview and may change before GA.

New

New in this release: automated SIM activation.

Annotation

Small, local callouts that shouldn't interrupt reading flow.

Usage (Markdown)

:::annotation
This is an inline annotation block used for small callouts near the exact content they relate to.
:::/annotation

Rendered

This is an inline annotation block used for small callouts near the exact content they relate to.

Tabs

For short, parallel alternatives (regions, languages, small variants). If content scrolls, prefer a dedicated section.

Usage (Markdown)

:::tabs "Overview" "Details"
:::tab for="1"
This content is in the first tab.
:::/tab
:::tab for="2"
This content is in the second tab.
:::/tab
:::/tabs

Rendered

Overview
Details

This content is in the first tab.

This content is in the second tab.

Code example

Single, consistent code surface with file-type icon, copy button, and optional collapsible output.

Usage (Markdown)

:::code-example title="Request"
```bash
curl -X GET "https://api.soracom.io/v1/subscribers" \
  -H "Accept: application/json"
```

:::code-output title="Response"
```json
{ "result": "ok" }
```
:::/code-output
:::/code-example

Rendered

curl -X GET "https://api.soracom.io/v1/subscribers" \
  -H "Accept: application/json"

Response

{ "result": "ok" }

Inline output

Use inline="true" when the output should appear immediately below the command (no disclosure).

Usage (Markdown)

:::code-example title="Shell"
```bash
soracom subscribers list --profile sandbox
```

:::code-output title="Output" inline="true"
```text
Subscribers: 2
SIM Group: sandbox-demo
```
:::/code-output
:::/code-example

Rendered

soracom subscribers list --profile sandbox

Output

Subscribers: 2
SIM Group: sandbox-demo

Remote GitHub source

Usage (Markdown)

:::code-example repo="soracom/soracom-cli" path="README.md" ref="master"
:::/code-example

Rendered

Loading…

Advanced tables

Use for complex tables where you need sticky headers or a pinned first column. For simple tables, use standard Markdown.

Usage (Markdown)

:::advanced-table sticky="header,first-column"
| Plan | Best for | Notes |
| --- | --- | --- |
| 01s | Prototypes | Entry tier |
| 10s | Scale | Production |

:::/advanced-table

Rendered

Plan	Best for	Notes
01s	Prototypes	Entry tier
10s	Scale	Production

Prerequisites and limitations

Collapsible disclosure blocks for prerequisites and known limitations.

Usage (Markdown)

:::prerequisites "Before you begin"
- An active Soracom account.
- An enabled SIM card.

:::/prerequisites

:::limitations
- Limited to Cat-M1/LTE-M in this release.

:::/limitations

Rendered

Before you begin

An active Soracom account.
An enabled SIM card.

Limitations

Limited to Cat-M1/LTE-M in this release.

Release phase notice

Usage (Markdown)

:::release-phase "Release phase: Early Access"
This feature is in early access and may change before general availability.
:::/release-phase

Rendered

Release phase: Early Access

This feature is in early access and may change before general availability.

Visual elements

Browser frame

Wrap UI screenshots or short HTML snippets that represent in-product UI.

Usage (Markdown)

:::ui-browser title="User Console"

This is placeholder content inside a browser frame.

:::/ui-browser

Rendered

User Console

This is placeholder content inside a browser frame.

Image frame

Image with a fullscreen overlay. The overlay fits the image to the screen and keeps the caption visible.

Usage (Markdown)

:::image-frame src="/images/placeholders/placeholder-photo.svg" caption="Coverage UI mockup" alt="Coverage UI mockup"

Rendered

Coverage UI mockup

YouTube embed

Usage (Markdown)

:::youtube "https://www.youtube.com/embed/VgngPO5gQaE"

Rendered

Carousels

Horizontally scrollable card lists. Three types available:

Usage (Markdown)

:::carousel type="partners" limit=10 mock=true

:::carousel type="store-items" ids="sim-starter-kit,usb-modem,evaluation-sim" limit=3 mock=true

:::carousel type="use-cases" category="fleet" limit=5 mock=true

Rendered

Partner Space (mock): horizontally scrollable list

AWS

Connectivity + IoT integrations at cloud scale.

Azure

Enterprise cloud + device management integrations.

Google Cloud

Analytics + data pipelines for IoT telemetry.

Datadog

Observability for fleet and device health.

Snowflake

Unified data warehouse for IoT analytics.

Twilio

Messaging + notifications for device workflows.

Okta

Identity and access management integrations.

MongoDB

Flexible storage for device telemetry.

Confluent

Streaming data pipelines for event flows.

Grafana

Dashboards for network and device visibility.

Contact Soracom to connect with a partner

IoT SIM Starter Kit

Starter

Get a SIM + basic accessories to start prototyping quickly.

Open store item

USB LTE Modem

Device

Connectivity hardware for rapid bring-up and testing.

Open store item

Evaluation SIM

SIM

Order a small batch for early pilots and PoCs.

Open store item

Use-case carousel (mock): horizontally scrollable list

SIM lifecycle basics

Provision, activate, and manage SIMs at scale.

Getting startedExplore

Device onboarding

Bring devices online with starter hardware and guides.

DeviceExplore

Contact Soracom about a use case

Inline helpers

Badges

Mark plans, coverage, and lifecycle status inline.

Usage (Markdown)

Plans: [plan=01s/] [plan=10s/]
Coverage: [coverage=lte/] [coverage=5g/]
Status: [tag=beta/] [tag=deprecated/] [tag=online/]
Required: [required/]

Rendered

Plans: plan01s plan10s Coverage: LTE 5G Status: Beta Deprecated Online Required:

Icons

Usage (Markdown)

Download the icon set [fa=download/] or search the docs [fa=search/].

Rendered

Download the icon set or search the docs .

API reference links

Deep links into the API reference pages.

Usage (Markdown)

Operator API: [api-reference=Operator:authenticate/]
Krypton API: [krypton-api-reference=SORACOM Krypton:bootstrapAwsIotThing/]
Sandbox API: [sandbox-api-reference=Subscriber:sandboxCreateSubscriber/]
Permission: [user-permission=User:updateUserPermission/]

Rendered

Operator API: Operator:authenticateAPI Krypton API: SORACOM Krypton:bootstrapAwsIotThingKrypton Sandbox API: Subscriber:sandboxCreateSubscriberSandbox Permission: User:updateUserPermissionPermission

Usage (Markdown)

:::menu "File" "Export" "PDF"

Rendered

Button link

Usage (Markdown)

:::button href="https://console.soracom.io"
Open the User Console
:::/button

Rendered

Open the User Console

Utility shortcodes

API expansion controls

For long API pages — expand/collapse all details at once.

Usage (Markdown)

:::open-close-apis

Rendered

Toggle all API details on this page.

Show Hide

Page break

Usage (Markdown)

:::page-break

Rendered

Support inquiry CTA

Usage (Markdown)

:::support-inquiry
ticket_form_id: 123456
tf_123456789: Example support issue
:::/support-inquiry

Rendered

Contact Support

Zendesk FAQ embed

Usage (Markdown)

:::zendesk-faq section="Getting Started" limit=3 mock=true

Rendered

FAQs

Getting Started

How do I activate a SIM?

Start with SIM Management, then follow the "Activate Your SIM" guide to register and connect.

How do I estimate costs?

Use the pricing estimator to model devices, monthly data, and region, then validate with plan limits.

Where do I find API examples?

See "Using the API" and the API Reference "Try It" panel for request/response examples.

Demo pair

For showing Usage/Rendered or Before/After pairs inside a single demo card on any content page.

Usage (Markdown)

:::demo-pair
:::demo-panel title="Usage"
:::code-example
```md
:::annotation
Use annotation for small inline callouts.
:::/annotation
```
:::/code-example
:::/demo-panel

:::demo-panel title="Rendered"
:::annotation
Use annotation for small inline callouts.
:::/annotation
:::/demo-panel
:::/demo-pair

Rendered

Usage

:::annotation
Use annotation for small inline callouts.
:::/annotation

Rendered

Use annotation for small inline callouts.

Legacy shortcodes

Legacy Hugo/Grav syntax is listed here for migration reference only. The current pipeline still carries limited compatibility handling for some legacy constructs, but do not author new content with them. Migrate to the supported equivalents before publishing.

Legacy syntax	Migrate to
`!!! Warning:` / `!!!! Alert:` (Grav callouts)	Markdown callouts
`[block=fees]...[/block]` (Grav block)	`:::notice type="fees"`
`{{</* warn />}}` / `{{</ info */>}}` (Hugo callouts)	Markdown callouts
`{{</* deprecated */>}}` (Hugo)	`:::notice type="beta"` or `[tag=deprecated/]`
`{{</* text />}}` / `{{</ underline />}}` / `{{</ nowrap */>}}` (Hugo inline)	Native Markdown or semantic HTML
`[blink=color]...[/blink]` (Grav blink)	Describe the pattern in prose
`{{<icon-set/icon ID>}}` / `{{<icon-set/icons>}}` (Hugo icons)	`[fa=name/]` or images in tables
`{{</* multiple-code-fences */>}}` (Hugo)	Separate code blocks or `:::code-example`
`{{<states "class" "label">}}` (Hugo states)	`[tag=status/]`
`{{<th>}}` / `{{<td>}}` / `{{<nowrap>}}` (Hugo table helpers)	Standard Markdown tables
`[ui-tabs]` / `[ui-tab]` (Grav tabs)	`:::tabs`
`{{</* toc />}}` / `{{</ table-of-contents-related-pages */>}}` (Hugo TOC)	Automatic (right-rail TOC)

Markdown rendering

Text formatting

Links and images

Blockquotes

Lists

Tables

Horizontal rules

Callouts

Code blocks

Mermaid diagrams

Glossary tooltips

Shortcodes

Callouts (semantic)

Annotation

Tabs

Code example

Inline output

Remote GitHub source

Advanced tables

Prerequisites and limitations

Release phase notice

Visual elements

Browser frame

Image frame

YouTube embed

Carousels

Inline helpers

Badges

Icons

API reference links

Menu paths

Button link

Utility shortcodes

API expansion controls

Page break

Support inquiry CTA

Zendesk FAQ embed

Demo pair

Legacy shortcodes