Documentation / Theming / Theme Structure

Theme Structure

📅 Updated: May 26, 2025

👤 Author: LebCit

⏱️ Reading time:

On this page

An Aether theme is a directory containing template files and assets. Let's explore the required and optional components.

Required Files

For a valid Aether theme, you must include these three files:

File	Purpose
`theme.json`	Contains theme metadata and configuration
`templates/layout.html`	Main template for the entire site
`assets/css/style.css`	Main stylesheet for the theme

Recommended Directory Structure

my-theme/
├── theme.json              # Theme metadata (required)
├── screenshot.png          # Theme screenshot
├── templates/              # Default templates directory
│   ├── layout.html         # Main layout (required)
│   ├── content.html        # Generic content template
│   ├── post.html           # Blog post template
│   ├── page.html           # Standard page template
│   └── taxonomy.html       # Category/tag archives template
├── custom/                 # Custom page templates
│   ├── homepage.html       # Homepage template
│   ├── about.html          # About page template
│   ├── category.html       # Category listing template
│   └── tag.html            # Tag listing template
├── partials/               # Reusable components
│   ├── head.html           # <head> content
│   ├── header.html         # Site header
│   ├── footer.html         # Site footer
│   └── sidebar.html        # Sidebar content
└── assets/                 # Theme assets
    ├── css/
    │   ├── style.css       # Main stylesheet (required)
    │   └── custom.css      # Additional styles
    ├── js/
    │   └── theme.js        # Theme JavaScript
    └── images/
        └── logo.svg        # Theme logo

Aether's flexibility makes theme structure possibilities virtually limitless — only three directories and three files are required in the theme folder, as described above:

theme.json: Contains theme metadata and configuration
templates/layout.html: Base layout template
assets/css/style.css: Main stylesheet

Theme JSON File

The theme.json file defines metadata for your theme. Here's a detailed real-world example:

{
    "title": "Modern Blog Theme",
    "description": "A clean and modern blog theme with dark mode support",
    "version": "1.1.0",
    "author": "John Doe",
    "authorUrl": "https://johndoe.com",
    "tags": ["blog", "modern", "dark-mode", "responsive"],
    "license": "GPL-3.0-or-later",
    "features": [
        "Dark/Light mode toggle",
        "Responsive design",
        "SEO optimized",
        "Social media integration",
        "Custom widgets"
    ],
    "screenshot": "screenshot.png",
    "changelog": {
        "1.0.0": [
            "Initial release",
            "Basic blog functionality",
            "Responsive design",
            "Custom header and footer",
            "Widget support"
        ]
    },
    "releases": {
        "1.0.0": {
            "date": "2024-12-01",
            "type": "major",
            "highlights": ["Initial stable release"],
            "breakingChanges": false,
            "migrationRequired": false
        }
    }
}

Required Fields

Field	Description	Type	Example	Default Value
`title`	Theme name	String	`"My Awesome Theme"`	(no default)
`description`	Brief description	String	`"A responsive and feature-rich theme"`	(no default)
`version`	Version in X.Y.Z format	String	`"1.0.0"`	(no default)
`author`	Theme author	String	`"Your Name"`	(no default)
`authorUrl`	Author's website (HTTPS URL)	String	`"https://example.com"`	`""`
`tags`	Theme categories/features	Array of strings	`["responsive", "blog"]`	`[]`
`license`	Must be "GPL-3.0-or-later"	String	`"GPL-3.0-or-later"`	(no default)
`features`	Supported theme features	Array of strings	`["custom-header", "widgets"]`	`[]`
`screenshot`	Theme screenshot filename	String	`"screenshot.png"`	`""`

Optional Fields

Field	Description	Type	Example
`colors`	Theme color palette	Array of strings	`["#ffffff", "#000000"]`
`changelog`	Map of version numbers to lists of changes	Object	`{ "1.0.0": ["Initial release", "Basic functionality"] }`
`releases`	Detailed release metadata keyed by version	Object	`{ "1.0.0": { "date": "...", "type": "...", "breakingChanges": false }}`

Notes

Fields marked with "no default" are required and must be provided explicitly.
authorUrl and screenshot allow empty strings ("") if no value is available.
tags and features are required but can be empty arrays ([]) if no applicable items exist.
Optional fields such as colors, changelog, and releases can be omitted, but must follow their expected structure if included.
The changelog field is strongly recommended as a best practice. It allows users to preview changes before installing updates and helps communicate what’s new, fixed, or improved.
The releases field provides detailed metadata for each version. It can enhance developer tools and version management but is not required.

