Using Smart Optimization

Smart Optimization automatically optimizes your website's HTML, CSS, JavaScript, and SVG files before they're delivered to visitors. There's no build step to configure and nothing to install. It's enabled by default for all Synaps Media websites, on all plans, at no additional cost.

Why Smart Optimization exists

Ghost's built-in Theme Editor lets you edit theme files directly from Ghost Admin, without uploading a new theme archive for every change.

Most modern themes, however, are distributed with prebuilt CSS and JavaScript files. Theme developers typically write their code as multiple, readable source files, then run a build process that combines and minifies them into smaller files optimized for delivery. This keeps the codebase organized during development while keeping the live website fast.

The Theme Editor doesn't have a build step of its own. If your theme relies on prebuilt files, editing them directly in Ghost Admin means working with minified, hard-to-read code, and there's no way to regenerate the optimized version afterward.

With Smart Optimization, that build step is no longer necessary. You can include your readable source CSS and JavaScript files directly in your theme. Synaps Media optimizes them on the fly when the site is served, so you always get the benefits of minified output, smaller file sizes, fewer exposed comments, faster downloads, without giving up the ability to edit source files directly in Ghost Admin.

The same applies to Code Injection: any inline CSS or JavaScript you add through Ghost's Code Injection feature is optimized as well, even though it's written and stored as plain, unminified code.

What gets optimized

Smart Optimization processes four types of content:

HTML responses are optimized by removing unnecessary whitespace and comments, including inline <style> and <script> blocks and Code Injection output.

CSS files (and inline styles) are minified: whitespace, comments, and redundant syntax are removed.

JavaScript files (and inline scripts) are minified: whitespace and comments are removed, and code may be restructured for smaller output.

SVG files are optimized by removing metadata, comments, and unnecessary attributes added by design tools, without affecting how the image renders.

All minifications are configured with safe parameters to not break any codes.

Configuration

Smart Optimization is enabled by default and requires no setup.

To review or change its settings, go to Advanced Settings → Smart Optimization in your management panel. From there, you can toggle optimization independently for:

• HTML optimization
• CSS optimization
• JavaScript optimization
• SVG optimization

Disabling an individual option only affects that file type; the others continue to be optimized normally. Disabling Smart Optimization entirely turns off all four.

Best practices

These tips help you get the most out of Smart Optimization and keep your theme easy to maintain.

Prefer Code Injection over editing Theme source files

Even though this feature enables to edit theme CSS and JS source files, we suggest to use Ghost's Code Injection to make style or JS tunings. This way, you can take advantage of updating your themes easily when your theme provider releases new versions. But if your changes are large, then it's better to create new CSS/JS files in your theme, and include them to your templates with asset helper.

Use Ghost's asset helper for theme files

When linking CSS or JavaScript files in your theme, use Ghost's built-in asset helper rather than hardcoding the path:

<link rel="stylesheet" href="{{asset "css/style.css"}}">
<script src="{{asset "js/app.js"}}"></script>

The asset helper automatically appends a cache-busting query string based on your theme's version. Without it, visitors' browsers may continue serving an old, cached copy of your CSS or JavaScript after you make changes, since the file's URL doesn't change. The asset helper ensures the URL changes whenever your theme is updated, so visitors always receive the latest version without needing to clear their cache manually.

Avoid relying on the global scope in JavaScript

When writing custom JavaScript, wrap your code in a function rather than declaring variables and functions directly in the global scope:

javascript

(function () {
  const button = document.querySelector('.my-button');
  // ...
})();

This prevents naming collisions with other scripts on the page (including those added by Ghost, your theme, or third-party integrations), and makes minification more effective, since variables scoped to a function can be safely renamed by the optimizer. Variables declared globally cannot be renamed, as doing so could break other scripts that depend on them.

Write minification-friendly code

A few habits make your CSS and JavaScript easier to optimize and keep behavior predictable after minification:

Declare variables with const or let instead of var, and avoid relying on function or variable hoisting. This keeps scope predictable and avoids subtle issues that can arise when code is reorganized during minification.

Avoid using string-based dynamic property or selector access that depends on a variable's original name, such as referencing window['myVariableName']. Minifiers may rename local variables for efficiency, and code that depends on matching exact names as strings can break.

Keep CSS selectors and class names meaningful but concise. Smart Optimization removes whitespace and comments but does not rename CSS classes or HTML elements, so overly long, repetitive class names still add to file size.

Questions