mkdocs-color-swatch-plugin

🎨 Color Swatch Plugin for MkDocs

A lightweight plugin that lets you insert inline color swatches into your Markdown docs using a simple, readable syntax.

⭐ Features

• Styled swatches with smooth hover animations and tooltips
• Responsive swatches for all screen sizes
• Supports various color formats:
  • Hex colors - #ff0000/#f00
  • RGB colors - rgb(255, 0, 0)
  • RGBA colors - rgba(255, 0, 0, 0.5)
• No CSS setup required — styles are embedded automatically

Visit demo: https://fabieu.github.io/mkdocs-color-swatch-plugin/

🚀 Installation

Prerequisites

• MkDocs >= 1.4.X
• Python >= 3.10

Install the plugin from PyPI using pip:

pip install mkdocs-color-swatch-plugin

Then enable it in your mkdocs.yml:

plugins:
  - color-swatch

Make sure you have mkdocs installed:

pip install mkdocs

✍️ Syntax & Usage

To add swatches to your Markdown, use the simple, custom inline format:

:color[#e74c3c]: -> Red
:color[rgb(52, 152, 219)]: -> Green
:color[rgba(46, 204, 113, 0.6)]: -> Blue

Each tag will render as:

• A visual color preview
• Dynamically generated tooltips showing the color value and label
• A smooth hover animation for swatch elements

🧠 Why Use This Plugin?

Instead of manually writing HTML for every color sample like:

<span style="background-color: #e74c3c; width: 30px; height: 30px; ..."></span>

You can just write:

:color[#e74c3c]:  

It's faster, cleaner, and scales dynamically with your content.

💡 Features & Benefits

• 🎨 Works with all valid hex, rgb(), and rgba() color values
• 🎯 Simple syntax for embedding colors directly in your Markdown files
• 🛠 Automatically injected CSS for responsive and visually appealing swatches
• 🔄 Perfectly safe to use with other Markdown extensions
• 🔍 Live color preview in rendered HTML files, complete with tooltips

🛠 Development & Contribution

👨‍💻 Repository Setup:

Clone the project repository and configure the environment with Poetry:

git clone https://github.com/yourusername/mkdocs-color-swatch-plugin.git
cd mkdocs-color-swatch-plugin
poetry install

Editable Install (for local use):

poetry install
pip install -e .

This allows you to test your changes directly when running MkDocs locally.

📄 License

MIT © Fabian Eulitz

📎 Resources

• mkdocs-color-swatch-plugin on PyPI
• mkdocs-color-swatch-plugin on GitHub
• MkDocs Documentation