Code Injection Variables

Code Injection variables — what they do and how to use them

These variables are read by Crimson at runtime to decide how your site behaves (external links, image light-box, header behavior, theme mode, pagination, contact/social visibility, etc.).

You can change them anytime from Ghost Admin → Settings → Advanced → Code Injection → Site Header, then Change the variable value, click Save and refresh your site.

Adding these variables is already explained in the previous section - Code Injection.

How to edit safely?

Change one variable at a time.
Save in Ghost Admin.
Hard refresh your site (Ctrl/Cmd + Shift + R).
If required, clear your cache.
Confirm the change worked, then move to the next variable.

Code injection variables explained

Variable

What it controls

Allowed values

Default

GHOST_CONTENT_API_KEY

Features that depend on fetching posts/tags/authors will work properly. If missing/invalid, pagination on Authors and Tags pages will not work.

A valid Content API key string

GHOST_API_URL (optional)

Fixes API calls in special setups (Ghost(Pro) domain differences, staging domains, etc.). If set wrong, API calls can fail.

Full URL string

OPEN_LINKS_IN_NEW_TAB

Opens external links in a new browser tab. true: external links open in a new tab. false: open in the same tab.

true / false

true

ENABLE_IMAGE_LIGHTBOX

Enables click-to-zoom image light-box popup. true: clicking images opens a light-box. false: images behave normally (no popup).

true / false

true

AUTO_HIDE_HEADER

Auto-hides the header while scrolling down, shows it when scrolling up. true: more reading space while scrolling. false: header stays visible.

true / false

true

DEFAULT_COLOR_SCHEME

Sets the site’s default color scheme selection. light: always light. dark: always dark. system: matches user device setting.

'light' / 'dark' / 'system'

'system'

REDIRECT_ON_LOCALE

Redirects visitors to the site version matching their browser language (only if your site is set up for multilingual/locale routing). true: visitors may be redirected to a language-specific version of your site. false: no locale redirects.

true / false

false

PAGINATION_STYLE

How Crimson loads additional content on paginated feeds. load-more: button loads more posts without changing page. paginated-pages: classic page numbers/next page style. (Authors/Tags will always use Load More)

'load-more' / 'paginated-pages'

'load-more'

CONTACT_ENDPOINT

Shows/hides the Contact form and defines where form submissions are sent. Empty: contact form hidden. URL provided: contact form appears and submits to that endpoint.

URL string or empty string

'' (hidden)

YOUTUBE_LINK

Shows/hides YouTube link on Contact page. Empty: YouTube row hidden. URL: YouTube row shown and points to your URL.

URL string or empty string

'' (hidden)

INSTAGRAM_LINK

Shows/hides Instagram link on Contact page. Empty: Instagram row hidden. URL: Instagram row shown and points to your URL.

URL string or empty string

'' (hidden)

WHATSAPP_LINK

Shows/hides Whatsapp link on Contact page. Empty: Whatsapp row hidden. URL: Whatsapp row shown and points to your URL.

URL string or empty string

'' (hidden)

TIKTOK_LINK

Shows/hides TikTok link on Contact page. Empty: TikTok row hidden. URL: TikTok row shown and points to your URL.

URL string or empty string

'' (hidden)

THREADS_LINK

Shows/hides Threads link on Contact page. Empty: Threads row hidden. URL: Threads row shown and points to your URL.

URL string or empty string

'' (hidden)

LINKEDIN_LINK

Shows/hides LinkedIn link on Contact page. Empty: LinkedIn row hidden. URL: LinkedIn row shown and points to your URL.

URL string or empty string

'' (hidden)

Best Practices

1) Always edit in Site Header, not Footer

Because Crimson needs the variables available before theme JS loads.

Rule of thumb

Variables/config → Site Header
Tracking scripts → usually OK in Header or Footer depending on provider

2) Treat Code Injection like “configuration”

Keep it clean and minimal.

Recommended structure

One <script> block for API vars
One <script> block for window.GLOBAL

Avoid adding unrelated scripts in between unless you know they won’t overwrite window.GLOBAL.

3) Change one thing at a time

This makes debugging easy.

Workflow

Change 1 variable
Save
Hard refresh
Validate visually + console

4) Keep defaults unless you have a reason

Defaults are chosen to fit most sites:

Open external links in a new tab (usually better UX)
Light-box on (visual polish)
Auto-hide header (modern reading experience)
System theme (best for accessibility and user preference)

