> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/block-showcase.md).

# Block showcase

This article exercises every content type and custom block available in GitBook so we can confirm each one renders correctly after a git-to-GitBook sync.

***

## Text and basic formatting

### Headings

All six heading levels render with distinct sizing. Most articles only use H1 (title), H2 (major sections), and H3 (sub-sections). H4-H6 are mainly used inside custom blocks (per GitBook's normalisation rules).

## H2 heading

### H3 heading

#### H4 heading

**H5 heading**

**H6 heading**

### Inline text styles

**Bold text** and *italic text* and `inline code` and ~~strikethrough~~.

Combined: ***bold italic***, **`bold inline code`**, and *`italic inline code`*.

### Links

* External link: [Smaply website](https://smaply.com)
* Internal link to another file: [Homepage](/readme.md)
* Internal link with anchor: [Jump to Mermaid section](#mermaid-diagrams)
* Email link: [Contact support](mailto:help@smaply.com)

***

## Structural elements

### Horizontal divider

A horizontal rule separates sections visually without adding a heading. Syntax: three hyphens on a line of their own.

Above the divider.

***

Below the divider.

### Blockquote

> A blockquote for quoting text or calling out something memorable.
>
> Blockquotes can span multiple paragraphs and support *inline formatting*.

### Task lists

Markdown checkboxes render as visual task lists.

* [ ] Unchecked task
* [x] Completed task
* [ ] Another unchecked task
  * [x] Nested completed task
  * [ ] Nested unchecked task

### Code blocks

Syntax highlighting follows the language tag on the fence.

```javascript
// JavaScript
const greeting = "Hello GitBook";
console.log(greeting);
```

```python
# Python
def greet(name):
    return f"Hello, {name}"
```

```yaml
# YAML
config:
  timeout: 30
  retries: 3
```

### Tables

| Column A | Column B | Column C |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

### Lists

Unordered:

* First item
* Second item
  * Nested item
    * Double-nested item

Ordered:

1. First step
2. Second step
3. Third step
   1. Nested numbered
   2. Second nested

***

## Callouts (hint blocks)

### Basic styles

Four styles, each mapped to the callout vocabulary.

{% hint style="info" %}
**Prerequisites style.** Used for requirements the reader needs before starting a task.
{% endhint %}

{% hint style="success" %}
**Tip style.** Used for optional enhancements, shortcuts, or best-practice nudges.
{% endhint %}

{% hint style="warning" %}
**Important style.** Used for non-obvious constraints the reader will trip on if missed.
{% endhint %}

{% hint style="danger" %}
**Warning style.** Used for destructive or irreversible actions.
{% endhint %}

### Rich internal formatting

Hints accept most markdown inside them.

{% hint style="info" %}
**With a heading**

You need Admin permissions on the workspace.

This article assumes you have already connected at least one integration. If you have not, see the integrations overview first.
{% endhint %}

{% hint style="warning" %}
**With a list**

Switching between OAuth and service account will:

* Disconnect the current connection
* Invalidate any active tokens
* Require re-authorisation on the next sync

Save any pending configuration changes before proceeding.
{% endhint %}

{% hint style="success" %}
**With a code block:** use keyboard shortcuts to speed up common actions.

```
⌘ + K    Open quick search
⌘ + /    Show all shortcuts
⌘ + .    Toggle comments panel
```

{% endhint %}

{% hint style="danger" %}
**Multi-paragraph.** Deleting a persona is permanent. There is no undo and no archive for personas.

If you think you might need the persona later, archive related journey maps instead. Archived journeys can be restored with their persona assignments intact.

For bulk operations, export the workspace before deleting anything.
{% endhint %}

{% hint style="info" icon="books" %}
**Custom icon.** This hint uses a `books` icon instead of the default info icon.
{% endhint %}

{% hint style="info" icon="bars" %}

#### Possible causes:

* [**Missing invitation** - They don't see the map in their sidebar at all](#missing-invitation-they-dont-see-the-map-in-their-sidebar-at-all)
* [**Permissions issue** - The map is visible but they can't edit it](#the-map-is-visible-but-they-cant-edit-it)
* [**Archived, moved or deleted** - The map used to be visible but has disappeared](#the-map-used-to-be-visible-but-has-disappeared)
* [**Wrong Account / Workspace** - They see different content or a different workspace](#wrong-account-workspace-they-see-different-content-or-a-different-workspace)
  {% endhint %}

***

## Sequential and comparison blocks

### Stepper

Sequential steps with visual progression. Steps accept nested formatting.

{% stepper %}
{% step %}
**Open Workspace Settings**

Click **Settings** in the workspace sidebar.

{% hint style="info" %}
The Settings option only appears if you are a Workspace Admin.
{% endhint %}
{% endstep %}

{% step %}
**Go to Manage users**

Select the **Manage users** tab.

You'll see three sections: active users, pending invitations, and viewers.
{% endstep %}

{% step %}
**Send the invite**

Enter an email, pick a role from the dropdown, and click **Invite**.

Available roles:

* **Admin**: full access to the workspace
* **Editor**: can create and edit content
* **Viewer**: read-only with commenting

The invite expires after 7 days.
{% endstep %}
{% endstepper %}

### Tabs

Used for genuine alternatives.

{% tabs %}
{% tab title="OAuth" %}
Sign in with your Google account. Access is tied to the individual user who authenticates.

**Best for:**

* Quick personal connections
* Single-user integrations
* Early testing
  {% endtab %}

{% tab title="Service account" %}
Upload a JSON service account file. Access is tied to the service, not a user.

**Best for:**

* Team-wide integrations
* Production setups
* Environments where user turnover should not break integrations
  {% endtab %}

{% tab title="API token" %}
For services that use token-based auth (like Qualtrics).

1. Generate a token in the third-party service
2. Copy it (tokens are usually shown once)
3. Paste into Smaply's configuration field
   {% endtab %}
   {% endtabs %}

### Columns

Side-by-side comparison. Maximum two columns.

{% columns %}
{% column %}
**Viewer role**

Can view journey maps and add comments. Cannot edit content, change structure, or manage users.

Best for:

* Stakeholders reviewing work
* Executives who want visibility
* Read-only cross-team access
  {% endcolumn %}

{% column %}
**Editor role**

Can view and edit content: create journey maps, add cards, manage personas, update portfolio items.

Best for:

* Core team members
* Researchers and designers
* Product managers
  {% endcolumn %}
  {% endcolumns %}

### Expandable

Optional deep-dives, collapsed by default.

<details>

<summary><strong>Advanced configuration options</strong></summary>

Content hidden by default. Readers expand if they need the detail.

**Configuration file:**

```yaml
advanced:
  refresh_interval: 3600
  max_retries: 3
  timeout: 30
```

**Options explained:**

* `refresh_interval`: how often the integration polls, in seconds
* `max_retries`: attempts before marking the connection as failed
* `timeout`: request timeout per call

</details>

***

## Navigation and reference blocks

### Cards

Visual navigation for Related topics and category landing pages.

<table data-view="cards" data-full-width="false"><thead><tr><th>Related topic</th><th>Short description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Test homepage</td><td>Back to the test space landing page</td><td><a href="/pages/kzTlst3tKo255yz4YpDi">/pages/kzTlst3tKo255yz4YpDi</a></td></tr><tr><td>Hint blocks</td><td>Jump to the hint blocks section of this article</td><td><a href="#hint-blocks-basic-styles">#hint-blocks-basic-styles</a></td></tr><tr><td>Stepper examples</td><td>See the stepper block with nested hints and lists</td><td><a href="#stepper-with-nested-blocks">#stepper-with-nested-blocks</a></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

### Updates (changelog style)

Dated entries in reverse chronological order. Good for release notes.

{% updates %}
{% update date="2026-04-23" %}

## Block showcase expanded

Added task lists, Mermaid diagrams, embeds, and explicit heading level examples.
{% endupdate %}

{% update date="2026-04-22" %}

## Sync testing

Set up the GitBook Git Sync test environment. Confirmed bi-directional sync and all custom blocks render correctly.
{% endupdate %}

{% update date="2026-04-15" %}

## Helpdesk workflow overhaul

Replaced the Haiku retrieval + Opus writer pipeline with a registry-driven multi-agent workflow.
{% endupdate %}
{% endupdates %}

***

## Rich media

### Images

Committed image (SVG in `.gitbook/assets/`):

![Committed SVG](/files/AniRzwaIUntJWkfIHni5)

External image by URL:

![External placeholder](https://placehold.co/600x300/e0e0e0/333333?text=External+Image+via+URL)

### File downloads

Inline downloadable file with caption. File blocks need a resolvable URL or GitBook silently drops them.

### Buttons

Primary and secondary styles, with optional icons.

<a href="https://smaply.com" class="button primary">Open Smaply</a>

<a href="https://smaply.com/docs" class="button secondary">Read the docs</a>

<a href="https://github.com/joe-smaply/test-gitbook" class="button primary" data-icon="github">View on GitHub</a>

### Embeds

External content (videos, interactive demos, social media).

YouTube:

{% embed url="<https://www.youtube.com/watch?v=39-WxZLf004>" %}

Loom (placeholder URL):

{% embed url="<https://www.loom.com/share/test-placeholder>" %}

***

## Diagrams

### Mermaid diagrams

Fenced code block with `mermaid` language tag. GitBook renders it as an interactive diagram.

**Flowchart:**

```mermaid
graph TD
    A[User opens journey map] --> B{Is map shared?}
    B -->|Yes| C[Viewer sees content]
    B -->|No| D[Access denied]
    C --> E{Has edit role?}
    E -->|Yes| F[Can edit content]
    E -->|No| G[Read-only view]
```

**Sequence diagram:**

```mermaid
sequenceDiagram
    participant User
    participant Smaply
    participant GoogleSheets
    User->>Smaply: Open journey map
    Smaply->>GoogleSheets: Request metric data
    GoogleSheets-->>Smaply: Return data
    Smaply->>User: Render metric card
```

***

## Dynamic content

### Variables and expressions

Variables defined in `.gitbook/vars.yaml` referenced dynamically via expressions.

**Current support email:** <code class="expression">space.vars.supportEmail</code>

**Current plan name:** <code class="expression">space.vars.currentPlan</code>

**Current year:** <code class="expression">space.vars.currentYear</code>

**Max workspaces on Ultimate plan:** <code class="expression">space.vars.maxWorkspacesUltimate</code>

**String concatenation:** <code class="expression">"Contact support at " + space.vars.supportEmail</code>

**Conditional:** <code class="expression">space.vars.currentPlan === "Ultimate" ? "You are on the top tier" : "Consider upgrading"</code>

### Inline icons

Icons in running text: the <i class="fa-check">:check:</i> icon indicates success, the <i class="fa-triangle-exclamation">:triangle-exclamation:</i> icon flags caution, and the <i class="fa-circle-info">:circle-info:</i> icon points at supplementary info.

Use sparingly. Icons work best as visual anchors in comparison tables or status indicators, not decoration in every paragraph.

***

## Card icon options (prototype)

Three ways to add a visual to overview-page cards, shown with the Journey Maps *Create and structure* grid so the options compare like-for-like. This is a prototype for choosing which treatment to roll out on category landing pages.

### Option A: icon in the title

Font Awesome glyph prepended to each card title. No image assets. Reuses the inline-icon convention already used in comparison tables.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-map">:map:</i> Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr><tr><td><h4><i class="fa-table-columns">:table-columns:</i> Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td></tr><tr><td><h4><i class="fa-clone">:clone:</i> Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td></tr></tbody></table>

### Option B: cover tile (soft tint)

Branded SVG cover in `.gitbook/assets/`. Soft warm-tint background with the brand-red glyph.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td><td><a href="/files/0dziZq262d7FbbLgykfq">/files/0dziZq262d7FbbLgykfq</a></td></tr><tr><td><h4>Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td><td><a href="/files/lzhRTbwhkI9ERJO9CO6b">/files/lzhRTbwhkI9ERJO9CO6b</a></td></tr><tr><td><h4>Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td><td><a href="/files/oWFRfSjbUPDGKBJZEBgb">/files/oWFRfSjbUPDGKBJZEBgb</a></td></tr></tbody></table>

### Option B: cover tile (solid red)

Same cover mechanism, saturated brand-red background with a white glyph.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td><td><a href="/files/CAWq4Y1kID7qWl2qWBEg">/files/CAWq4Y1kID7qWl2qWBEg</a></td></tr><tr><td><h4>Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td><td><a href="/files/ERQj8t08Un4AXVnJ9eH7">/files/ERQj8t08Un4AXVnJ9eH7</a></td></tr><tr><td><h4>Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td><td><a href="/files/Rykxx9T96pqRQQqwaNAM">/files/Rykxx9T96pqRQQqwaNAM</a></td></tr></tbody></table>

***

## Spacer test

Each method sits between a **TOP** and **BOTTOM** marker. The gap between the two markers shows how much vertical space the method renders; reading the file back after sync shows what GitBook kept.

### A. Three blank lines

TOP A

BOTTOM A

### B. Empty centered paragraph (x2)

TOP B

BOTTOM B

### C. Non-breaking space paragraph (x2)

TOP C

&#x20;

&#x20;

BOTTOM C

### D. Space-entity paragraph (x2)

TOP D

BOTTOM D

### E. Break tags

TOP E

\
\ <br>

BOTTOM E

***

## Summary

If you're reading this and everything above renders correctly, GitBook sync is working end-to-end with the full feature set we'd use in the real helpdesk.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/block-showcase.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.