feat: implement modular theme system with file-based theme organization
Transform theme system from large inline dictionaries to maintainable YAML files:
**Architecture:**
- File-based themes organized by scope: mode/, ui/, document/, branding/
- Dynamic theme loading with automatic discovery
- Hybrid system maintaining 100% backward compatibility
- Rich metadata support with theme documentation
**Implementation:**
- Created markitect/themes/ directory with organized structure
- Added ThemeRegistry for dynamic YAML theme loading
- Extracted ChatGPT and Substack themes to separate files
- Added mode themes (light.yaml, dark.yaml) as examples
- Integrated with existing LAYERED_THEMES system seamlessly
**Benefits:**
- Improved maintainability: each theme is a separate file
- Better collaboration: multiple contributors can work simultaneously
- Enhanced discoverability: clear organization shows available themes
- Rich documentation: each theme file includes design notes and metadata
- Schema validation potential with YAML format
**Quality Assurance:**
- Comprehensive 12-test suite for modular system (12/12 passing)
- Backward compatibility verified with existing 15 theme tests (15/15 passing)
- CLI integration tested and working with file-based themes
- Theme combination and scoping functionality preserved
**Files Created:**
- markitect/themes/__init__.py - Theme registry and dynamic loader
- markitect/themes/README.md - Complete documentation and usage guide
- markitect/themes/document/{chatgpt,substack}.yaml - Modular theme files
- markitect/themes/mode/{light,dark}.yaml - Mode theme examples
- tests/test_modular_theme_system.py - Comprehensive test coverage
Addresses maintainability concerns while preserving all existing functionality.
No breaking changes - all existing code, CLI commands, and API calls work unchanged.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
168
markitect/themes/README.md
Normal file
168
markitect/themes/README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Markitect Modular Theme System
|
||||
|
||||
This directory contains the modular theme system for Markitect, allowing themes to be defined in separate YAML files for better maintainability and organization.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
themes/
|
||||
├── __init__.py # Theme loader and registry
|
||||
├── README.md # This file
|
||||
├── mode/ # Mode themes (light/dark color schemes)
|
||||
│ ├── light.yaml
|
||||
│ └── dark.yaml
|
||||
├── ui/ # UI themes (interface styling)
|
||||
│ ├── standard.yaml
|
||||
│ ├── electric.yaml
|
||||
│ └── psychedelic.yaml
|
||||
├── document/ # Document themes (content formatting)
|
||||
│ ├── basic.yaml
|
||||
│ ├── github.yaml
|
||||
│ ├── academic.yaml
|
||||
│ ├── substack.yaml
|
||||
│ └── chatgpt.yaml
|
||||
└── branding/ # Branding themes (company/personal styling)
|
||||
├── corporate.yaml
|
||||
└── startup.yaml
|
||||
```
|
||||
|
||||
## Theme File Format
|
||||
|
||||
Each theme file is a YAML file with the following structure:
|
||||
|
||||
```yaml
|
||||
# Theme metadata
|
||||
name: theme_name
|
||||
description: "Brief description of the theme"
|
||||
scope: document # One of: mode, ui, document, branding
|
||||
author: "Theme Author"
|
||||
version: "1.0.0"
|
||||
|
||||
# Theme properties
|
||||
properties:
|
||||
font_family: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif'
|
||||
max_width: '580px'
|
||||
body_background: '#ffffff'
|
||||
body_color: '#1f1f1f'
|
||||
# ... other CSS properties
|
||||
|
||||
# Optional: Design notes and comments
|
||||
# Design notes:
|
||||
# - Rationale for design choices
|
||||
# - Usage recommendations
|
||||
```
|
||||
|
||||
## Theme Scopes
|
||||
|
||||
### Mode Themes (`mode/`)
|
||||
Control light/dark color schemes:
|
||||
- `light.yaml` - Light color scheme for daytime reading
|
||||
- `dark.yaml` - Dark color scheme for low-light environments
|
||||
|
||||
### UI Themes (`ui/`)
|
||||
Control interface styling:
|
||||
- `standard.yaml` - Clean, professional interface
|
||||
- `electric.yaml` - Vibrant, high-energy styling
|
||||
- `psychedelic.yaml` - Colorful, creative styling
|
||||
|
||||
### Document Themes (`document/`)
|
||||
Control content formatting and typography:
|
||||
- `basic.yaml` - Simple, clean formatting
|
||||
- `github.yaml` - GitHub-inspired styling
|
||||
- `academic.yaml` - Traditional academic formatting
|
||||
- `substack.yaml` - Long-form reading optimization
|
||||
- `chatgpt.yaml` - Compact, interactive layout
|
||||
|
||||
### Branding Themes (`branding/`)
|
||||
Control company/personal branding:
|
||||
- `corporate.yaml` - Professional business styling
|
||||
- `startup.yaml` - Modern startup aesthetic
|
||||
|
||||
## Usage
|
||||
|
||||
Themes are automatically loaded when the system starts. You can use them in several ways:
|
||||
|
||||
### Command Line
|
||||
```bash
|
||||
markitect md-render document.md --theme chatgpt
|
||||
markitect md-render document.md --theme "light,standard,substack"
|
||||
```
|
||||
|
||||
### Programmatic Access
|
||||
```python
|
||||
from markitect.themes import get_theme, list_themes
|
||||
|
||||
# Get a specific theme
|
||||
chatgpt_theme = get_theme('chatgpt')
|
||||
|
||||
# List all themes
|
||||
all_themes = list_themes()
|
||||
|
||||
# List themes by scope
|
||||
document_themes = list_themes(scope='document')
|
||||
```
|
||||
|
||||
## Adding New Themes
|
||||
|
||||
1. Create a new YAML file in the appropriate scope directory
|
||||
2. Follow the standard YAML format (see examples)
|
||||
3. Include proper metadata (name, description, scope, author, version)
|
||||
4. Add comprehensive properties for your theme
|
||||
5. Test with existing content to ensure compatibility
|
||||
|
||||
### Example: Adding a New Theme
|
||||
|
||||
Create `markitect/themes/document/academic_paper.yaml`:
|
||||
|
||||
```yaml
|
||||
name: academic_paper
|
||||
description: "Formal academic paper formatting with traditional typography"
|
||||
scope: document
|
||||
author: "Your Name"
|
||||
version: "1.0.0"
|
||||
|
||||
properties:
|
||||
font_family: 'Times New Roman, Times, serif'
|
||||
heading_font_family: 'Times New Roman, Times, serif'
|
||||
max_width: '650px'
|
||||
line_height: '2.0'
|
||||
text_align: 'justify'
|
||||
body_background: '#ffffff'
|
||||
body_color: '#000000'
|
||||
heading_color: '#000000'
|
||||
# ... additional properties
|
||||
```
|
||||
|
||||
The theme will be automatically available as `academic_paper` after restart.
|
||||
|
||||
## Migration from Inline Themes
|
||||
|
||||
The system uses a hybrid approach:
|
||||
1. Themes defined in YAML files take precedence
|
||||
2. Fallback to inline themes for backward compatibility
|
||||
3. Existing code continues to work without changes
|
||||
|
||||
This allows gradual migration of themes from the main code file to separate files.
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Maintainability**: Each theme is a separate file
|
||||
- **Collaboration**: Multiple people can work on themes simultaneously
|
||||
- **Discoverability**: Easy to see what themes exist
|
||||
- **Documentation**: Each theme file can include design notes
|
||||
- **Validation**: YAML format allows for schema validation
|
||||
- **Modularity**: Themes can be distributed separately
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
The modular theme system is fully backward compatible:
|
||||
- All existing theme names continue to work
|
||||
- Existing LAYERED_THEMES access patterns work unchanged
|
||||
- Legacy TEMPLATE_STYLES mapping preserved
|
||||
- CLI commands work exactly the same
|
||||
|
||||
## Performance
|
||||
|
||||
- Themes are loaded once at startup and cached
|
||||
- No performance impact during normal operation
|
||||
- Reload functionality available for development
|
||||
Reference in New Issue
Block a user