#tutorial #customization #hugo

Complete Customization Guide

Learn how to customize every aspect of your Kawaii theme

The Kawaii theme is designed to be highly customizable while maintaining its beautiful aesthetics. This guide will walk you through all the ways you can make the theme truly yours.

Configuration Options

Basic Site Settings

1# hugo.toml
2baseURL = "https://yoursite.com"
3languageCode = "en-us"
4title = "Your Amazing Site"
5theme = "kawaii"
6
7[params]
8  description = "Your site description"
9  author = "Your Name"

Theme-Specific Settings

 1[params]
 2  # Enable/disable features
 3  theme_toggle = true      # Dark mode toggle
 4  search = true           # Search functionality
 5  
 6  # Favicon
 7  favicon = "/favicon.ico"
 8  
 9  # Hero section
10  hero_cta = "Get Started"
11  hero_cta_link = "/getting-started"

Color Customization

Using CSS Variables

The easiest way to customize colors is by overriding CSS variables:

1/* assets/css/custom.css */
2:root {
3  --kawaii-primary: #your-color;
4  --kawaii-secondary: #your-color;
5  --kawaii-accent: #your-color;
6}

Common Color Overrides

 1/* Brand colors */
 2:root {
 3  --kawaii-primary: #e91e63;        /* Pink to custom */
 4  --kawaii-secondary: #3f51b5;      /* Blue to custom */
 5  --kawaii-accent: #009688;         /* Teal to custom */
 6}
 7
 8/* Background colors */
 9:root {
10  --kawaii-bg-primary: #ffffff;     /* Main background */
11  --kawaii-bg-secondary: #f8f9fa;   /* Secondary background */
12}

Typography Customization

Changing Fonts

1/* Custom fonts */
2:root {
3  --kawaii-font-family: 'Your Font', sans-serif;
4  --kawaii-font-mono: 'Your Mono Font', monospace;
5}
6
7/* Import your fonts */
8@import url('https://fonts.googleapis.com/css2?family=Your+Font:wght@300;400;500;600;700&display=swap');

Typography Scale

1/* Customize heading sizes */
2h1 { font-size: 3rem; }      /* Default: 2.5rem */
3h2 { font-size: 2.25rem; }   /* Default: 2rem */
4h3 { font-size: 1.75rem; }   /* Default: 1.5rem */

Layout Customization

Homepage Sections

Configure featured sections in your hugo.toml:

1[[params.featured_sections]]
2  title = "Your Feature"
3  description = "Feature description"
4  icon = "🚀"
5  link = "/your-link"

 1[menu]
 2  [[menu.main]]
 3    name = "Home"
 4    url = "/"
 5    weight = 10
 6  
 7  [[menu.main]]
 8    name = "Blog"
 9    url = "/blog"
10    weight = 20

 1[[params.social]]
 2  name = "github"
 3  url = "https://github.com/yourusername"
 4
 5[[params.social]]
 6  name = "twitter"
 7  url = "https://twitter.com/yourusername"
 8
 9[[params.social]]
10  name = "linkedin"
11  url = "https://linkedin.com/in/yourusername"

Advanced Customization

Custom Layouts

Create custom layouts by copying theme files to your site:

1# Copy and modify layouts
2cp themes/kawaii/layouts/_default/single.html layouts/_default/

Custom Partials

Add custom functionality with partials:

1<!-- layouts/partials/custom-header.html -->
2<div class="my-custom-header">
3  <!-- Your custom content -->
4</div>

Custom CSS

Add your own styles:

 1/* assets/css/custom.css */
 2.my-custom-class {
 3  /* Your styles */
 4}
 5
 6/* Override existing styles */
 7.kawaii-post-card {
 8  border-radius: 20px;
 9  box-shadow: 0 8px 32px rgba(0,0,0,0.1);
10}

Custom JavaScript

Add custom functionality:

1// assets/js/custom.js
2document.addEventListener('DOMContentLoaded', function() {
3  // Your custom JavaScript
4});

Content Customization

Post Front Matter

Enhance your posts with custom front matter:

1---
2title: "Your Post Title"
3date: 2024-01-15T10:00:00Z
4description: "Post description"
5tags: ["tag1", "tag2"]
6featured_image: "/images/featured.jpg"
7author: "Author Name"
8---

Custom Shortcodes

Create reusable content components:

1<!-- layouts/shortcodes/callout.html -->
2<div class="kawaii-callout kawaii-callout-{{ .Get 0 }}">
3  {{ .Inner | markdownify }}
4</div>

Use in content:

1{{/* callout "info" */}}
2This is an info callout!
3{{/* /callout */}}

Performance Optimization

Image Optimization

1<!-- Use Hugo's image processing -->
2{{ $image := .Page.Resources.GetMatch "featured.jpg" }}
3{{ $processed := $image.Resize "800x" }}
4<img src="{{ $processed.RelPermalink }}" alt="{{ .Title }}">

CSS/JS Minification

1# hugo.toml
2[minify]
3  disableCSS = false
4  disableJS = false
5  disableHTML = false

Deployment Configuration

Netlify

1# netlify.toml
2[build]
3  command = "hugo --minify"
4  publish = "public"
5
6[build.environment]
7  HUGO_VERSION = "0.120.0"

Vercel

 1{
 2  "build": {
 3    "env": {
 4      "HUGO_VERSION": "0.120.0"
 5    }
 6  },
 7  "scripts": {
 8    "build": "hugo --minify"
 9  }
10}

Troubleshooting

Common Issues

  1. CSS not loading: Check file paths and Hugo version
  2. JavaScript errors: Ensure jQuery isn’t conflicting
  3. Images not displaying: Verify image paths and formats

Debug Mode

Enable Hugo’s debug mode:

1hugo server --debug --verbose

Getting Help

  • Documentation: Check the theme docs
  • GitHub Issues: Report bugs and feature requests
  • Community: Join our Discord server
  • Examples: Browse the example site code

Remember: The best customization respects the theme’s design principles while making it uniquely yours!