Skip to content

Add minimal default theme to zola init#3139

Open
nooscraft wants to merge 2 commits intogetzola:nextfrom
nooscraft:add-default-theme
Open

Add minimal default theme to zola init#3139
nooscraft wants to merge 2 commits intogetzola:nextfrom
nooscraft:add-default-theme

Conversation

@nooscraft
Copy link
Copy Markdown

@nooscraft nooscraft commented Apr 10, 2026

Fixes #3137

Summary

This PR adds a minimal default theme that is automatically generated when running zola init, providing new users with a working site out of the box.

Motivation

Currently, zola init creates empty directories, which results in errors when users try to run zola serve immediately. This creates a rough first experience compared to other SSGs like Jekyll, 11ty, and Hugo (with themes).

Approach

Following the maintainer's guidance to use an 11ty-style minimal approach, this implementation:

  • Generates essential files automatically
  • Provides ~150 lines of minimal CSS
  • Uses system fonts only
  • Creates a max-width container (720px) for readability
  • Includes basic templates demonstrating Zola's template syntax
  • Remains minimal enough that users won't feel bad replacing it

Changes

Files Generated by zola init

  1. .gitignore - Ignores public/ and .DS_Store
  2. README.md - Basic getting started guide with zola serve and zola build commands
  3. content/_index.md - Homepage content with TOML front matter
  4. templates/base.html - Base HTML5 template with semantic structure
  5. templates/index.html - Homepage template extending base
  6. templates/page.html - Single page template
  7. templates/section.html - Section list template with page iteration
  8. static/style.css - Minimal stylesheet (~150 lines)

CSS Features

  • Reset and box-sizing
  • System font stack
  • Responsive max-width container (720px)
  • Readable typography (line-height 1.6)
  • Basic link styling (#0066cc)
  • Simple header with navigation
  • Footer with subtle border
  • Code block styling
  • Minimal color palette (black text, gray accents, blue links)

Testing

All existing tests pass, plus updated test assertions for the new generated files.

Manual Testing

# Create a new site
zola init mysite
cd mysite

# Build immediately (works!)
zola build

# Serve immediately (works!)
zola serve

The site now works immediately without any additional setup or configuration.

Design Philosophy

  • Intentional but minimal - Looks complete, not broken, but easy to replace
  • No dependencies - No JavaScript, no web fonts, no build tools
  • Educational - Templates demonstrate Zola's syntax for new users
  • 11ty-inspired - Follows the maintainer's preferred approach

Backward Compatibility

✅ Fully backward compatible:

  • All existing tests pass
  • --force flag works as expected
  • Directory structure unchanged
  • Only adds files, doesn't modify behavior

Screenshots

Before (Current Behavior)

$ zola init mysite
$ cd mysite
$ zola serve
Error: Failed to build the site
Reason: Failed to render index page

After (This PR)

$ zola init mysite
$ cd mysite
$ zola serve
Building site...
-> Creating 0 pages (0 orphan) and 0 sections
Web server is available at http://127.0.0.1:1111

Site displays immediately with clean, minimal styling.

Future Enhancements (Not in this PR)

Potential additions for future consideration:

  • Optional --minimal flag to skip theme generation
  • Sample blog post with taxonomies
  • Dark mode support via CSS variables
  • Additional template examples

Related Discussion

- Introduced .gitignore, README.md, and initial content files.
- Added base, index, page, and section templates for rendering.
- Included a default style.css for basic styling.
- Updated tests to verify the creation of new files and directories.
@nooscraft nooscraft marked this pull request as draft April 10, 2026 06:05
@nooscraft nooscraft changed the base branch from master to next April 10, 2026 06:13
@nooscraft nooscraft marked this pull request as ready for review April 10, 2026 06:15
- Replaced hardcoded content in init.rs with includes for default theme files.
- Added .gitignore, README.md, and initial content files for the default theme.
- Introduced base, index, page, and section templates for rendering.
- Included a default style.css for basic styling.
@nooscraft nooscraft requested a review from Keats April 10, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improving zola init - thoughts?

2 participants