tabs and modes

Note that this page was generated by Agent mode in GitHub Copilot and then manually modified.

Purpose

These shortcodes let you present alternative instructions or code paths (e.g. Bash vs PowerShell, or Portal vs CLI) in a compact UI. They are progressively enhanced by a small JavaScript file so content still appears (all expanded) if JavaScript is disabled.

• tabs + tab: Lightweight code/text variants.
• modes + mode: Rich, bordered panels (steps, images, code, notes).
• Unified query parameter override: ?tabs=bash or ?tabs=powershell.
• Persistence: last chosen variant remembered across pages.

Configuration

Front Matter Tab Defaults

You can set default tabs for an entire page using front matter:

---
title: "Your Page Title"
tabs:
  - powershell  # First preference
  - bash        # Fallback if PowerShell tab not found
  - portal      # Second fallback
---

Force Tabs (for Shared Content)

Use force_tabs: true to override user preferences:

---
title: "Shared Content Page"
tabs:
  - powershell
force_tabs: true  # Always defaults to PowerShell, ignoring user preferences
---

Priority System

1. URL parameters (e.g., ?tabs=bash) - always highest priority
2. force_tabs: true - page defaults override user preferences
3. User preferences - stored choices from previous interactions
4. Front matter tabs array - page-level defaults
5. First tab - final fallback

Shortcodes

Query Parameter & Persistence

Append ?tabs=<name> (normalized to lowercase, alphanumeric only) to a page URL. All groups will attempt to activate the matching variant. Choices are stored in localStorage (global and per-group) so a user’s preference carries over.

When a user manually clicks a tab or mode, the current page URL is updated (via history.replaceState) to set ?tabs=<normalized-key> without causing a reload. This lets you copy/share a link that preserves the active variant.

Examples:

• ?tabs=bash
• ?tabs=powershell
• ?tabs=powershell,bash (comma list; first match per group wins)

Normalization

Display title → key transformation: lowercase + strip non-alphanumeric.

tabs shortcode (tabs/tab)

Raw tabs

Raw example so the shortcode is shown literally:

{{< tabs >}}
{{< tab title="Bash" >}}
```bash
az group create --name rg1 --location westeurope
```
{{< /tab >}}
{{< tab title="PowerShell" >}}
```powershell
New-AzResourceGroup -Name rg1 -Location westeurope
```
{{< /tab >}}
{{< /tabs >}}

Rendered tabs

1. Authenticate

   az login
   

   Connect-AzAccount
   

2. Show current context

   az account show --output jsonc
   

   Get-AzContext | Format-List
   

modes/mode shortcodes

Raw modes example

{{< modes >}}
  {{< mode title="Portal" >}}

  1. Open the Azure Portal.
  1. Create a resource group.

  {{< /mode >}}
  {{< mode title="Bash" >}}

  1. Authenticate

      ```shell
      az login
      ```

  1. Create a resource group

      ```shell
      az group create --name rg1 --location westeurope
      ```

  {{< /mode >}}
  {{< mode title="PowerShell" >}}

  1. Authenticate

      ```shell
      Connect-AzAccount
      ```

  1. Create a resource group

      ```shell
      New-AzResourceGroup -Name rg1 -Location westeurope
      ```

  {{< /mode >}}
{{< /modes >}}

Rendered modes example

Nested Shortcodes

Both tabs/tab and modes/mode now support nested shortcodes! You can include flash, img, details, button, and other shortcodes within tab or mode panels.

Example: Modes with Nested Flash and Image

{{< modes default="Portal" >}}
  {{< mode title="Portal" >}}

  {{< flash >}}
  **Important:** Ensure you have the correct permissions before proceeding.
  {{< /flash >}}

  1. Open the Azure Portal
  1. Navigate to Resource Groups

  {{< img light="/images/portal-light.png" dark="/images/portal-dark.png" alt="Azure Portal Resource Groups" >}}

  {{< /mode >}}

  {{< mode title="CLI" >}}

  {{< flash >}}
  **Note:** Make sure Azure CLI is installed and authenticated.
  {{< /flash >}}

  ```bash
  az group create --name mygroup --location westeurope
  ```

  {{< /mode >}}
{{< /modes >}}

Example: Tabs with Nested Details

{{< tabs default="Bash" >}}
  {{< tab title="Bash" >}}

  ```bash
  curl -X GET "https://api.example.com/data"
  ```

  {{< details "Advanced Options" >}}
  You can add additional headers:
  ```bash
  curl -H "Authorization: Bearer token" -X GET "https://api.example.com/data"
  ```
  {{< /details >}}

  {{< /tab >}}

  {{< tab title="PowerShell" >}}

  ```powershell
  Invoke-RestMethod -Uri "https://api.example.com/data"
  ```

  {{< details "Advanced Options" >}}
  You can add authentication:
  ```powershell
  $headers = @{ Authorization = "Bearer token" }
  Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers
  ```
  {{< /details >}}

  {{< /tab >}}
{{< /tabs >}}

Working Example:

curl -X GET "https://api.example.com/data"

curl -H "Authorization: Bearer token" -X GET "https://api.example.com/data"

Invoke-RestMethod -Uri "https://api.example.com/data"

$headers = @{ Authorization = "Bearer token" }
Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers

Comprehensive Nesting Example

Here’s an example showcasing all shortcodes that support nesting within modes:

./install.sh --auto

./install.sh --debug --verbose

# Step 1: Download
wget https://example.com/installer.tar.gz

# Step 2: Extract
tar -xzf installer.tar.gz

# Step 3: Install
cd installer && make install

environment: production
debug: false
log_level: warn

environment: development
debug: true
log_level: debug

class CustomExtension(BaseExtension):
    def initialize(self):
        pass

    def process(self, data):
        return processed_data

class CustomExtension extends BaseExtension {
    initialize() {
        // Setup code
    }

    process(data) {
        return processedData;
    }
}

-- Good: Uses index
SELECT * FROM users WHERE user_id = ?

-- Bad: Full table scan
SELECT * FROM users WHERE UPPER(username) = ?

Author Tips

• Use a single consistent title form (e.g. “Bash” not “Bash Shell”).
• Prefer fewer than 4 variants per group to avoid horizontal crowding.
• Use default="..." on the container to specify a preferred initial variant.
• For large mode panels, keep early lines concise; readers can switch quickly.

Accessibility & Keyboard

• role="tablist", role="tab", role="tabpanel" applied at runtime.
• Keys: Left / Right move; Home / End jump.
• Panels hidden via display: none; all content present in HTML for screen readers with scripting disabled.

Print & No-JS

Currently only active panel prints. Future enhancement may expand all on @media print. If JavaScript is disabled the raw HTML shows all panels stacked.

Roadmap

• Copy button per active panel
• Analytics event on variant change
• Optional print expansion
• Smoother visual parity with Microsoft Learn