How to Add custom settings to a ghost theme

Ghost recently shipped a new feature called custom settings. With these custom settings, you can define site-wide/homepage/post settings.

What is Custom Settings?

Custom theme settings are a powerful tool that allows you to configure custom settings that appear in Ghost Admin — making it easy for you to make stylistic choices without needing to edit theme files.

Supported Settings Type

select
boolean
color
image
text

How to define these settings?

You need to define these settings on package.json file under config key.

{
    "config": {
        "custom": {
            "primary_font": {
                "type": "select",
                "options": ["Modern sans-serif", "Elegant serif"],
                "default": "Modern sans-serif"
            },
            "cta_text": {
                "type": "text",
                "default": "Sign up for more like this",
            },
            "cta_image": {
                "type": "image"
            },
            "enable_comments": {
            	"type": "boolean"
                "default": "true"
            },
            "secondary_color": {
            	"type": "color"
            }
        }
    }
}

Above is an example of some custom settings. After defining the settings you have to upload the theme again manually or with Github Action.

How to call the defined settings in the frontend?

For Example, you have defined a custom CTA text & you can call the custom setting for setting using the below method.

{{#if @custom.cta_text}}
    <p class="cta-text">
    	{{@custom.cta_text}}
    </p>
{{/if}}

You can also use Else Statement.

{{#if @custom.cta_text}}
    <p class="cta-text">
    	{{@custom.cta_text}}
    </p>
{{else}}
	{{@site.description}}
{{/if}}

For boolean:

{{#if @custom.enable_comments}}
    <div class="comments">
    	{{!-- Comment Script or js to load the only when the comment is enables ---}}
        <script src="path/to/script.js"></script>
        {{> "comments"}}
    </div>
{{/if}}

For Color:

{{#if @custom.secondary_color}}
    <style>
    	:root {
            --secondary_color: {{@custom.secondary_color}}
        }
    </style>
{{/if}}

For Select, we can use the match helper.

<body class="{{body_class}} {{#match @custom.primary_font "Modern sans-serif"}}font-primary{{/match}}">
	....
</body>

Hopefully, you find this helpful.