feat(config): add support for multiple CSS entry points (#174)

- Add TAILWIND_CLI_CSS_MAP setting for multiple source/destination pairs
- Add CSSEntry NamedTuple for structured CSS entry representation
- Add mutual exclusivity validation between single-file and multi-file modes
- Update template tag to use Config class for consistent validation
- Add optional name parameter to {% tailwind_css %} for filtering entries
- Add MultiWatchProcessManager for parallel watch processes
- Add integration tests for multi-file build and watch commands
- Add documentation for new settings and template tag usage

Author: oliverandrich

CHANGELOG.md

@@ -2,12 +2,18 @@
 
 ## Unreleased
 
+### 🎯 New Features
+- **Multiple CSS entry points**: Added `TAILWIND_CLI_CSS_MAP` setting for compiling multiple CSS files in a single project (e.g., separate admin and frontend styles)
+- **Template tag enhancement**: `{% tailwind_css %}` now supports optional name parameter for multi-file mode: `{% tailwind_css "admin" %}`
+
 ### 🔧 Technical Improvements
 - **Django support**: Dropped support for Django 5.1 (now supporting Django 4.2 LTS, 5.2, and 6.0 only)
 - **Pre-commit hooks**: Updated uv-secure (0.15.4) and pyright (1.1.407)
 - **Security**: Updated Django and Werkzeug to fix security vulnerabilities
 - **Documentation**: Migrated from MkDocs to Sphinx with myst-parser and Furo theme
 - **Documentation**: Added Advanced Configuration and Development Workflow pages
+- **Template tag consistency**: Template tag now uses Config class for consistent validation
+- **Test coverage**: Added integration tests for multi-file build and watch commands
 
 ### 🛠️ Developer Experience
 - **Cleanup command**: Added `just clean` target to remove temporary files and build artifacts

docs/settings.md

@@ -85,6 +85,30 @@ If it is an absolute path, this path is used as the input file for Tailwind CSS
 The name of the output file. This file is stored relative to the first element of the
 `STATICFILES_DIRS` array.
 
+### TAILWIND_CLI_CSS_MAP
+
+**Default**: `None`
+
+A list of tuples defining multiple CSS source/destination pairs. Each tuple contains:
+- Source CSS file path (relative to `BASE_DIR`)
+- Destination CSS file path (relative to `STATICFILES_DIRS[0]`)
+
+```python
+TAILWIND_CLI_CSS_MAP = [
+    ("admin.css", "admin.output.css"),
+    ("web.css", "web.output.css"),
+]
+```
+
+:::{warning}
+This setting is **mutually exclusive** with `TAILWIND_CLI_SRC_CSS` and `TAILWIND_CLI_DIST_CSS`.
+You cannot use both configuration modes at the same time. If `TAILWIND_CLI_CSS_MAP` is defined,
+the single-file settings will be ignored and a warning will be raised.
+:::
+
+The entry name is derived from the source filename (without extension). This name can be used
+with the `{% tailwind_css %}` template tag to include specific CSS files.
+
 ### TAILWIND_CLI_USE_DAISY_UI
 
 **Default**: `False`
@@ -198,6 +222,61 @@ Example content of `src/styles/daisyui.css` with theme configuration:
 
 For more configuration options, see the [DaisyUI Configuration Documentation](https://daisyui.com/docs/config/).
 
+### Multiple CSS Entry Points
+
+For projects that need separate CSS files for different parts of the application (e.g., admin panel and public website):
+
+```python
+# settings.py
+TAILWIND_CLI_CSS_MAP = [
+    ("styles/admin.css", "css/admin.css"),
+    ("styles/web.css", "css/web.css"),
+]
+```
+
+Example source files:
+
+`styles/admin.css`:
+```css
+@import "tailwindcss";
+
+@source "../templates/admin/**/*.html";
+
+@layer components {
+  .admin-panel {
+    @apply bg-gray-100 p-4 rounded-lg;
+  }
+}
+```
+
+`styles/web.css`:
+```css
+@import "tailwindcss";
+
+@source "../templates/web/**/*.html";
+
+@layer components {
+  .hero-section {
+    @apply bg-gradient-to-r from-blue-500 to-purple-600;
+  }
+}
+```
+
+In your templates, include all CSS files or filter by name:
+
+```htmldjango
+{# Include all CSS files #}
+{% tailwind_css %}
+
+{# Include only admin CSS #}
+{% tailwind_css "admin" %}
+
+{# Include only web CSS #}
+{% tailwind_css "web" %}
+```
+
+The `build` command processes all entries, and the `watch` command monitors all source files simultaneously.
+
 ### Staging Environment
 
 Balanced between dev flexibility and prod stability:

docs/template_tags.md

@@ -28,3 +28,35 @@ Depending on the value of the variable `settings.DEBUG` it also activates preloa
   ```html
   <link rel="stylesheet" href="/static/css/styles.css" />
   ```
+
+### Optional `name` Parameter
+
+When using `TAILWIND_CLI_CSS_MAP` for multiple CSS entry points, you can optionally filter
+which CSS files to include by passing a name:
+
+```htmldjango
+{# Include all CSS files defined in CSS_MAP #}
+{% tailwind_css %}
+
+{# Include only the "admin" entry #}
+{% tailwind_css "admin" %}
+
+{# Include only the "web" entry #}
+{% tailwind_css "web" %}
+```
+
+The name corresponds to the source filename (without extension and path) defined in your
+`TAILWIND_CLI_CSS_MAP` setting. For example, with this configuration:
+
+```python
+TAILWIND_CLI_CSS_MAP = [
+    ("styles/admin.css", "css/admin.output.css"),
+    ("styles/web.css", "css/web.output.css"),
+]
+```
+
+- `{% tailwind_css "admin" %}` includes only `css/admin.output.css`
+- `{% tailwind_css "web" %}` includes only `css/web.output.css`
+- `{% tailwind_css %}` includes both files
+
+If the specified name doesn't match any entry, no output is generated.