https://github.com/ruslanlap/catppuccin-mkdocs
https://github.com/ruslanlap/catppuccin-mkdocs
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ruslanlap/catppuccin-mkdocs
- Owner: ruslanlap
- License: mit
- Created: 2025-11-21T18:32:28.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-11-21T20:10:06.000Z (7 months ago)
- Last Synced: 2025-11-21T20:29:32.872Z (7 months ago)
- Language: CSS
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎨 MkDocs Catppuccin Theme
Soothing pastel theme for MkDocs based on the Catppuccin color palette
---
## 📖 Overview
This is a [MkDocs](https://www.mkdocs.org/) theme that extends [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) with the beautiful [Catppuccin](https://catppuccin.com) color palette. It provides a comfortable and aesthetically pleasing documentation experience with carefully crafted soothing pastel colors.
## ✨ Features
- 🎨 **Four Catppuccin Flavors**: Latte (light), Frappé, Macchiato, and Mocha (dark)
- 🌈 **Complete Color Integration**: All UI elements styled with Catppuccin colors
- 🎯 **Syntax Highlighting**: Code blocks with Catppuccin-themed syntax colors
- 📱 **Fully Responsive**: Works perfectly on all devices
- 🔌 **Easy Installation**: Just `pip install mkdocs-catppuccin`
- ⚡ **Extends Material**: All Material for MkDocs features available
## 🚀 Installation
Install the theme using pip:
```bash
pip install mkdocs-catppuccin
```
Or install from source:
```bash
git clone https://github.com/ruslanlap/Catppuccin-MkDocs.git
cd Catppuccin-MkDocs
pip install -e .
```
## 📝 Step-by-Step Configuration Guide
### Step 1: Install the Theme
```bash
pip install mkdocs-catppuccin
```
### Step 2: Create Project Structure
Your MkDocs project should have this structure:
```
your-project/
├── docs/
│ ├── index.md # Home page
│ ├── assets/ # Assets folder (optional)
│ │ └── logo.png # Your logo
│ └── stylesheets/ # CSS folder (optional)
│ └── extra.css # Your custom styles
└── mkdocs.yml # Configuration file
```
### Step 3: Basic Configuration
Create or edit your `mkdocs.yml` file:
```yaml
# Basic site information
site_name: Your Project Name
site_description: Your documentation description
site_url: https://yourname.github.io/your-project/
# Catppuccin theme configuration
theme:
name: catppuccin
# Choose color scheme (pick one or multiple)
palette:
# Light theme - Catppuccin Latte
- scheme: latte
toggle:
icon: material/weather-sunny
name: Switch to dark mode
# Dark theme - Catppuccin Mocha
- scheme: mocha
toggle:
icon: material/weather-night
name: Switch to light mode
# Add your logo (optional)
logo: assets/logo.png # Path to your logo
favicon: assets/logo.png # Browser tab icon
# Useful features
features:
- navigation.tabs # Navigation tabs
- navigation.sections # Navigation sections
- navigation.top # Back to top button
- search.suggest # Search suggestions
- search.highlight # Highlight search results
- content.code.copy # Copy code button
# Your site navigation
nav:
- Home: index.md
- About: about.md
# Plugins
plugins:
- search # Documentation search
```
### Step 4: Custom Styles (Optional)
**IMPORTANT:** The theme already includes all Catppuccin styles! You **DO NOT need** to add `extra_css` for basic usage.
Add `extra_css` **ONLY if** you want to customize something:
```yaml
# Add this ONLY if you need custom styles
extra_css:
- stylesheets/extra.css # Your custom styles
```
Create `docs/stylesheets/extra.css` file for your customizations:
```css
/* Example: change heading color */
.md-typeset h1 {
color: #c6a0f6; /* Catppuccin Mauve */
}
```
#### 🎨 Changing Accent Color (New Simplified Method!)
The theme uses **Green** as the default accent color for all flavors. You can now change the accent color for **all themes in just one place**!
**Super Easy Method** (Recommended):
1. Open `docs/stylesheets/catppuccin.css`
2. Find the **ACCENT COLOR CONFIGURATION** section at the top (lines 5-18)
3. Change `green` to any color you want in just **4 lines**!
**Example - Change from Green to Pink:**
```css
/* ========================================
ACCENT COLOR CONFIGURATION
Change these to modify the accent color for all themes in one place!
Available colors: green, pink, blue, mauve, lavender, sky, teal, etc.
======================================== */
:root {
/* Change these 4 lines to switch accent colors for all themes */
--accent-latte: var(--ctp-latte-pink);
/* Default: green, Try: var(--ctp-latte-pink) */
--accent-frappe: var(--ctp-frappe-pink);
/* Default: green, Try: var(--ctp-frappe-pink) */
--accent-macchiato: var(--ctp-macchiato-pink);
/* Default: green, Try: var(--ctp-macchiato-pink) */
--accent-mocha: var(--ctp-mocha-pink);
/* Default: green, Try: var(--ctp-mocha-pink) */
}
```
**Available Catppuccin colors:**
`pink`, `mauve`, `blue`, `sapphire`, `sky`, `teal`, `green`, `yellow`, `peach`, `red`, `maroon`, `lavender`, `flamingo`, `rosewater`
**What gets changed:**
- ✅ Link colors
- ✅ Navigation active states
- ✅ Hover effects
- ✅ Code syntax highlighting (strings)
- ✅ Success admonitions
- ✅ Scrollbar hover
- ✅ Table of contents active items
### Step 5: All 4 Color Schemes
If you want to give users a choice of all 4 Catppuccin variants:
```yaml
theme:
name: catppuccin
palette:
# Light theme - Latte
- scheme: latte
toggle:
icon: material/weather-sunny
name: Switch to Frappé
# Dark theme - Frappé (coolest)
- scheme: frappe
toggle:
icon: material/weather-night
name: Switch to Macchiato
# Dark theme - Macchiato (warm)
- scheme: macchiato
toggle:
icon: material/weather-partly-cloudy
name: Switch to Mocha
# Dark theme - Mocha (warmest)
- scheme: mocha
toggle:
icon: material/weather-cloudy
name: Switch to Latte
```
### Step 6: Complete Configuration Example
Here's a complete `mkdocs.yml` example with all features:
```yaml
site_name: My Documentation
site_description: Beautiful documentation with Catppuccin theme
site_url: https://yourname.github.io/your-project/
repo_url: https://github.com/yourname/your-project
repo_name: yourname/your-project
theme:
name: catppuccin
palette:
- scheme: latte
toggle:
icon: material/weather-sunny
name: Switch to Frappé
- scheme: frappe
toggle:
icon: material/weather-night
name: Switch to Macchiato
- scheme: macchiato
toggle:
icon: material/weather-partly-cloudy
name: Switch to Mocha
- scheme: mocha
toggle:
icon: material/weather-cloudy
name: Switch to Latte
logo: assets/logo.png
favicon: assets/logo.png
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.footer
- navigation.top
- navigation.tracking
- search.suggest
- search.highlight
- search.share
- content.code.copy
- content.code.annotate
# Navigation
nav:
- Home: index.md
- Configuration: configuration.md
# Plugins
plugins:
- search
# Markdown extensions
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- tables
- toc:
permalink: true
# Copyright
copyright: Copyright © 2025 Your Name
# Additional settings
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/yourname/your-project
generator: false
```
### 📌 Important Notes
1. **Logo**: Place your `logo.png` file in the `docs/assets/` folder
2. **CSS**: The theme already includes all Catppuccin styles - `extra_css` is only needed for your own customizations
3. **Color schemes**: You can use a single scheme or all four with a toggle
4. **Testing**: Run `mkdocs serve` to preview your documentation locally
## 🎨 Color Schemes
### Light Mode - Latte 🌻
Perfect for daytime reading with warm, gentle tones:
- **Background**: `#eff1f5` (Base)
- **Text**: `#4c4f69` (Text)
- **Primary**: `#8839ef` (Mauve)
- **Accent**: `#1e66f5` (Blue)
### Dark Mode - Mocha 🌙
Cozy and comfortable for nighttime with rich, soft colors:
- **Background**: `#1e1e2e` (Base)
- **Text**: `#cdd6f4` (Text)
- **Primary**: `#cba6f7` (Mauve)
- **Accent**: `#89b4fa` (Blue)
### Syntax Highlighting
Both themes include complete syntax highlighting:
- **Keywords**: Red
- **Strings**: Green
- **Functions**: Mauve
- **Numbers**: Peach
- **Comments**: Overlay0
- **Operators**: Sky
- **Variables**: Rosewater
## 📦 What's Included
```
mkdocs-catppuccin/
├── mkdocs_catppuccin/
│ ├── __init__.py
│ ├── mkdocs_theme.yml # Theme configuration
│ └── assets/
│ └── stylesheets/
│ └── catppuccin.css # Catppuccin colors
├── pyproject.toml # Package configuration
├── LICENSE # MIT License
└── README.md # This file
```
## 🔧 Development
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/ruslanlap/Catppuccin-MkDocs.git
cd Catppuccin-MkDocs
# Install in editable mode
pip install -e .
# Create a test MkDocs project
mkdocs new test-site
cd test-site
# Configure to use the theme
echo "theme:
name: catppuccin" > mkdocs.yml
# Serve the documentation
mkdocs serve
```
### Building the Package
```bash
# Install build tools
pip install build twine
# Build the package
python -m build
# The package will be in dist/
```
### Publishing to PyPI
```bash
# Upload to TestPyPI first
python -m twine upload --repository testpypi dist/*
# If everything looks good, upload to PyPI
python -m twine upload dist/*
```
## 🤝 Contributing
Contributions are welcome! Feel free to:
- Report bugs
- Suggest new features
- Submit pull requests
- Improve documentation
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Credits
- **Catppuccin Theme**: [catppuccin.com](https://catppuccin.com) - The beautiful color palette
- **Material for MkDocs**: [squidfunk/mkdocs-material](https://github.com/squidfunk/mkdocs-material) - The base theme
- **MkDocs**: [mkdocs.org](https://www.mkdocs.org/) - The documentation framework
## 🔗 Links
- **Homepage**: [github.com/ruslanlap/Catppuccin-MkDocs](https://github.com/ruslanlap/Catppuccin-MkDocs)
- **PyPI**: [pypi.org/project/mkdocs-catppuccin](https://pypi.org/project/mkdocs-catppuccin)
- **Catppuccin**: [catppuccin.com](https://catppuccin.com)
- **Material for MkDocs**: [squidfunk.github.io/mkdocs-material](https://squidfunk.github.io/mkdocs-material)
# Catppuccin-MkDocs