Advanced Formatting

Admonitions

In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.

Example:

:::info note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

note

Some content with Markdown syntax. Check this api.

tip

Some content with Markdown syntax. Check this api.

caution

Some content with Markdown syntax. Check this api.

Tabs

You can use the <Tabs> component in your markdown to create tabbed content. This is useful for organizing content that is related but not necessarily sequential.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="core-features">
  <TabItem value="system" label="System" default>
  As software grows in complexity, systems offer a way to visualize and manage entire software ecosystems. A system comprises various components and resources, often providing public APIs. This abstraction lets developers focus on the bigger picture without worrying about specific details. For instance, a playlist management system might consist of multiple services for updating, searching, and storing playlists, an API for external communication, and data streams for playlist updates.
  </TabItem>
  <TabItem value="components" label="Components">
  A component is any software element—be it a mobile feature, website, backend service, or data pipeline. Each component is tracked in source control and may implement or consume APIs. Components may also depend on other components or resources at runtime.
  </TabItem>
  <TabItem value="resources" label="Resources">
  A resource refers to the infrastructure required by a component to function at runtime, such as databases, messaging topics, storage buckets, or CDNs. By modeling resources alongside components and systems, Alchemy helps teams visualize resource footprints and create tooling for efficient management.
  </TabItem>
  <TabItem value="groups" label="Groups">
  A group represents an organizational entity, such as a team, business unit, or a collection of users with shared interests.
  </TabItem>
  <TabItem value="users" label="Users">
  A user represents individuals, such as employees or contractors, and defines their association with various `Group` entities in the catalog.  This connection is crucial for understanding how authentication and user management work within the Alchemy ecosystem, further detailed in [auth](https://backstage.io/docs/auth).  
  </TabItem>
</Tabs>

System
Components
Resources
Groups
Users

As software grows in complexity, systems offer a way to visualize and manage entire software ecosystems. A system comprises various components and resources, often providing public APIs. This abstraction lets developers focus on the bigger picture without worrying about specific details. For instance, a playlist management system might consist of multiple services for updating, searching, and storing playlists, an API for external communication, and data streams for playlist updates.

A user represents individuals, such as employees or contractors, and defines their association with various Group entities in the catalog. This connection is crucial for understanding how authentication and user management work within the Alchemy ecosystem, further detailed in auth.

Displaying a default tab

The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding default to one of the tab items.

<Tabs queryString="annotations">
  ...
  <TabItem value="aws" label="AWS" default>
  ...
  </TabItem>
</Tabs>

Creating shareable tab links

You can create links that automatically open specific tabs when shared. This is particularly useful for directing users to specific content, such as linking to specific documentation.

Use the queryString prop in your Tabs component. The value you provide will be used in the URL.

Windows: yoursite.com/docs?current-os=windows
macOS: yoursite.com/docs?current-os=macos

When someone opens these shared URLs, they'll see the correct tab automatically selected.

<Tabs queryString="current-os">
  <TabItem value="windows" label="Windows">
    <p>Windows</p>
  </TabItem>
  <TabItem value="macos" label="macOS">
    <p>macOS</p>
  </TabItem>
</Tabs>

Pro Tip

When queryString is set to true (without a value), the system automatically uses the groupId value as the search parameter name.

<Tabs groupId="current-os" queryString>
  <TabItem value="windows" label="Windows">
    <p>Windows</p>
  </TabItem>
  <TabItem value="macos" label="macOS">
    <p>macOS</p>
  </TabItem>
</Tabs>

When the page loads, any tab selection in the URL takes precedence over the groupId settings (which use localStorage).

Details

The <details> element creates a disclosure widget that reveals information only when it is toggled to an "open" state. A <summary> element is required to serve as a label.

<details>
  <summary>Details</summary>
  <p>Something small enough to escape casual notice.</p>
</details>

Details

Something small enough to escape casual notice.

This widget is usually displayed on the screen with a small rotating triangle that indicates whether it is open or closed, along with the corresponding label.

A <details> widget can exist in one of two states. In its default closed state, only the triangle and the label from the <summary> are visible. When opened, it expands to reveal the details inside.

Tooltips

Tooltips can be added to any word or phrase by wrapping it with the <Tooltip> component. This is useful for providing additional context or information about a particular word or term, espcially glossary terms.

<p><a href="#" data-tooltip>
    word or phrase
    <div class="tooltip-content">
        definition or explanation       
    </div>
</a></p>

word or phrase

Tooltips with hyperlinks

<p><a href="#" data-tooltip>
    Passkeys
    <div class="tooltip-content">
        Passkeys are a phishing-resistant alternative to traditional authentication factors (such as identifier/password) that offer an easier and more secure login experience to users. Passkeys are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) specifications.<p><a href="https://auth0.com/docs/authenticate/database-connections/passkeys">Learn more</a></p>        
    </div>
