Metadata-Version: 2.4
Name: mkdocs-color-swatch-plugin
Version: 0.3.1
Summary: A MkDocs plugin for inline color swatches with tooltip and hover effects
License: MIT
License-File: LICENSE
Keywords: mkdocs,plugin,markdown,color,tooltip
Author: Fabian Eulitz
Author-email: dev@sustineo.de
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
Requires-Dist: markdown (>=3.8,<4.0)
Requires-Dist: mkdocs (>=1.6.1,<2.0.0)
Project-URL: Repository, https://github.com/fabieu/mkdocs-color-swatch-plugin
Description-Content-Type: text/markdown

# 🎨 Color Swatch Plugin for [MkDocs](https://www.mkdocs.org/)

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

[![GitHub Release](https://img.shields.io/github/v/release/fabieu/mkdocs-color-swatch-plugin)](https://github.com/fabieu/mkdocs-color-swatch-plugin/releases/latest)
[![GitHub Issues](https://img.shields.io/github/issues/fabieu/mkdocs-color-swatch-plugin)](https://github.com/fabieu/mkdocs-color-swatch-plugin/issues)
[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/fabieu/mkdocs-color-swatch-plugin)](https://github.com/fabieu/mkdocs-color-swatch-plugin/pulls)
[![License](https://img.shields.io/github/license/fabieu/mkdocs-color-swatch-plugin)](https://github.com/fabieu/mkdocs-color-swatch-plugin/blob/main/LICENSE)

[![PyPI Version](https://img.shields.io/pypi/v/mkdocs-color-swatch-plugin)](https://pypi.org/project/mkdocs-color-swatch-plugin/)
[![Python Versions](https://img.shields.io/pypi/pyversions/mkdocs-color-swatch-plugin)](https://pypi.org/project/mkdocs-color-swatch-plugin/)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=alert_status)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=security_rating)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)
[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=vulnerabilities)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=fabieu_mkdocs-color-swatch-plugin&metric=sqale_index)](https://sonarcloud.io/summary/overall?id=fabieu_mkdocs-color-swatch-plugin)

## ⭐ 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](https://www.mkdocs.org/) >= 1.4.X
- [Python](https://www.python.org/) >= 3.10

Install the plugin from [PyPI](https://pypi.org/project/mkdocs-color-swatch-plugin/) using `pip`:

```bash
pip install mkdocs-color-swatch-plugin
```

Then enable it in your `mkdocs.yml`:

```yaml
plugins:
  - color-swatch
```

Make sure you have `mkdocs` installed:

```bash
pip install mkdocs
```

---

## ✍️ Syntax & Usage

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

```markdown
: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:

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

You can just write:

```markdown
: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:

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

### Editable Install (for local use):

```bash
poetry install
pip install -e .
```

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

---

## 📄 License

MIT © [Fabian Eulitz](https://github.com/fabieu)

---

## 📎 Resources

- [mkdocs-color-swatch-plugin on PyPI](https://pypi.org/project/mkdocs-color-swatch-plugin/)
- [mkdocs-color-swatch-plugin on GitHub](https://github.com/fabieu/mkdocs-color-swatch-plugin)
- [MkDocs Documentation](https://www.mkdocs.org/)


