eleventy-vue-shortcodes

Compile-time Vue SFC shortcodes for Eleventy - use Vue components in markdown without client-side JavaScript.

Features

• 🚀 Zero Runtime: Vue components are compiled at build time - no client-side JavaScript needed
• 📝 Markdown Ready: Use Vue components directly in your markdown files as shortcodes
• 🎨 Scoped CSS: Automatic CSS scoping prevents style conflicts
• ⚡ Fast: No hydration overhead, pure static HTML output
• 🔧 Simple Setup: Auto-registers all Vue components as Eleventy shortcodes
• 🎯 Flexible Props: Pass data to components via shortcode parameters

Installation

npm install eleventy-vue-shortcodes

Quick Start

1. Configure Eleventy (in eleventy.config.js or .eleventy.js):

import { VueShortcodes } from 'eleventy-vue-shortcodes';

export default function(eleventyConfig) {
  // Register the plugin
  eleventyConfig.addPlugin(VueShortcodes, {
    componentsDir: '_includes/components',  // Where your Vue components live
    scopedCSS: true,                        // Enable automatic CSS scoping
    verbose: false                          // Set to true for debug output
  });
}

2. Create a Vue Component (_includes/components/WelcomeBox.vue):

<template>
  <div class="welcome-box">
    <h2>{{ greeting }}</h2>
    <p>{{ message }}</p>
    <button @click="increment">Clicked {{ count }} times</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';

defineProps({
  greeting: {
    type: String,
    default: 'Hello from Vue!'
  },
  message: {
    type: String, 
    default: 'This is a Vue component in your markdown!'
  }
});

const count = ref(0);
const increment = () => count.value++;
</script>

<style scoped>
.welcome-box {
  border: 2px solid #42b883;
  border-radius: 8px;
  padding: 1rem;
  margin: 1rem 0;
}

.welcome-box h2 {
  color: #42b883;
  margin-top: 0;
}

button {
  background: #42b883;
  color: white;
  border: none;
  padding: 0.5rem 1rem;
  border-radius: 4px;
  cursor: pointer;
}
</style>

3. Use in Markdown (index.md):

# My Page

Here's a Vue component in markdown:

{% WelcomeBox "Custom Greeting!", "This message was passed as a prop!" %}

Regular markdown content continues here...

Configuration Options

eleventyConfig.addPlugin(VueShortcodes, {
  // Directory containing Vue components (relative to Eleventy input dir)
  componentsDir: '_includes/components',
  
  // Enable automatic CSS scoping
  scopedCSS: true,
  
  // Auto-register components as shortcodes
  autoRegister: true,
  
  // Optional prefix for shortcode names
  prefix: '', // e.g., 'vue-' would create 'vue-WelcomeBox'
  
  // File extensions to process
  extensions: ['.vue'],
  
  // Enable debug logging
  verbose: false
});

How It Works

1. Build Time Processing: Vue components are parsed and processed during Eleventy's build phase
2. Template Compilation: Vue templates are converted to static HTML with prop interpolation
3. CSS Scoping: Styles are automatically scoped with unique class names to prevent conflicts
4. Shortcode Registration: Each Vue component becomes an Eleventy shortcode you can use in templates
5. Static Output: Final HTML contains no Vue runtime - just pure, fast-loading HTML and CSS

Prop Handling

Currently supports simple prop passing via shortcode parameters:

{% ComponentName "firstProp", "secondProp" %}

Props are mapped in order to your component's defineProps() definition.

Examples

See the examples/basic-usage/ directory for a complete working example.

Requirements

• Node.js >= 18.0.0
• Eleventy >= 3.0.0

License

MIT

Contributing

Issues and pull requests welcome! This is an early-stage project with room for enhancement.

Roadmap

• [ ] Named parameter support ({% Component prop="value" %})
• [ ] Slot content support
• [ ] Advanced template features (v-if, v-for handling)
• [ ] TypeScript support
• [ ] More comprehensive test suite