5) Use correct data types (this prevents 80% of errors)

Booleans: true, false (no quotes)
Strings: 'system', 'load-more', URLs (quotes required)

Correct:

AUTO_HIDE_HEADER: true,
DEFAULT_COLOR_SCHEME: 'system',
CONTACT_ENDPOINT: 'https://example.com/api/contact',

Incorrect:

AUTO_HIDE_HEADER: 'true',
DEFAULT_COLOR_SCHEME: system,
CONTACT_ENDPOINT: https://example.com/api/contact,

6) Use real, secure URLs for endpoints

If you enable a contact endpoint:

Prefer https:// .
Ensure CORS is configured if your endpoint is on a different domain.
Make sure your endpoint returns clear success/error responses (so you can debug easily).

Tip: If your endpoint is not ready yet, keep:

CONTACT_ENDPOINT: '' (form stays hidden)

7) Don’t expose Admin API keys (ever)

Only use Content API key in the browser. Keep Admin API keys server-side only.

8) Version-control your “settings”

When you find a configuration you like, copy it into a safe place:

A private Git repo / notes / password manager secure note

Why?

Easy recovery if someone edits Code Injection incorrectly
Easy migration from staging → production

9) If something conflicts, prefer one source of truth

If you also have custom scripts that define window.GLOBAL, you can get unpredictable results.

Best practice

Define window.GLOBAL only once in Site Header.
If you must manipulate it later, do:

window.GLOBAL = window.GLOBAL || {};
window.GLOBAL.AUTO_HIDE_HEADER = false;

Troubleshooting

1) “I updated variables, but nothing changed”

Most common causes: caching + not refreshing properly.

Fix checklist

In Ghost Admin, confirm you clicked Save in Code Injection.
Do a hard refresh: Ctrl/Cmd + Shift + R.
Test in an Incognito/Private window.
If you use a CDN (Cloudflare/Bunny/host caching), purge cache.
If you recently updated the theme, clear any server-level cache (if applicable).

Quick verification

Right-click → View Page Source
Search for: window.GLOBAL and GHOST_CONTENT_API_KEY
If you don’t see them, they’re not being injected (wrong box, not saved, or cached HTML).

2) “My site looks broken / white screen / header missing after adding the snippet”

This almost always happens due to a JavaScript syntax error.

What to check

You must have:
- matching { and }
- matching quotes '...'
- commas between properties (except after the last property)
Don’t paste “smart quotes” from editors: use normal ' or ".

Fast debug

Open DevTools → Console
Look for errors like:
- Uncaught SyntaxError: Unexpected token
- Uncaught ReferenceError

Recovery tip

Temporarily remove the whole window.GLOBAL block, Save, refresh.
Then add it back and edit one line at a time.

3) “DevTools says `window.GLOBAL` is undefined”

Possible reasons:

You pasted into Site Footer instead of Site Header
A caching layer is serving old HTML
Another script on your site overwrote window.GLOBAL

Fix

Move snippet to Site Header, Save, hard refresh.
In DevTools console, run:
- window.GLOBAL
- window.GHOST_CONTENT_API_KEY
If window.GLOBAL exists but values don’t match, another script may be overwriting it. Place your snippet as high as possible in Site Header.

4) “Content API features aren’t working / sections are empty”

This typically points to API URL / key issues.

Symptoms

“Load more” doesn’t load posts
Tag-based sections show nothing
Console/network shows failed requests
Authors and Tags page cannot load more authors/tags

Fix checklist

Confirm window.GHOST_CONTENT_API_KEY is correct (copied from the Custom Integration).
Check DevTools → Network tab:
- Do you see requests to /ghost/api/content/… ?
- Are they returning 200 or errors like 401/403/404?
If requests fail due to domain mismatch, set:
- window.GHOST_API_URL = 'https://YOUR_API_DOMAIN' Use the API URL/domain shown in Ghost Integration (best source of truth).

Common mistakes

Using the wrong key
Key pasted with extra spaces/quotes accidentally
Setting a wrong GHOST_API_URL domain/protocol

5) “External links still aren’t opening in a new tab”

Check these first

Is the link actually “external”? (external themes have different root domains.)
Is your value a boolean (not a string)?
- ✅ OPEN_LINKS_IN_NEW_TAB: true
- ❌ OPEN_LINKS_IN_NEW_TAB: 'true'

Test

Put an obvious external link in a post and re-test.

6) “Light-box doesn’t open on images”

Possible reasons

