Writing Instructions

Create engaging, interactive instructions for your lab scenarios.

Markdown Basics

Instructions support standard GitHub-flavored markdown:

Headings

# Heading 1
## Heading 2
### Heading 3

Text Formatting

**Bold text**
*Italic text*
`inline code`
~~strikethrough~~

Lists

- Unordered item
- Another item

1. Ordered item
2. Second item

Blockquotes

> This is a blockquote
> Great for tips and warnings

Links

[External link](https://example.com)

External links open in a new tab.

Code Blocks

Fenced code blocks are enhanced with:

• Language-specific styling
• Copy button on hover
• Language label

Terminal Commands (Dark Theme)

Languages bash, sh, shell, zsh, powershell use terminal styling:

```bash
# Create a Kafka topic
kafka-topics --create \
  --topic orders \
  --bootstrap-server localhost:9092 \
  --partitions 3
```

Code (Light Theme)

Other languages use code styling:

```sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100)
);
```

```python
def hello(name):
    return f"Hello, {name}!"
```

Supported Languages

All common languages are supported: sql, python, java, go, rust, javascript, typescript, yaml, json, xml, dockerfile, and more.

Inline Copyable Values

For configuration values, credentials, or any text users need to copy, use triple backticks around the value:

Enter ```my-database``` as the database name.

This renders as highlighted text with a copy button that appears on hover. Perfect for:

• Configuration values: Enter ```localhost:9092``` as the bootstrap server
• Credentials: Use ```admin``` as username and ```password123``` as password
• Connection strings: Set the endpoint to ```http://minio:9000```​

In Tables

Copyable values work great in configuration tables:

| Setting | Value |
|---------|-------|
| Endpoint | ```http://minio:9000``` |
| Access Key | ```admin``` |
| Secret Key | ```password123``` |

This creates a clean reference table where users can copy each value individually.

Tab Navigation Links

The killer feature: clickable links that switch participants to specific component tabs.

Basic Syntax

[link text](tab:componentLabel)

Example:

Open the [Kafka terminal](tab:kafka) to run commands.

This creates a blue button that switches to the Kafka component when clicked.

Navigating to Specific Tabs

When a component has multiple tabs (UI + Terminal), specify which one:

[link text](tab:componentLabel:tabIndex)

Tab indices are zero-based:

• 0 = First tab
• 1 = Second tab

Examples:

View data in the [MinIO console](tab:minio:0).
Run commands in the [MinIO terminal](tab:minio:1).

Default Behavior

If you omit the tab index, it opens the first tab:

[MinIO](tab:minio)  <!-- Opens tab 0 -->

Best Practices

Structure

1. Break into logical steps - One instruction per major task
2. Number your steps - Clear progression
3. Descriptive titles - Users should know what they'll learn

Writing Style

• Action-oriented - Start with verbs: "Create", "Configure", "Verify"
• Explain why - Don't just tell what, explain the purpose
• Expected outcomes - Tell users what success looks like

Code Blocks

• Add comments - Explain what commands do
• Realistic examples - Use meaningful data
• Keep it concise - Break long scripts into steps

Navigation Flow

Guide users through your scenario logically:

First, configure the source in [Kafka](tab:kafka),
then deploy the processor in [Flink](tab:platform:0),
and finally verify data arrives in [MinIO](tab:minio:0).

Troubleshooting Tips

Use blockquotes for common issues:

> **Tip:** If the connection fails, verify that the pod is in
> "Running" state before proceeding.

Complete Example

# Step 3: Create Your First Topic

In this step, you'll create a Kafka topic for order events.

## Open the Terminal

Click to open the [Kafka terminal](tab:kafka:1).

## Create the Topic

Run the following command to create an `orders` topic:

\`\`\`bash
kafka-topics --create \
  --topic orders \
  --bootstrap-server localhost:9092 \
  --partitions 3 \
  --replication-factor 1
\`\`\`

## Verify Creation

List all topics to confirm:

\`\`\`bash
kafka-topics --list --bootstrap-server localhost:9092
\`\`\`

You should see `orders` in the output.

> **Tip:** If you see a connection error, wait 30 seconds for
> Kafka to fully initialize and try again.

## Next Step

Now that your topic exists, proceed to [produce messages](tab:kafka:1)
in the next step.

Next Steps

• Best Practices - Tips and troubleshooting
• The Studio - Configure component tabs