Shortcodes

Shortcodes provide easy-to-use styled callouts that make important information stand out in your documentation.

Available Shortcodes

Note Shortcode

Use for general information and helpful hints.

Syntax:

<div class="note">Your message here</div>

Example:

When to use:

• General information
• Helpful hints
• Things to remember
• Additional context

Info Shortcode

Use for contextual information and details.

Syntax:

<div class="info">Your message here</div>

Example:

When to use:

• Technical requirements
• Version information
• Feature availability
• Contextual details

Tip Shortcode

Use for best practices and recommendations.

Syntax:

<div class="tip">Your message here</div>

Example:

When to use:

• Best practices
• Optimization suggestions
• Helpful recommendations
• Pro tips

Warning Shortcode

Use for important cautions and potential issues.

Syntax:

<div class="warning">Your message here</div>

Example:

When to use:

• Important cautions
• Potential data loss
• Security concerns
• Breaking changes
• Deprecation notices

Usage Examples

In Installation Guides

# Installation

## Prerequisites

<div class="info">You must have Node.js 18 or higher installed.</div>

## Steps

1. Clone the repository
2. Install dependencies

<div class="warning">Do not run npm install with sudo as it may cause permission issues.</div>

3. Configure environment

<div class="tip">Copy .env.example to .env and update the values for your environment.</div>

<div class="note">Database credentials can be found in your hosting provider&#039;s dashboard.</div>

Result:

In API Documentation

# Update User Endpoint

`PUT /api/users/{id}`

<div class="note">Authentication is required for this endpoint.</div>

## Parameters

| Name | Type | Required |
|------|------|----------|
| name | string | No |
| email | string | No |

<div class="warning">Changing a user&#039;s email will send a verification email to the new address.</div>

<div class="tip">Use PATCH instead of PUT if you only want to update specific fields.</div>

In Tutorials

# Building Your First Widget

## Step 1: Create Component

<div class="info">We&#039;ll use Laravel&#039;s Livewire for this tutorial.</div>

Create a new component:

```bash
php artisan livewire:make Widget

Step 2: Configure

In Configuration Guides

# Environment Configuration

## Required Variables

<div class="info">These variables must be set in your .env file.</div>

```env
APP_NAME="My Application"
APP_ENV=production
APP_KEY=

Optional Variables

In Security Documentation

# Security Best Practices

## Authentication

<div class="warning">Always use HTTPS in production. Never transmit credentials over HTTP.</div>

<div class="tip">Enable two-factor authentication for all administrator accounts.</div>

## Password Policies

<div class="info">Passwords must be at least 12 characters and include uppercase, lowercase, numbers, and symbols.</div>

<div class="note">Users will be prompted to update weak passwords on next login.</div>

## API Keys

<div class="warning">API keys grant full access to your account. Keep them secret and rotate regularly.</div>

<div class="tip">Use separate API keys for each integration to limit exposure.</div>

In Troubleshooting Guides

# Troubleshooting Common Issues

## Installation Fails

<div class="info">Check that your PHP version meets the minimum requirement of 8.2.</div>

**Solution:** Upgrade PHP or use Docker for a consistent environment.

<div class="tip">Run php -v to check your current PHP version.</div>

## Database Connection Errors

<div class="warning">Verify your database credentials in the .env file are correct.</div>

**Common causes:**
- Wrong hostname
- Incorrect port
- Database doesn't exist
- User lacks permissions

<div class="note">Database errors are logged to storage/logs/laravel.log</div>

## Cache Issues

<div class="tip">Clear all caches with: php artisan optimize:clear</div>

<div class="note">This is safe to run and won&#039;t delete any data.</div>

Styling and Colors

Shortcodes use colors defined in your .env:

Change colors in .env to match your brand:

DOCS_PRIMARY_COLOR="#0066cc"
DOCS_ACCENT_COLOR="#00aa00"
DOCS_WARNING_COLOR="#ff9900"
DOCS_INFO_COLOR="#0099ff"

Best Practices

1. Use Appropriate Shortcode Types

Good:

<div class="warning">This action is permanent and cannot be undone.</div>
<div class="tip">Use keyboard shortcuts to work faster.</div>
<div class="info">This feature is available in Pro plans.</div>
<div class="note">Settings are auto-saved.</div>

Avoid:

<div class="warning">Here&#039;s a helpful tip!</div>  <!-- Use tip instead -->
<div class="note">DANGER! This will delete everything!</div>  <!-- Use warning -->

2. Keep Messages Concise

Good:

<div class="warning">Changing this setting requires restarting the server.</div>

Avoid:

<div class="warning">Please be aware that if you decide to change this particular setting, you will need to make sure that you restart the server application in order for the changes to take effect, otherwise the system will continue to use the old configuration values.</div>

3. One Idea Per Shortcode

Good:

<div class="tip">Use caching to improve performance.</div>
<div class="note">Cache is automatically cleared when deploying.</div>

Avoid:

<div class="tip">Use caching to improve performance. Cache is automatically cleared when deploying. Remember to test performance before and after enabling cache.</div>

4. Place Strategically

Put shortcodes near related content:

Good:

## Delete Account

<div class="warning">This action is permanent and cannot be undone.</div>

To delete your account, click the Delete button...

Avoid:

## Delete Account

To delete your account, click the Delete button...

<div class="warning">This action is permanent and cannot be undone.</div>
<!-- Too far from the action -->

5. Don't Overuse

Good:

# API Authentication

Use Bearer tokens for all API requests.

<div class="info">Generate tokens in your account settings.</div>

Here's an example...

Avoid:

# API Authentication

<div class="note">This section covers authentication.</div>

<div class="info">Authentication is required for API access.</div>

Use Bearer tokens for all API requests.

<div class="tip">Bearer tokens are more secure than API keys.</div>

<div class="info">Generate tokens in your account settings.</div>

<div class="note">Tokens expire after 30 days.</div>
<!-- Too many callouts distract from content -->

Advanced Techniques

Combining with Markdown

Shortcodes support basic markdown:

<div class="tip">Check out our **[video tutorial](https://example.com/video)** for a visual guide.</div>

Sequential Callouts

Stack different types for complex information:

<div class="info">This feature is in beta and available to Pro users.</div>

<div class="warning">Beta features may have bugs or change without notice.</div>

<div class="tip">Enable beta features in Settings &gt; Advanced &gt; Beta Programs.</div>

In Tables

While not directly supported in table cells, use before/after:

<div class="warning">Review pricing carefully before choosing a plan.</div>

| Plan | Price | Users |
|------|-------|-------|
| Free | $0 | 5 |
| Pro | $29 | 25 |

Limitations

Not Supported:

• Shortcodes inside code blocks (they'll be escaped)
• Nested shortcodes: <div class="note"><div class="tip">text&lt;/div&gt;</div>
• Multi-line content (keep on one line)
• HTML inside shortcodes (use markdown instead)

Next Steps

• View more code examples
• Learn about tables
• Explore navigation