sukr/docs/content/configuration.md

+++ title = "Configuration" description = "Complete reference for site.toml configuration" weight = 3 +++

sukr is configured via site.toml. All settings have sensible defaults.

Basic Configuration

title    = "My Site"
author   = "Your Name"
base_url = "https://example.com"

Field	Required	Description
title	Yes	Site title (used in page titles)
author	Yes	Author name (used in feeds)
base_url	Yes	Canonical URL for the site

Path Configuration

All paths are optional. Default values shown:

[paths]
content   = "content"    # Markdown source files
output    = "public"     # Generated HTML output
static    = "static"     # Static assets (copied as-is)
templates = "templates"  # Tera template files

Paths are resolved relative to the config file location. This enables monorepo setups:

# Build site from subdirectory
sukr -c sites/blog/site.toml
# Paths resolve relative to sites/blog/

Navigation Configuration

Control how navigation menus are generated:

[nav]
nested = false  # Show child pages under sections
toc    = false  # Enable table of contents globally

Field	Default	Description
nested	false	Display section children as nested sub-menus
toc	false	Show heading anchors in sidebar (table of contents)

When nested = true, section pages appear as indented sub-items under their parent section. When toc = true, h2-h6 headings are extracted and displayed as anchor links in the sidebar.

Both settings can be overridden per-page via frontmatter.

CLI Options

sukr                           # Use ./site.toml
sukr -c path/to/site.toml      # Custom config
sukr --config path/to/site.toml
sukr -h, --help                # Show help

Frontmatter

Each Markdown file can have TOML frontmatter:

+++
title = "Page Title"
description = "Optional description"
date = 2024-01-15              # For blog posts (native TOML date)
weight = 10                    # Sort order (lower = first)
nav_label = "Short Name"       # Override nav display
section_type = "blog"          # Override section template
template = "custom"            # Override page template
toc = true                     # Override global TOC setting
link_to = "https://..."        # External link (for project cards)
tags = ["rust", "tutorial"]    # Tags for categorization
draft = true                   # Exclude from output
aliases = ["/old/path"]        # Redirect old URLs here
+++

Frontmatter Fields

Field	Type	Default	Description
title	string	(required)	Page title
description	string	(none)	Meta description
date	date	(none)	Publication date (YYYY-MM-DD, native TOML date)
weight	integer	50	Sort order (lower = first)
nav_label	string	title	Override navigation label
section_type	string	directory name	Template dispatch (e.g., "blog", "projects")
template	string	(none)	Custom template name
toc	boolean	global setting	Enable/disable table of contents for this page
link_to	string	(none)	External URL (renders as link instead of page)
tags	list	[]	Tags for categorization
draft	boolean	false	Exclude content from output
aliases	list	[]	Old URL paths that redirect here

Section Types

The section_type field determines which template is used for section indexes:

• blog → templates/section/blog.html
• projects → templates/section/projects.html
• (any other) → templates/section/default.html

If not specified, sukr uses the directory name as the section type.

See Also

• Getting Started — install sukr and build your first site
• Content Organization — how directories map to site structure
• Templates — template directory structure and customization