# Tool Name: `template-list-snippets`

**Module**: Channels > Templates  
**Version**: 1.0.0  
**Status**: Stable

## Overview

Lists all snippets in a site. **Snippets are reusable code blocks** that can be included in pages and other templates using Liquid tags like `{% snippet 'header' %}`. They are fundamental to Modyo's code sharing and component-based architecture.

## Use Cases

- Discover available snippets before adding them to pages
- Audit which snippets exist in a site
- Verify snippet creation was successful
- Plan template refactoring by identifying reusable components
- Document available snippets for team reference

## Parameters

### Required Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
| siteId | number | The ID of the site to list snippets from | 123 |

### Optional Parameters

None. This tool returns all snippets in the specified site.

## Response

### Success Response

```json
{
  "snippets": [
    {
      "id": 456,
      "uuid": "snippet-uuid-123",
      "name": "site-header",
      "body": "<header><nav>...</nav></header>",
      "published": true,
      "created_at": "2025-01-08T10:00:00Z",
      "updated_at": "2025-01-09T15:30:00Z"
    },
    {
      "id": 457,
      "uuid": "snippet-uuid-456",
      "name": "site-footer",
      "body": "<footer>&copy; 2025</footer>",
      "published": true,
      "created_at": "2025-01-08T10:05:00Z",
      "updated_at": "2025-01-08T10:05:00Z"
    },
    {
      "id": 458,
      "uuid": "snippet-uuid-789",
      "name": "product-card",
      "body": "<div class=\"product\">{{ product.name }}</div>",
      "published": false,
      "created_at": "2025-01-09T14:00:00Z",
      "updated_at": "2025-01-09T14:00:00Z"
    }
  ]
}
```

### Error Responses

**404 Not Found - Invalid Site**
```json
{
  "error": "Site not found",
  "site_id": 999
}
```

**Empty Response**
```json
{
  "snippets": []
}
```

## Examples

### Example 1: List All Snippets

Get all snippets in a site to see what's available:

```json
{
  "platformSlug": "production",
  "siteId": 123
}
```

**Result**: Returns array of all snippet objects with names, bodies, and metadata.

### Example 2: Verify Snippet After Creation

Check that a newly created snippet appears in the list:

```json
{
  "platformSlug": "production",
  "siteId": 123
}
```

Filter response to find your snippet by name.

### Example 3: Audit Site Templates

List snippets to document what templates exist:

```json
{
  "platformSlug": "production",
  "siteId": 123
}
```

Use for creating template inventory or migration planning.

## Related Tools

- `template-list-custom-snippets` - List user-defined custom snippets
- `template-create` - Create new snippets (type: "snippet")
- `template-get` - Get full details of a specific snippet
- `template-update` - Modify snippet metadata
- `template-save` - Update snippet body content
- `template-delete` - Remove snippets
- `page-update` - Use snippets in page content

## Common Patterns

### Pattern 1: Snippet Discovery and Usage

```
1. template-list-snippets → see available snippets
2. template-get (id: X) → view snippet code
3. page-update → add snippet to page using {% snippet 'name' %}
4. page-get → verify snippet rendering
```

### Pattern 2: Template Audit and Documentation

```
1. template-list-snippets → get all snippets
2. template-list-custom-snippets → get custom snippets
3. template-list-layouts → get layouts
4. [For each snippet]: template-get → get full details
5. Document available templates for team
```

### Pattern 3: Snippet Migration Between Sites

```
1. template-list-snippets (source site) → get all snippets
2. [For each snippet]: template-get (source) → get body
3. [For each snippet]: template-create (target site) → recreate
4. template-list-snippets (target) → verify migration
```

### Pattern 4: Identifying Unused Snippets

```
1. template-list-snippets → get all snippets
2. page-list → get all pages
3. [For each page]: page-get → check content for snippet references
4. Compare to find unused snippets
5. template-delete (unused) → cleanup
```

## Understanding Snippets

### What Are Snippets?

