2545 Extensions 7560b3bd

# Extensions

Quarto extensions add custom functionality including shortcodes, filters, formats, and RevealJS plugins.

## Extension Types

| Type             | Description                               |
| ---------------- | ----------------------------------------- |
| Shortcodes       | Custom `{{< shortcode >}}` commands       |
| Filters          | Pandoc filters for content transformation |
| Formats          | Custom output formats                     |
| RevealJS Plugins | Presentation enhancements                 |

## Finding Extensions

### Official Repository

- [Quarto Extensions](https://quarto.org/docs/extensions/)
- Browse by category: filters, shortcodes, formats, etc.

### Community Extensions

- [Community Extensions List](https://m.canouil.dev/quarto-extensions/)
- [Extensions JSON](https://m.canouil.dev/quarto-extensions/extensions.json)
- Search GitHub for `quarto-extension`

## Installing Extensions

### Basic Installation

```bash
quarto add username/repository
```

### From GitHub

```bash
quarto add quarto-ext/fontawesome
quarto add shafayetShafee/bsicons
```

### Specific Version

```bash
quarto add username/repository@v1.0.0
```

### From URL

```bash
quarto add https://github.com/user/repo/archive/main.zip
```

### Interactive Installation

When prompted, confirm trust in the extension source.

## Using Extensions

### In Document YAML

```yaml
---
filters:
  - extension-name
---
```

### Shortcode Extensions

After installing, use in document:

````markdown
{{< fa brands github >}} # Font Awesome icon
````

### Format Extensions

```yaml
format: custom-format
```

## Managing Extensions

### Location

Extensions are stored in `_extensions/` directory:

```txt
project/
├── _extensions/
│   └── fontawesome/
│       ├── _extension.yml
│       └── fontawesome.lua
├── document.qmd
└── _quarto.yml
```

### List Installed Extensions

```bash
ls _extensions/
```

### Update Extensions

```bash
quarto add username/repository  # Re-run to update
```

### Remove Extensions

Delete the folder from `_extensions/`:

```bash
rm -rf _extensions/extension-name
```

## Project vs Document Extensions

### Project-Wide

Install in project root. Available to all documents:

```txt
project/
├── _extensions/
├── chapter1.qmd
└── chapter2.qmd
```

### Global Extensions

Install in user config (less common):

```bash
quarto add --global username/repository
```

Location: `~/.local/share/quarto/extensions/`

## Popular Extensions

### Icons

```bash
quarto add quarto-ext/fontawesome
```

````markdown
{{< fa brands github >}} GitHub
{{< fa solid envelope >}} Email
````

### Lightbox

```bash
quarto add quarto-ext/lightbox
```

```yaml
lightbox: true
```

### Include Code from Files

```bash
quarto add quarto-ext/include-code-files
```

````markdown
{{< include-code example.py >}}
````

### Fancy Text

```bash
quarto add quarto-ext/fancy-text
```

````markdown
{{< lipsum 1 >}}
````

### Social Cards

```bash
quarto add gadenbuie/quarto-social-embeds
```

````markdown
{{< tweet user=username id=123456789 >}}
````

## Extension Configuration

Some extensions have configuration options:

```yaml
lightbox:
  match: auto
  effect: zoom
  loop: true

fontawesome:
  version: 6
```

## Creating Custom Extensions

### Basic Structure

```txt
_extensions/
└── my-extension/
    ├── _extension.yml
    └── my-extension.lua
```

### Extension YAML

In `_extension.yml`:

```yaml
title: My Extension
author: Your Name
version: 1.0.0
contributes:
  shortcodes:
    - my-extension.lua
```

### Shortcode Lua

In `my-extension.lua`:

```lua
return {
  ['my-shortcode'] = function(args)
    local text = args[1] or "default"
    return pandoc.Str("Processed: " .. text)
  end
}
```

### Use

````markdown
{{< my-shortcode "Hello" >}}
````

## Troubleshooting

### Extension Not Found

```txt
ERROR: Extension not found
```

- Check extension is in `_extensions/`
- Verify extension name matches folder

### Trust Warning

When installing, Quarto asks about trust. Extensions run code during render.

### Conflicts

If extensions conflict, try:

1. Check extension documentation for compatibility
2. Update extensions to latest versions
3. Report issue to extension maintainer

## Extension Sources

### GitHub Organizations

- `quarto-ext` - Official Quarto extensions
- `quarto-journals` - Academic journal formats

### Popular Repositories

| Extension                       | Description           |
| ------------------------------- | --------------------- |
| `quarto-ext/fontawesome`        | Font Awesome icons    |
| `quarto-ext/lightbox`           | Image lightbox        |
| `quarto-ext/include-code-files` | Include external code |
| `shafayetShafee/bsicons`        | Bootstrap icons       |
| `mcanouil/quarto-letter`        | Letter format         |
| `jmbuhr/quarto-molstar`         | Molecular viewer      |

## Best Practices

### Before Installing

1. Check extension source is trustworthy
2. Read the documentation
3. Check compatibility with your Quarto version

### In Projects

1. Document which extensions are used
2. Include `_extensions/` in version control
3. Pin versions for reproducibility

### Updating

1. Test updates in development first
2. Check changelogs for breaking changes
3. Update one at a time

## Resources

- [Quarto Extensions Guide](https://quarto.org/docs/extensions/)
- [Creating Extensions](https://quarto.org/docs/extensions/creating.html)
- [Community Extensions](https://m.canouil.dev/quarto-extensions/)
- [Extensions JSON API](https://m.canouil.dev/quarto-extensions/extensions.json)