</a></p>

Passkeys

Tooltips styles (CSS)

Make sure to add the following CSS to your site to style the tooltips.

/* Tooltips */

/* Add this attribute to the element that needs a tooltip */
[data-tooltip] {
    position: relative;
    cursor: pointer;
    border-bottom: 1px dashed var(--ifm-color-primary);
    display: inline;
}

/* Hide the tooltip content by default */
.tooltip-content {
    visibility: hidden;
    opacity: 0;
    pointer-events: none;
    transition: opacity 0.2s ease-in-out;
}

/* Position tooltip above the element */
.tooltip-content {
    position: absolute;
    top: 115%;
    left: 50%;
    margin-bottom: 5px;
    margin-left: -80px;
    padding: 15px;
    width: 370px;
    border-radius: 6px;
    background-color: #000;
    background-color: hsla(0, 0%, 10%, 0.9);
    color: #fff;
    text-align: left;
    font-size: 14px;
    line-height: 1.2;
    z-index: 2;
}

/* Triangle hack to make tooltip look like a speech bubble */
.tooltip-content::after {
    content: " ";
    position: absolute;
    top: -5px;
    left: 50%;
    margin-left: -5px;
    width: 0;
    border-bottom: 5px solid #000;
    border-bottom: 5px solid hsla(0, 0%, 10%, 0.9);
    border-right: 5px solid transparent;
    border-left: 5px solid transparent;
    font-size: 0;
    line-height: 0;
}

/* Show tooltip content on hover */
[data-tooltip]:hover .tooltip-content {
    visibility: visible;
    opacity: 1;
    pointer-events: auto;
}

Markdown front matter

front matter example
---
title: Getting Started with React
sidebar_label: React # (Optional) Use this to shorten the title in the sidebar
id: get-started-react
description: 'Create a developer account and connect it to our sample application. This application demonstrates common workflows, like creating realms, applications, and passkeys (public-private key pairs) for user authentication.'
keywords: [get started, react] # Use this to improve search results
last_update:
   date: 09/27/2024 
   author: Patricia McPhee # Topic SME
doc_type: get-started
displayed_sidebar: mainSidebar
role:  # (Optional) Use this to indicate that the topic is for Admins.
   - Admins
---

Required metadata fields

Required front matter
---
title:  
id: 
description: '...'
keywords: [keyword1, keyword2]
last_update:
   date: 09/27/2024 
   author: Patricia McPhee # Replace with the topic SME or primary author of the topic
doc_type: reference # Topic type (how-to, overview, concept, reference, troubleshooting)
displayed_sidebar: mainSidebar # Default sidebar
---

Field	Type	Description
`id`	string	A unique identifier for the document. It must not be duplicated within the documentation set.
`title`	string	The title of the document, written in title case, representing the primary subject of the topic.
`description`	string	A concise summary of the document's content, between 20-50 words, written to provide clear context.
`keywords`	string	An array of terms or phrases that represent the document's content, helping improve searchability. The search plugin relies on these keywords rather than crawling the entire page, so ensure they accurately reflect the document's key topics.
`doc_type`	string	The category or type of the document, such as reference, how-to, overview, concept, or troubleshooting.
`last_update:date`	string	The date when the document was last updated with significant changes. This date is displayed in search results, so it should reflect meaningful updates rather than minor edits like typos.
`last_update:author`	string	The name of the topic's subject matter expert (SME) or primary contributor, responsible for the content.
`displayed_sidebar`	string	Specifies the sidebar in which the document will appear, for example, mainSidebar (default).

Optional metadata fields

You can also include the following front matter fields based on when to use them.

Field	Type	Default	When to use
`sidebar_label`	string	`title`	The text shown in the sidebar for this document should differ from the title field.
`hide_title`	boolean	`false`	Set to `true` if the document's title should not appear at the top of the page. Useful for custom page designs like a home page.
`hide_table_of_contents`	boolean	`false`	Set to `true` if the table of contents should not appear in the sidebar. Useful for short documents or landing pages.

Admonitions

Tabs

Displaying a default tab

Creating shareable tab links

Details

Tooltips

Basic tooltip

Tooltips with hyperlinks

Tooltips styles (CSS)

Markdown front matter

Required metadata fields

Optional metadata fields