Markdown Examples

This page demonstrates various markdown formatting and documentation patterns you can use in your OkiDoki documentation.

Headers

# H1 - Main Title
## H2 - Section Title  
### H3 - Subsection
#### H4 - Sub-subsection
##### H5 - Minor Heading
###### H6 - Smallest Heading

Result:

H1 - Main Title

H2 - Section Title

H3 - Subsection

H4 - Sub-subsection

H5 - Minor Heading

H6 - Smallest Heading

Text Formatting

**Bold text** or __bold text__
*Italic text* or _italic text_
***Bold and italic*** or ___bold and italic___
~~Strikethrough text~~
`Inline code`

Result:Bold text, italic text, bold and italic, ~~strikethrough text~~, inline code

Lists

Unordered Lists

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Result:

First item
Second item
- Nested item
- Another nested item
Third item

Ordered Lists

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

Result:

First step
Second step
1. Nested step
2. Another nested step
Third step

Links and Images

[Link text](https://example.com)

[Internal link](reference.md)

[Link with title](https://example.com "Example Website")

![Alt text](okidokilogo.svg)

Result:

Link text

Internal link

Link with title

Code Blocks

JavaScript Example

```javascript
function calculateTotal(items) {
  return items.reduce((sum, item) => {
    return sum + (item.price * item.quantity);
  }, 0);
}

// Usage
const cartItems = [
  { name: "Book", price: 12.99, quantity: 2 },
  { name: "Pen", price: 1.50, quantity: 5 }
];

console.log(`Total: ${calculateTotal(cartItems)}`);
```

Result:

function calculateTotal(items) {
  return items.reduce((sum, item) => {
    return sum + (item.price * item.quantity);
  }, 0);
}

// Usage
const cartItems = [
  { name: "Book", price: 12.99, quantity: 2 },
  { name: "Pen", price: 1.50, quantity: 5 }
];

console.log(`Total: $${calculateTotal(cartItems)}`);

Python Example

```python
def fibonacci(n):
    """Generate Fibonacci sequence up to n terms."""
    if n <= 0:
        return []
    elif n == 1:
        return [0]
    elif n == 2:
        return [0, 1]
    
    fib_seq = [0, 1]
    for i in range(2, n):
        fib_seq.append(fib_seq[i-1] + fib_seq[i-2])
    
    return fib_seq

# Generate first 10 Fibonacci numbers
print(fibonacci(10))
```

YAML Configuration

```yaml
site:
  title: "My API Documentation"
  description: "Complete API reference and guides"
  theme:
    light: "fantasy"
    dark: "forest"
  
globals:
  version: "2.1.0"
  api_base: "https://api.example.com/v1"
  
search:
  enabled: true
  placeholder: "Search API docs..."
```

Shell Commands

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production  
npm run build

# Run tests
npm test
```

Tables

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET    | `/users` | List all users | Yes |
| POST   | `/users` | Create new user | Yes |
| GET    | `/users/{id}` | Get user by ID | Yes |
| PUT    | `/users/{id}` | Update user | Yes |
| DELETE | `/users/{id}` | Delete user | Yes |

Result:

Method	Endpoint	Description	Auth Required
GET	`/users`	List all users	Yes
POST	`/users`	Create new user	Yes
GET	`/users/{id}`	Get user by ID	Yes
PUT	`/users/{id}`	Update user	Yes
DELETE	`/users/{id}`	Delete user	Yes

Blockquotes

> This is a blockquote. It can be used for highlighting important information,
> quotes, or notes.

> **Tip:** You can also use blockquotes for tips and warnings.

Result:

This is a blockquote. It can be used for highlighting important information, quotes, or notes.

Tip: You can also use blockquotes for tips and warnings.

Horizontal Rules

---

***

___

Result:

Global Variables

Use variables defined in your okidoki.yaml:

# Okidoki Configuration
site:
  title: "My Docs"
  description: "Docs generated with Okidoki"
  theme:
    light: "fantasy"
    dark: "forest"

version: "1.0.1"
api_url: "https://api.example.com"
support_email: "support@example.com"
author: "**John Doe**"
author_url: "https://example.com"
author_image: "https://example.com/avatar.png"
author_bio: "John Doe is a good man"
author_twitter: "https://twitter.com/johndoe"
author_linkedin: "https://linkedin.com/in/johndoe"

Reference them in your markdown file:

Current version: {{version}}

API endpoint: {{{api_url}}}

Support email: {{{support_email}}}

Use triple curly brackets to encode stuff {{{encoded_content}}}.

Result

Current version: 1.0.40

API endpoint:

Support email:

Important Messages & Callouts

Create important message callouts using Handlebars alert helpers:

Simple Alert Syntax

For basic alerts with text only:

{{alert "This is an informational callout." "info"}}
{{alert "This is a success message." "success"}}
{{alert "This is a warning message." "warning"}}
{{alert "This is an error alert." "error"}}
{{alert "This is neutral information."}}

Result:

This is an informational callout.

This is a success message.

This is a warning message.

This is an error alert.

This is neutral information.

Block Alert Syntax

For alerts with complex content including markdown:

{{#alert type="info"}}
Information alert with **markdown** support and [links](https://example.com)
{{/alert}}

{{#alert type="warning"}}
Warning alert with `code` and multiple lines of content
{{/alert}}

Result:

Information alert with markdown support and links

Warning alert with code and multiple lines of content

Available Alert Types

info - Blue, for general information
success - Green, for positive messages
warning - Orange/yellow, for important warnings
error - Red, for critical alerts
blank - Gray, for neutral information (default)

Complex Example with Code

{{#alert type="error"}}
❌ **Error**: Critical code detected!
```javascript
console.log('Be careful with this');
process.exit(1);
```

Please check your [code file](index.js) and ensure that your code is sanitized.
{{/alert}}

Result:

❌ Error: Critical code detected!

console.log('Be careful with this');
process.exit(1);

Please check your code file and ensure that your code is sanitized.

Badges

Here are some examples of the new badge functionality:

Basic Badges

{{badge "Default Badge"}}

Result:Default Badge

Colored Badges

{{badge "Primary" "primary"}}
{{badge "Secondary" "secondary"}}
{{badge "Accent" "accent"}}
{{badge "Info" "info"}}
{{badge "Success" "success"}}
{{badge "Warning" "warning"}}
{{badge "Error" "error"}}

Result:PrimarySecondaryAccentInfoSuccessWarningError

Badges in Text

You can use badges inline like this {{badge "Status: Active" "success"}} within your text content.

Result: You can use badges inline like this Status: Active within your text content.

Practical Examples

API Documentation

## Get User {{badge "GET" "primary"}}
## Create User {{badge "POST" "success"}}
## Update User {{badge "PUT" "warning"}}
## Delete User {{badge "DELETE" "error"}}

Result:

Get User GET

Create User POST

Update User PUT

Delete User DELETE

Version and Status Indicators

# My Project {{badge "v2.1.0" "info"}} {{badge "Stable" "success"}}

Features:
- Authentication {{badge "✅ Complete" "success"}}
- Dashboard {{badge "🚧 In Progress" "warning"}}
- Analytics {{badge "📋 Planned" "outline"}}
- Mobile App {{badge "❌ Deprecated" "error"}}

Result:

My Project v2.1.0Stable

Features:

Authentication ✅ Complete
Dashboard 🚧 In Progress
Analytics 📋 Planned
Mobile App ❌ Deprecated

HTML in Markdown

You can also use HTML for more complex formatting:

<div>
  <h4>Custom HTML Block</h4>
  <p>Sometimes you need more control over the formatting.</p>
  <ul>
    <li><strong>Bold item</strong></li>
    <li><em>Italic item</em></li>
  </ul>
</div>

Result:

Custom HTML Block

Sometimes you need more control over the formatting.

Bold item
Italic item

Tabs Demo

This page demonstrates both the old Handlebars tabs syntax and the new markdown tabs syntax.

Tabs Syntax

Create interactive tabbed content using Handlebars helpers:

{{#tabs}}
{{#tab title="JavaScript"}}
```javascript
const message = "Hello from JavaScript!";
console.log(message);
// more code here
```
{{/tab}}
{{#tab title="Python"}}
```python
def main():
# more code here
```
{{/tab}}
{{/tabs}}

Result:

const message = "Hello from JavaScript!";
console.log(message);

// Fetch data from API
fetch('/api/users')
  .then(response => response.json())
  .then(data => console.log(data));

def main():
    message = "Hello from Python!"
    print(message)

    # Fetch data from API
    import requests
    try:
        response = requests.get('/api/users')
        data = response.json()
        print(data)
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

# Get users from API
curl -X GET \
  'https://api.example.com/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-token'

Another Example with Mixed Content

Here’s some regular markdown content in a tab.

Feature A: Does something cool
Feature B: Does something else
Feature C: Does something amazing

Note: This tab contains mixed content - not just code!

interface User {
  id: number;
  name: string;
  email: string;
}

class UserService {
  async getUser(id: number): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  }
}

# config.yml
api:
  baseUrl: "https://api.example.com"
  timeout: 30000
  retries: 3

features:
  enableCache: true
  enableLogging: true
  enableMetrics: false

Best Practices

Use descriptive headers - Make it easy to scan and navigate
Include code examples - Show, don’t just tell
Add context - Explain when and why to use something
Keep it updated - Outdated documentation is worse than no documentation
Link related content - Help users discover relevant information

This comprehensive example should give you a solid foundation for creating rich, well-formatted documentation with OkiDoki!