README.md

# Soul

A minimal, typography-focused Hugo theme with elegant sidebar navigation and full customization support.

## Features

- **Clean, distraction-free design** - Focus on content and readability
- **Responsive sidebar navigation** - Converts to horizontal menu on mobile
- **Typography-first** - Beautiful Inter font with variable font support
- **Fully customizable** - Configure colors, fonts, layout, and menu via `hugo.toml`
- **Fast and lightweight** - No JavaScript dependencies, optimized CSS
- **SEO-ready** - Proper meta tags, OpenGraph, and Twitter card support

## Installation

### As a Git Submodule

```bash
git submodule add https://github.com/isaacmeerloo/soul.git themes/soul
```

### Manual Installation

Download and extract the theme into your `themes/` directory:

```bash
cd themes
git clone https://github.com/isaacmeerloo/soul.git
```

## Configuration

Add `theme = 'soul'` to your `hugo.toml` and configure the theme parameters:

```toml
baseURL = 'https://example.com/'
languageCode = 'en-us'
title = 'My Site'
theme = 'soul'

[params]
  description = "My personal website"
  author = "Your Name"
  keywords = ["blog", "personal"]

  [params.colors]
    background = "#cdecff"
    accent = "#ff6300"
    linkBg = "#fbf1a9"
    linkHover = "#ffffff"
    textPrimary = "rgba(0, 0, 0, 0.60)"
    titleColor = "#ffffff"
    blockquoteBorder = "#ff6300"
    themeColor = "#cdecffc"

  [params.typography]
    enableInterFont = true

  [params.layout]
    navWidth = "300px"
    contentMaxWidth = "800px"

  [[params.menu]]
    name = "Blog"
    url = "/blog"
  [[params.menu]]
    name = "About"
    url = "/about"

  [params.footer]
    startYear = "2025"
```

## Customization

### Colors

All colors can be customized via `params.colors`:
- `background` - Main page background
- `accent` - Hover and accent color
- `linkBg` - Link background color
- `linkHover` - Link hover background
- `textPrimary` - Navigation text color
- `titleColor` - Page title color
- `blockquoteBorder` - Blockquote border color
- `themeColor` - Browser theme color

### Layout

Customize layout dimensions via `params.layout`:
- `navWidth` - Sidebar width (default: "300px")
- `contentMaxWidth` - Content max width (default: "800px")

### Navigation Menu

Define your menu items in `params.menu`:

```toml
[[params.menu]]
  name = "Blog"
  url = "/blog"
[[params.menu]]
  name = "Projects"
  url = "/projects"
```

### Typography

Control font loading via `params.typography.enableInterFont` (default: true).
Set to `false` to use system fonts or provide your own font.

## Advanced Customization

### Overriding Theme Files

You can override any theme file by creating the same file path in your site root. For example:
- Override navigation: Create `/layouts/partials/nav.html` in your site
- Custom CSS: Create `/assets/custom.css` and include it in a custom head partial
- Modify templates: Create `/layouts/_default/single.html` in your site

### Adding Custom CSS

Create `/assets/custom.css` in your site root and include it by overriding the head partial.

## Example Site

See the `exampleSite/` directory for a complete working example.

To run the example:

```bash
cd exampleSite
hugo server
```

## Requirements

- Hugo v0.112.0 or higher (extended version recommended for asset processing)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Credits

Created by [Isaac Meerloo](https://36.church)