Block showcase

A deliberate test of GitBook's custom block types and internal formatting to confirm each renders correctly after sync

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

• Internal link to another file: Homepage

• Internal link with anchor: Jump to Mermaid section

• Email link: Contact support

---

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

• Completed task

• Another unchecked task

  • Nested completed task

  • Nested unchecked task

Code blocks

Syntax highlighting follows the language tag on the fence.

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

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

# 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.

Prerequisites style. Used for requirements the reader needs before starting a task.

Tip style. Used for optional enhancements, shortcuts, or best-practice nudges.

Important style. Used for non-obvious constraints the reader will trip on if missed.

Warning style. Used for destructive or irreversible actions.

Rich internal formatting

Hints accept most markdown inside them.

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.

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.

With a code block: use keyboard shortcuts to speed up common actions.

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

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.

Custom icon. This hint uses a books icon instead of the default info icon.

Possible causes:

• Missing invitation - They don't see the map in their sidebar at all

• Permissions issue - The map is visible but they can't edit it

• Archived, moved or deleted - The map used to be visible but has disappeared

• Wrong Account / Workspace - They see different content or a different workspace

---

Sequential and comparison blocks

Stepper

Sequential steps with visual progression. Steps accept nested formatting.

1

Open Workspace Settings

Click Settings in the workspace sidebar.

The Settings option only appears if you are a Workspace Admin.

2

Go to Manage users

Select the Manage users tab.

You'll see three sections: active users, pending invitations, and viewers.

3

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.

Tabs

Used for genuine alternatives.

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

Service account

API token

Columns

Side-by-side comparison. Maximum two columns.

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

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

Expandable

Optional deep-dives, collapsed by default.

Advanced configuration options

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

Configuration file:

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

---

Navigation and reference blocks

Cards

Visual navigation for Related topics and category landing pages.

Related topic

Test homepage

Short description

Back to the test space landing page

Target

Smaply Helpdesk

Related topic

Hint blocks

Short description

Jump to the hint blocks section of this article

Target

Block showcase

Related topic

Stepper examples

Short description

See the stepper block with nested hints and lists

Target

Block showcase

Related topic

Short description

Target

Updates (changelog style)

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

April 23, 2026

Block showcase expanded

Added task lists, Mermaid diagrams, embeds, and explicit heading level examples.

April 22, 2026

Sync testing

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

April 15, 2026

Helpdesk workflow overhaul

Replaced the Haiku retrieval + Opus writer pipeline with a registry-driven multi-agent workflow.

---

Rich media

Images

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

Committed SVG

External image by URL:

External placeholder

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.

Open Smaply

Read the docs

View on GitHub

Embeds

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

YouTube:

Loom (placeholder URL):

https://www.loom.com/share/test-placeholderwww.loom.com

---

Diagrams

Mermaid diagrams

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

Flowchart:

Sequence diagram:

---

Dynamic content

Variables and expressions

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

Current support email: [e-mail]

Current plan name: Ultimate

Current year: 2026

Max workspaces on Ultimate plan: 10

String concatenation: Contact support at [e-mail]

Conditional: You are on the top tier

Inline icons

Icons in running text: the icon indicates success, the icon flags caution, and the 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.

Create a journey map

Start a new map with Smaply AI, from scratch, or from a template.

Lanes and columns

Build the grid of rows and steps that make up the map.

Cards

The card types and what each one is for.

Option B: cover tile (soft tint)

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

Create a journey map

Start a new map with Smaply AI, from scratch, or from a template.

Lanes and columns

Build the grid of rows and steps that make up the map.

Cards

The card types and what each one is for.

Option B: cover tile (solid red)

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

Create a journey map

Start a new map with Smaply AI, from scratch, or from a template.

Lanes and columns

Build the grid of rows and steps that make up the map.

Cards

The card types and what each one is for.

---

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

BOTTOM C

D. Space-entity paragraph (x2)

TOP D

BOTTOM D

E. Break tags

TOP E

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.