Theme Validation

The system validates the theme.json file according to the following rules:

🔸 Required Field Rules

title, description, and author must be non-empty strings.
version must follow Semantic Versioning in the format X.Y.Z (e.g., "1.0.0").
license must be the exact string "GPL-3.0-or-later".
tags and features must be arrays of strings; empty arrays ([]) are allowed.
screenshot must be:
- A string (filename only),
- With an extension in one of the allowed image formats: .jpg, .jpeg, .png, .webp, .avif, .svg.
- An empty string ("") is allowed if no screenshot is provided.

🔹 Optional Field Rules

authorUrl is optional, but if provided, it must be a valid HTTPS URL (e.g., "https://example.com"). An empty string is allowed.
colors is optional. If present:
- It must be an array of strings (each representing a color, typically hex codes or CSS color names),
- Empty arrays ([]) are valid.
changelog is optional, but recommended. If included:
- It must be an object mapping version numbers (X.Y.Z) to arrays of change descriptions (strings).
releases is optional. If included:
- It must be an object where each key is a version (X.Y.Z),
- Each version entry must be an object with the following structure:
  - date: ISO 8601 date string (YYYY-MM-DD),
  - type: One of "major", "minor", or "patch",
  - highlights: Array of strings summarizing the update,
  - breakingChanges: Boolean (true or false),
  - migrationRequired: Boolean (true or false).

Changelog Best Practices

A changelog allows users and developers to see what changed in each release of your theme—what’s new, what’s fixed, and what might break. While optional in theme.json, including a changelog is strongly recommended.

Changelog Format

Use the following structure within your theme.json file:

"changelog": {
  "version": ["change description", ...]
}

Example

"changelog": {
  "2.1.0": [
    "Added: New template for product archives",
    "Improved: Page loading speed by 30%",
    "Fixed: Cart widget display on mobile devices",
    "Changed: Updated color scheme for better contrast"
  ],
  "2.0.0": [
    "Removed: Legacy checkout flow",
    "Added: Redesigned checkout experience",
    "Changed: Order summary layout for mobile"
  ]
}

ℹ️

Note: Each key is a version number (X.Y.Z), and its value is an array of changes introduced in that release.

Entry Structure Guidelines

When writing changelog entries, follow these rules to ensure clarity and consistency:

Use Semantic Versioning (MAJOR.MINOR.PATCH)
List versions from newest to oldest
Use action verbs (e.g., Added, Fixed, Removed) at the start of each entry
Be concise and specific
Avoid vague entries like "Misc fixes" or "Updated stuff"
Group similar types of changes together

Semantic Versioning

Changelog entries should correspond to versions formatted using the Semantic Versioning specification:

Level	Format	Use When...
MAJOR	`2.0.0`	Incompatible or breaking changes
MINOR	`1.1.0`	Backward-compatible features or enhancements
PATCH	`1.0.1`	Bug fixes or backward-compatible internal improvements

Example Progression

1.0.0   → Initial release
1.0.1   → Fixed: Layout bug in sidebar
1.1.0   → Added: Dark mode support
2.0.0   → Removed: Deprecated color utility classes (breaking)

Standard Change Types

Use one of these action types at the start of each changelog entry:

Type	Description
Added	New features or functionality
Changed	Modifications to existing behavior
Deprecated	Features scheduled for removal in a future release
Removed	Features or APIs that were removed
Fixed	Bug fixes or error corrections
Improved	Enhancements to performance, accessibility, or UX
Security	Vulnerability fixes or security updates

ℹ️

Note: Consistent use of these types improves readability and enables automated tools to parse changelogs.

Do & Don’t

✅ Clear Example	❌ Unclear Example
`Added: Support for dark/light toggle`	`Update theme`
`Fixed: Header alignment issue on Safari`	`Bug fix`
`Removed: Deprecated Google Fonts support`	`Cleanup`
`Improved: Load time on category pages`	`Performance improvements`

Tools

To streamline changelog generation, you can use commit-based tools like:

standard-version
auto-changelog
Conventional Commits (format guidelines)

These tools automatically generate changelogs from commit history, enforce structure, and help maintain consistency.

Why Use Changelogs?

Help users preview changes before upgrading
Document project history and evolution
Improve collaboration between team members
Assist with debugging and regression tracking

Including a changelog in your theme improves transparency, encourages adoption, and makes maintenance easier for everyone.

Template Inheritance and Resolution →