Snippets are **reusable HTML/Liquid code blocks** that solve the DRY (Don't Repeat Yourself) principle:

- **Before Snippets**: Copy header HTML to every page (unmaintainable)
- **With Snippets**: `{% snippet 'header' %}` on every page (update once, reflects everywhere)

### Snippet vs Custom Snippet

- **Snippets**: System-level templates, managed by administrators
- **Custom Snippets**: User-created templates, often site-specific

Both work the same way in pages, just different organizational categories.

### How to Use Snippets in Pages

In page content (accessed via `page-update`):

```liquid
<!DOCTYPE html>
<html>
<head>
  {% snippet 'head-meta' %}
</head>
<body>
  {% snippet 'site-header' %}
  
  <main>
    {{ content_for_layout }}
  </main>
  
  {% snippet 'site-footer' %}
  {% snippet 'analytics' %}
</body>
</html>
```

When the page renders, `{% snippet 'site-header' %}` is replaced with the snippet body.

### Common Snippet Types

| Snippet Name | Purpose | Typical Body |
|--------------|---------|--------------|
| site-header | Site navigation | `<header><nav>...</nav></header>` |
| site-footer | Footer content | `<footer>&copy; year</footer>` |
| head-meta | SEO meta tags | `<meta name="..." content="...">` |
| product-card | Reusable component | `<div class="card">{{ product }}</div>` |
| analytics | Tracking scripts | `<script>ga('...')</script>` |
| breadcrumbs | Navigation path | `<nav>{% for item in path %}</nav>` |

## Troubleshooting

### Issue: Empty snippets array

**Cause**: No snippets have been created in this site yet  
**Solution**:
- Use `template-create` with type: "snippet" to create snippets
- Check if you're looking at the correct siteId
- Verify site exists using `site-get`

### Issue: Missing expected snippet

**Cause**: Snippet may be a custom_snippet instead  
**Solution**:
- Use `template-list-custom-snippets` to check custom snippets
- Use `template-list` with type filter to see all template types
- Check if snippet was deleted

### Issue: Snippet body truncated

**Cause**: List endpoint returns metadata only, not full body  
**Solution**:
- Use `template-get` with specific snippet ID to get complete body
- List operation intentionally limits body size for performance

### Issue: Published vs Unpublished snippets

**Cause**: Snippets can be in draft (unpublished) state  
**Solution**:
- Check "published": true/false in response
- Unpublished snippets work in draft pages but not in published pages
- Publish snippets through Modyo admin or use template-update

## Best Practices

1. **Standardize naming** - Use consistent patterns (e.g., `site-*`, `component-*`)
2. **Document snippets** - Add descriptions when creating snippets
3. **Keep snippets focused** - One snippet = one responsibility
4. **Version control** - Export snippet bodies to git for backup
5. **Test before use** - Create snippets in staging first
6. **Publish wisely** - Only publish when snippets are tested and ready
7. **Regular audits** - Periodically list snippets to identify unused ones

## Performance Considerations

- **Fast operation**: Listing snippets is a lightweight query
- **No pagination**: All snippets returned in single response
- **Large sites**: Sites with 100+ snippets return quickly
- **Caching**: Consider caching snippet list for frequently accessed sites

## Permissions Required

- Valid Admin API access token
- Channels module enabled
- Read access to site templates
- Site must exist and be accessible

## Rate Limits

- **Standard**: 100 requests per minute
- **Recommended**: Cache results for 5-10 minutes
- **Concurrent requests**: No special restrictions

## Important Notes

- Returns **metadata only** - use `template-get` for full snippet body
- Includes **both published and unpublished** snippets
- **Does not include custom_snippets** - use `template-list-custom-snippets` for those
- Snippets are **site-scoped** - cannot be shared across sites directly
- **Empty array** is valid response (means no snippets exist)
- Order is typically by **created_at** (oldest first)
- Snippet **IDs are unique** within platform, not just site

## See Also

### Documentation
- [Snippets and Code Reusability Guide](../../guides/snippets-guide.md)
- [Template Management Best Practices](../../guides/template-management.md)
- [Liquid Template Language](../../guides/liquid-guide.md)

### Official Modyo Documentation
- [Modyo Snippets Docs](https://docs.modyo.com/en/platform/channels/templates.html#snippets)
- [API Reference](https://api.modyo.com/swagger#/templates/get_sites__site_id__templates_snippets)
- [Liquid Template Guide](https://docs.modyo.com/en/platform/channels/liquid-markup.html)

### Related Tool Documentation
- [template-create](./template-create.md) - Create new snippets
- [template-list-custom-snippets](./template-list-custom-snippets.md) - List custom snippets
- [template-get](./template-get.md) - Get full snippet details
- [template-save](./template-save.md) - Update snippet code
- [page-update](../pages/page-update.md) - Use snippets in pages