miki-template VS Code Extension

The ultimate VS Code extension for miki-template and Django templates. Packed with features to supercharge your template development.

Why miki-template?

• 100% Django compatible
• All Django template tags & filters
• miki-template extensions (partialdef, cache, addtoblock)
• Works with .django, .dj, .miki, .miki-template files

Features

🔥 Intelligent Completions

• Tags: All 50+ Django/miki-template tags
• Filters: All 70+ filters with argument hints
• forloop. variables*: Auto-complete when inside for loops
• Custom tags/filters: Auto-detected from project config
• Common variables: user, request, form, items, etc.
• Path completions: Auto-suggest template files for {% include %} and {% extends %}

📖 Hover Documentation

Hover over any tag or filter to see:

• Full description
• Syntax example
• Argument hints for filters
• {{ block.super }} shows parent block content explanation

⚡ Real-time Validation

• Unclosed tag detection
• Mismatched opening/closing tags
• {% extends %} placement validation
• Performance optimized with debouncing

🎨 Color Decorations

Automatically highlights:

• #ff0000, #fff, #ffffffaa
• rgb(), rgba()
• hsl(), hsla()

🔧 Code Actions (Quick Fixes)

• Add missing {% endif %}
• Add missing {% endfor %}
• Wrap selection in {% block %}
• Add {# prettier-ignore #}

💡 Inlay Hints

Show inline parameter hints for filter arguments.

🔗 Bracket Matching Highlights

Highlight matching {% if %} / {% endif %} pairs.

🚀 Go-to-Definition

Jump to:

• {% include "file" %}
• {% extends "file" %}
• {% block name %}
• {% partialdef name %}

🔍 Project-wide Find References

Find all references to:

• Block definitions across workspace
• Included templates
• Extended templates

📋 Smart Tag Selection

Double-click to select entire {% block %} content.

🎯 Quick Outline Navigation

Jump between blocks with keyboard shortcuts.

📝 Template Preview

Preview template syntax in a new tab.

✏️ Rename Blocks (F2)

Rename any {% block name %} and automatically update all {{ block.name }} references across your entire workspace. Just place cursor on a block name and press F2.

🎨 Semantic Highlighting

Enhanced syntax highlighting using VS Code's Semantic Token API for better theme support and more accurate token classification.

🌐 HTML/CSS/JS Support

Full embedded language support for:

• HTML: Proper tag and attribute highlighting
• CSS: Syntax highlighting in <style> tags
• JavaScript: Syntax highlighting in <script> tags
• Emmet: Full Emmet abbreviation support for HTML and JavaScript
• Auto-closing: HTML tags, brackets, and quotes
• Bracket matching: HTML tags, parentheses, brackets

📋 Smart Paste

Paste HTML content and the extension will automatically append |safe filter to prevent escaping issues.

🔧 Code Actions

Quick fixes for common issues.

Emmet Setup

Emmet works in miki-template and django-html language modes. The extension automatically configures Emmet on first activation, but you can also set it up manually:

Automatic Setup

On first activation, the extension will:

1. Detect if emmet.includeLanguages is missing miki-template or django-html
2. Automatically add the mappings
3. Prompt you to reload the window

Manual Setup

If automatic setup doesn't work, add this to your settings.json:

{
  "emmet.includeLanguages": {
    "miki-template": "html",
    "django-html": "html",
    "django-txt": "html"
  }
}

Then reload VS Code (Developer: Reload Window).

Verifying Emmet Works

1. Open a .miki, .miki-template, or .django file
2. Set the language mode to miki-template (bottom-right corner)
3. Type p and press Tab — it should expand to <p></p>
4. Type ul>li*3 and press Tab — it should expand to a list with 3 items

If Emmet doesn't work, check:

• settings.json contains the emmet.includeLanguages mapping above
• You have reloaded VS Code after installing the extension
• The Emmet extension is enabled (it's built into VS Code)

Quick Commands

Tip: Press F2 on any block name to rename it across the workspace!

Settings

File Associations

Format on Save

{
  "[django-html]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Custom Tags/Filters Detection

The extension auto-detects custom tags and filters from:

• miki-template.config.js
• miki-template.config.json
• .mikirc
• package.json

// miki-template.config.js
module.exports = {
  filters: ['myFilter', 'customFilter'],
  tags: ['myTag', 'customTag']
};

Path Completions

When typing {% include %} or {% extends %}, the extension automatically suggests template files from your workspace:

{% include "partials/"  ← Shows all template files
{% extends "base"       ← Shows matching templates

Files are searched recursively throughout your workspace and filtered as you type.

Examples

Basic Template

{% extends "base.html" %}

{% block content %}
<h1>{{ title|default:"Welcome" }}</h1>

{% if user.is_authenticated %}
  <p>Hello, {{ user.name }}!</p>
{% else %}
  <p>Please log in.</p>
{% endif %}

{% for item in items %}
  <li>{{ forloop.counter }}. {{ item }}</li>
{% empty %}
  <li>No items found.</li>
{% endfor %}
{% endblock %}

Rename Blocks

Place cursor on any {% block name %} and press F2:

<!-- Before rename: block title → block heading -->
{% block title %}Welcome{% endblock %}
{{ block.title }}

<!-- After pressing F2 and entering "heading": -->
{% block heading %}Welcome{% endblock %}
{{ block.heading }}

All references across the workspace are updated automatically.

With Partial

{% partialdef card inline %}
<div class="card">
  <h3>{{ title }}</h3>
  <p>{{ description }}</p>
</div>
{% endpartialdef %}

{% partial card with title="Hello" %}

Troubleshooting

Emmet Not Working

1. Check settings.json for emmet.includeLanguages:

   "emmet.includeLanguages": {
     "miki-template": "html",
     "django-html": "html"
   }
   

2. Reload VS Code after changing settings
3. Ensure the language mode (bottom-right) is set to miki-template or django-html

Completions Not Showing

1. Ensure miki-template.enableCompletions is true
2. Check that the language mode is miki-template, django-html, or django-txt
3. In plain html mode, Django tags/filters are provided via snippets, not the completion provider
4. Try pressing Ctrl+Space to manually trigger completions

Tags/Filters Missing

• The extension includes 70+ tags and 100+ filters
• Custom tags/filters are auto-detected from project config files
• Check the console for errors if completions are incomplete

Development

# Install dependencies
npm install

# Run tests
npm test

# Package
npm run package

# Watch & install
npm run watch

License

MIT

Support

If this extension helps you, consider buying me a coffee!