Docs
日本語
Labs

Content Style Guide (Examples)

This page exists to help us audit the look and feel across light/dark mode, desktop/mobile, and common content patterns.

Glossary tooltips

These terms should show a tooltip on hover/focus (and should not link inside code): SIM, LoRaWAN, and SIMカード.

Callouts (SDS notices)

Info notice using ds-notice --info.

Warning notice using ds-notice --warning.

Alert notice using ds-notice --alert.

Note callout using the info style.

Tip callout using the info style.

Important callout using the warning style.

Caution callout using the warning style.

Danger callout using the alert style.

Success notice using ds-notice --success.

Badges and status tags

Inline tags should render as SDS tags:

  • Plans: plan01s planX3-EU plan-D (Data-only)
  • Coverage: LTE 5G NB-IoT
  • Status tags: New Beta Preview Deprecated Success Pending

Release phase notice

Release phase: Early Access

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

Inline icons

Download the icon set or search the docs .

Open the User Console

Use menu paths inline to show click trails:

FileExportPDF

Operator API: Operator:authenticateAPI

Permission link: User:updateUserPermissionPermission

Sandbox API: Subscriber:sandboxCreateSubscriberSandbox

Krypton API: SORACOM Krypton:bootstrapAwsIotThingKrypton

Table of contents

The right-rail table of contents is automatic on docs/guides/learn pages.

Prefer authored next steps, collection navigation, and prev/next links. The current site shell does not use a generic Related Articles component.

Tabs (SDS ds-tabs)

Use tabs for short, side-by-side alternatives (regions, languages, variants).

Keep tab content compact; if it scrolls, consider a dedicated section instead.

This is placeholder content to validate spacing and typography.

Browser frame

User Console

This is a placeholder for a console screenshot or walkthrough step.

Annotation

This is an annotation block for supplemental notes.

Images

Shared images (logos, commonly reused diagrams, etc.) live under public/images/ and are referenced with absolute paths:

Placeholder hero illustration Placeholder diagram

public/assets/ is for generated machine data (for example coverage JSON), not for editorial image libraries.

For page-specific images, store the image alongside the Markdown file (same folder, or a subfolder like ./images/) and reference it with a relative path:

Local content image (side-by-side)

Inline code

Inline code should be legible and easy to scan, for example: soracom.io, beam.soracom.io, or SIM_GROUP_ID.

Inline formatting helpers

Required fields are marked in tables and forms.

Avoid inline-style shortcodes like underline. Use standard Markdown emphasis or semantic HTML instead.

Underlined label (only if truly needed): SIM Group Name.

Prerequisites

{{% prerequisites __fenced="true" "Before you begin" %}}

  • An active Soracom account.
  • An enabled SIM card. {{% /prerequisites __fenced="true" %}}

Code

curl -X GET "https://api.soracom.io/v1/subscribers" \
  -H "Accept: application/json"
{ "example": true, "note": "This is placeholder JSON for formatting." }

For code + output pairs, use the code example helper so the copy button only copies the code sample:

SH.sh
Request
curl -X GET "https://api.soracom.io/v1/subscribers" \
  -H "Accept: application/json"
Response
{ "result": "ok" }

To embed public GitHub source, add repo, path, and ref attributes (the block renders a View on GitHub action).

YouTube embed

Mermaid diagram

flowchart LR
  Device --> Gateway --> Cloud

Support inquiry CTA

Contact Support

API expansion controls

Toggle all API details on this page.
ShowHide

Page break

Tables

ItemDescriptionNotes
AShort valueOK
BA longer description to validate wrapping and cell paddingCheck mobile
CAnother rowOK

Advanced tables (sticky header/column)

Use the advanced-table shortcode for complex tables that need sticky headers or a pinned first column.

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

Auth-gated sections (example)

This page has hasAuthGatedSections: true so the layout displays a subtle sign-in banner above the content. Use it for pages that embed private snippets or other gated widgets.

Scheduled publishing + coming soon

Use publishAt to delay visibility until a specific date/time (UTC). Pages with a future publishAt are hidden from navigation, indexes, RSS, and sitemap until the next build after the timestamp.

Use comingSoon: true to show a "Coming soon" notice at the top of a page. Optional fields:

  • comingSoonMessage: customize the blurb shown in the notice.
  • waitlistUrl: link to a signup form.
  • waitlistLabel: override the CTA label.
  • waitlistDescription: small helper text under the CTA.

Shortcode support snapshot

Supported in Markdown today:

  • Callouts: > [!INFO] / > [!WARNING] / > [!ALERT]
  • Tabs: :::tabs + :::tab
  • API reference links: [api-reference=...], [sandbox-api-reference=...], [krypton-api-reference=...], [user-permission=...]
  • Menu paths: :::menu
  • Tags/badges: [plan=...], [coverage=...], [tag=...]
  • Inline icons: [fa=...]
  • Media: :::youtube
  • Diagrams: fenced ```mermaid blocks
  • Layout helpers: :::annotation, :::button, :::ui-browser
  • Misc: [required/], :::prerequisites, :::release-phase
  • Support/UX: :::support-inquiry, :::open-close-apis, :::page-break

Legacy syntax is documented in the shortcode gallery for migration reference only (not supported in content).
Search Esc to close / Enter to view results