ENABLE_IMAGE_LIGHTBOX is false
The image is wrapped in a custom HTML link that prevents the theme handler

Fix

Set ENABLE_IMAGE_LIGHTBOX: true
Test on a standard image inserted via the Ghost editor (not custom HTML).

7) “Header is behaving weird / flickering / not hiding”

Possible reasons

Conflicting custom scripts affecting scroll
Very heavy pages causing scroll handler jitter
You set AUTO_HIDE_HEADER: true and have a sticky announcement bar/plugin

Fix

Try AUTO_HIDE_HEADER: false to confirm the issue is the scroll behavior.
Remove/disable other scroll-related scripts (if any).

8) “Color scheme isn’t respecting my setting”

Check

DEFAULT_COLOR_SCHEME must be one of:
- 'light', 'dark', 'system'
If you set 'system', the site will follow the OS/browser theme.

Tip

Test quickly by switching your OS theme or browser theme override.

9) “REDIRECT_ON_LOCALE is on, but nothing happens”

Locale redirect works only if your site is actually configured for locale-based URLs/routing.

Fix

Confirm your multilingual/locale setup is implemented (routes + languages).
If you don’t have a locale structure, keep this false.

10) “Pagination style didn’t change”

Important note

PAGINATION_STYLE only affects post feeds that are paginated.
Authors/Tags pages will always use Load More

So if you tested on Authors/Tags pages, you may not see any change.

11) “Contact form isn’t visible”

Crimson hides the contact form when no endpoint is provided.

Fix

Set a valid endpoint:
- CONTACT_ENDPOINT: 'https://formhandler.com/api/abc123xyz'
Ensure it’s https:// and accessible publicly.
If it still doesn’t show, check console for blocked requests or mixed content.

These are intentionally hidden when empty.

Fix

Add the link as a full URL string.
Example:
- LINKEDIN_LINK: 'https://linkedin.com/in/yourhandle'

PreviousCode Injection NextOverview

Last updated 12 days ago

hashtagCode Injection variables — what they do and how to use them

hashtagHow to edit safely?

hashtagCode injection variables explained

hashtagBest Practices

hashtag1) Always edit in Site Header, not Footer

hashtag2) Treat Code Injection like “configuration”

hashtag3) Change one thing at a time

hashtag4) Keep defaults unless you have a reason

hashtag5) Use correct data types (this prevents 80% of errors)

hashtag6) Use real, secure URLs for endpoints

hashtag7) Don’t expose Admin API keys (ever)

hashtag8) Version-control your “settings”

hashtag9) If something conflicts, prefer one source of truth

hashtagTroubleshooting

hashtag1) “I updated variables, but nothing changed”

hashtag2) “My site looks broken / white screen / header missing after adding the snippet”

hashtag3) “DevTools says window.GLOBAL is undefined”

hashtag4) “Content API features aren’t working / sections are empty”

hashtag5) “External links still aren’t opening in a new tab”

hashtag6) “Light-box doesn’t open on images”

hashtag7) “Header is behaving weird / flickering / not hiding”

hashtag8) “Color scheme isn’t respecting my setting”

hashtag9) “REDIRECT_ON_LOCALE is on, but nothing happens”

hashtag10) “Pagination style didn’t change”

hashtag11) “Contact form isn’t visible”

hashtag12) “My social links aren’t showing on Contact page”

Code Injection variables — what they do and how to use them

How to edit safely?

Code injection variables explained

Best Practices

1) Always edit in Site Header, not Footer

2) Treat Code Injection like “configuration”

3) Change one thing at a time

4) Keep defaults unless you have a reason

5) Use correct data types (this prevents 80% of errors)

6) Use real, secure URLs for endpoints

7) Don’t expose Admin API keys (ever)

8) Version-control your “settings”

9) If something conflicts, prefer one source of truth

Troubleshooting

1) “I updated variables, but nothing changed”

2) “My site looks broken / white screen / header missing after adding the snippet”

3) “DevTools says `window.GLOBAL` is undefined”

4) “Content API features aren’t working / sections are empty”

5) “External links still aren’t opening in a new tab”

6) “Light-box doesn’t open on images”

7) “Header is behaving weird / flickering / not hiding”

8) “Color scheme isn’t respecting my setting”

9) “REDIRECT_ON_LOCALE is on, but nothing happens”

10) “Pagination style didn’t change”

11) “Contact form isn’t visible”

12) “My social links aren’t showing on Contact page”