Development of Custom Theme for October CMS
October CMS themes are sets of .htm files with PHP/Twig markup. Each file contains an ini section with metadata, component PHP code and HTML template. Layout is completely under developer control.
Theme Structure
themes/mytheme/
├── theme.yaml # theme metadata
├── layouts/
│ ├── default.htm # base layout
│ └── minimal.htm # for landing pages
├── pages/
│ ├── index.htm # home page
│ ├── about.htm
│ ├── blog.htm
│ └── blog-post.htm
├── partials/
│ ├── header.htm
│ ├── footer.htm
│ ├── nav.htm
│ ├── blog/
│ │ ├── post-card.htm
│ │ └── post-list.htm
│ └── forms/
│ └── contact.htm
└── assets/
├── css/
├── js/
└── images/
# theme.yaml
name: My Theme
description: Corporate theme for My Site
author: My Company
homepage: https://mycompany.com
code: mytheme
form:
fields:
primary_color:
label: Primary Color
type: colorpicker
default: '#1a56db'
logo:
label: Site Logo
type: mediafinder
mode: image
Layout File
description = "Default Layout"
==
<!DOCTYPE html>
<html lang="{{ this.site.locale ?? 'en' }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>
{% if this.page.meta_title %}
{{ this.page.meta_title }} | {{ this.site.name }}
{% else %}
{{ this.page.title }} | {{ this.site.name }}
{% endif %}
</title>
<meta name="description" content="{{ this.page.meta_description }}">
{% styles %}
<link rel="stylesheet" href="{{ 'assets/css/app.css' | theme }}">
</head>
<body class="{{ this.page.layout_class }}">
{% partial 'header' %}
<main id="main">
{% page %}
</main>
{% partial 'footer' %}
{% scripts %}
<script src="{{ 'assets/js/app.js' | theme }}" defer></script>
</body>
</html>
Page with Components
title = "Blog"
url = "/blog/:page?"
layout = "default"
is_hidden = 0
[blogPosts]
postsPerPage = 12
sortOrder = "published_at desc"
[blogCategories]
slug = "{{ :slug }}"
==
{% set currentPage = this.param.page ?? 1 %}
<section class="blog-header">
<h1>{{ this.page.title }}</h1>
</section>
<section class="blog-content">
<div class="posts-grid">
{% for post in blogPosts %}
{% partial 'blog/post-card' post=post %}
{% endfor %}
</div>
<aside class="sidebar">
<h3>Categories</h3>
<ul>
{% for cat in blogCategories %}
<li><a href="{{ cat.url }}">{{ cat.name }} ({{ cat.posts_count }})</a></li>
{% endfor %}
</ul>
</aside>
</section>
Vite Integration
npm install vite laravel-vite-plugin
// vite.config.ts
import { defineConfig } from 'vite';
import { octobercmsTheme } from 'vite-plugin-october-cms-theme';
export default defineConfig({
plugins: [
octobercmsTheme({ themePath: 'themes/mytheme' }),
],
build: {
outDir: 'themes/mytheme/assets/build',
manifest: true,
},
});
Theme Settings in Template
Fields from theme.yaml are available via this.theme:
<style>
:root {
--color-primary: {{ this.theme.primary_color ?? '#1a56db' }};
}
</style>
{% if this.theme.logo %}
<img src="{{ this.theme.logo }}" alt="{{ site.name }}">
{% else %}
<span class="text-logo">{{ site.name }}</span>
{% endif %}
Development of a corporate website theme takes 5–10 working days.