mkdocs-catppuccin 0.1.1

A soothing pastel theme for MkDocs based on the Catppuccin color palette

🎨 MkDocs Catppuccin Theme

Soothing pastel theme for MkDocs based on the Catppuccin color palette

---

📖 Overview

This is a MkDocs theme that extends Material for MkDocs with the beautiful Catppuccin 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:

pip install mkdocs-catppuccin

Or install from source:

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

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:

# 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:

# 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:

/* 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:

/* ========================================
   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:

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:

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

# 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

# Install build tools
pip install build twine

# Build the package
python -m build

# The package will be in dist/

Publishing to PyPI

# 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 file for details.

🙏 Credits

• Catppuccin Theme: catppuccin.com - The beautiful color palette
• Material for MkDocs: squidfunk/mkdocs-material - The base theme
• MkDocs: mkdocs.org - The documentation framework

🔗 Links

• Homepage: github.com/ruslanlap/Catppuccin-MkDocs
• PyPI: pypi.org/project/mkdocs-catppuccin
• Catppuccin: catppuccin.com
• Material for MkDocs: squidfunk.github.io/mkdocs-material

Catppuccin-MkDocs