Introduction
The following documentation serves as your guide to the new theme. Since this is Ghost theme documentation, it is assumed that you have a basic knowledge of the Ghost.
If you’re new to Ghost, it’s recommended to explore the guides in the official Ghost Help Center. Checking these resources will provide you with all the available information.
Uploading a theme
This is where the magic happens! You are able to upload, activate and delete a theme in the Ghost Admin of your publication.
Step-by-Step
- To upload a theme, go to the 'Design & branding' settings in the Ghost Admin and click 'Change theme' in the bottom right corner.
- Then click the 'Upload theme' button in the upper right corner.
- Once uploaded, click 'Activate' to activate the theme on your site.
Dark & sepia version
The dark or sepia version introduces a fresh and distinctive appearance for your website, bringing a modern and stylish aesthetic that enhances the visual experience for your visitors.
Step-by-Step
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Color scheme' position.
- Use the dropdown menu to select your option.
- Finally, click 'Save' to activate.
Tip: Dark & sepia version depending on operating system preferences
Modern operating systems (Windows, macOS, iOS, etc.) allow users to choose their preference for light or dark system themes. The below feature is used to detect if the user has requested the system to use a light or dark color theme.
- To activate an auto dark version based on user operating system preferences, select the 'Auto' option.
- Click 'Save' to activate.
Search function
By default, the theme uses a native search option. You can also use the search function specially designed for this theme — to do this, you must set the Content API key.
Step 1: Generating Content API key
- To generate 'Content API key', go to the 'Integrations' settings in the Ghost Admin.
- Click 'Add custom integration', then give the new integration a name, like 'Search', and click the 'Add' button.
- Copy your 'Content API key' and click 'Save & close'.
Step 2: Activate the search function
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Content API key for search' position.
- Paste your 'Content API key'.
- Finally, click 'Save' to activate.
Featured section
Select which posts and pages you want to featured in your publication.
Step-by-Step
- Open the post you would like to add to the featured section.
- Then, go to the 'Post/Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel, you'll find a switch labeled 'Feature this post/page.'
- Click the switch and close the panel.
Tip: How to remove featured posts from the main collection? (For advanced users)
- Go to the 'Labs' settings in the Ghost Admin, click on 'Beta features' tab and you will find the 'Routes' section.
- Upload the
routes.yaml
file with these settings:
Authors page
To present all authors from your publication in an elegant way, you can add a custom authors page.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Authors' template, close the panel.
- Finally, click 'Publish'.
Tags page
To present all tags from your publication in an elegant way, you can add a custom tags page.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Tags' template, close the panel.
- Finally, click 'Publish'.
Contact page
If you wish to have a direct way in which your readers can contact you, you can add a contact page based on Formspree or Getform.
Step 1: Add your Formspree or Getform endpoint
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Contact form endpoint' position.
- Paste your Formspree or Getform endpoint, e.g.
https://formspree.io/f/xhyplkej
- Finally, click Save to activate.
Step 2: Add a contact page
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Contact' template, close the panel.
- Finally, click 'Publish'.
Logo
A publication logo is the primary logo for your brand and is displayed across your theme.
Step-by-Step
- To upload a logo, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Brand' – expand this settings list and go to the 'Publication logo' position.
- Click 'Upload logo' to upload your logo.
- Finally, click 'Save' to activate.
Tip: How to change logo size?
- To change logo size go to the 'Code injection' settings in the Ghost Admin and paste this code to the 'Site header':
- Adjust the current
<value>
to match the expected value, such as30px
- Finally, click 'Save' to activate.
Tip: Uploading an additional logo for dark color scheme
- To upload an additional logo, go to the 'Design & branding' settings in the Ghost Admin.
- On the right, you’ll see the 'Site-wide' tab – expand this settings list and go to the 'Color scheme' position – select the option related to dark color scheme to display the option to upload an additional logo below.
- Click 'Upload Image' to upload your logo.
- Finally, click 'Save' to activate.
Publication cover
A publication cover is an optional large background image that can be used with your publication.
Step-by-Step
- To upload a publication cover, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Brand' – expand this settings list and go to the 'Publication cover' position.
- Click 'Upload cover' to upload your image.
- Finally, click 'Save' to activate.
Tip: Publication cover only on the homepage
By default, the publication cover is displayed on all pages. If you want to show the publication cover only on the homepage, change the 'Publication cover only on homepage' setting in the Ghost Admin.
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Publication cover only on homepage' position.
- Use the switch to activate the option.
- Finally, click 'Save' to activate.
Accent color
Primary color used in your publication.
Step-by-Step
- To change the accent color in your publication, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Brand' – expand this settings list and go to the 'Accent color' position.
- Choose your color.
- Finally, click 'Save' to activate.
Accent color buttons
By default, the buttons (e.g 'Load more') in the theme are in accent color. You can change in to black – with the accent color when hovering the mouse.
Step-by-Step
- To deactivate accent color buttons in your publication, go to the 'Design & branding' in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Accent color buttons' position.
- Use the switch to deactivate the option.
- Finally, click 'Save' to activate.
Fonts
You can change fonts using the 'Typography' setting in the 'Design & branding' section.
Using this option might not always give the best results because fonts are designed for different purposes and can vary in size. The theme doesn’t affect the list of available fonts or adjust them, so it’s a good idea to experiment and find what works best for your needs.
Step-by-Step
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right, you’ll see the 'Brand' tab and find the 'Typography' section.
- Use the dropdown menu to select your option.
- Finally, click 'Save' to activate.
Hero section
The hero section includes a title, subscription form or search box at the top of the homepage.
Tip: How to add your own hero title?
- To add your own hero title, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Homepage' – expand this settings list and go to the 'Hero title text' position.
- Enter your own hero title.
If you want to use italic text, use the <span>
... </span>
tag, like this:
<span>This is text in italics</span> and this one doesn't.
- Finally, click 'Save' to activate.
Tip: How to add description?
- To add description to hero section, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Brand' – expand this settings list and go to the 'Site description' position.
- Enter your own description.
- Finally, click 'Save' to activate.
Tip: How to change the subscription button link?
- To add your own link, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Brand' – expand this settings list and go to the 'Become a subscriber url slug' position.
- Enter your own slug, for example
/membership/
. - Finally, click 'Save' to activate.
Special section
You have the option to add a special section with posts on the homepage, below the 'Load more' button.
By default, the section located on the homepage displays related posts to the most recent post if it has a 'primary tag' added.
Tip: How to add a special section with posts for selected tag?
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Homepage' – expand this settings list and go to the 'Tag for special section' position.
- Enter your tag slug, e.g.
lifestyle
Hide author
Decide whether you want to display the author in the feed and on the post page.
Step-by-Step
- To hide the author, go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Site-wide' – expand this settings list and go to the 'Show author' position.
- Use the toggle switch.
- Finally, click 'Save' to activate.
Post header layouts
The theme includes a collection of post header layouts, allowing you to customize text and images in relation to each other.
Templates only work when a featured image is added.
Activate 'Background Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Background Image' template, close the panel.
- Finally, click 'Publish'.
Activate 'Box Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Box Image' template, close the panel.
- Finally, click 'Publish'.
Activate 'Box With Background Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Box With Background Image' template, close the panel.
- Finally, click 'Publish'.
Activate 'Default With Background Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Default With Background' Image template, close the panel.
- Finally, click 'Publish'.
Activate 'Full Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Full Image' template, close the panel.
- Finally, click 'Publish'.
Activate 'Full With Background Image' template (example)
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Post Full With Background Image' template, close the panel.
- Finally, click 'Publish'.
Post title: 'italic' style
Ghost, unfortunately, does not natively support italicizing titles. However, you can achieve this by adding a simple JavaScript code to the post or page.
The javascript code is done on client-side with the use of browser (not the server-side), so it is possible that you’ll see a quick conversion to italic text. This is called FOUT (Flash of Unstyled Text) and unfortunately that can’t be changed.
Step-by-Step
- Open the 'Post settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a item titled 'Code injection'.
- Then, paste this code to the 'Post footer':
<script>
var newTitle=document.getElementById('post-title');
newTitle&&(newTitle.innerHTML="This is <span>italics</span>")
</script>
When analyzing the provided code, make sure to insert your title between the quotation marks. Anything placed between the <span>
... </span>
tags will appear in italics. For example:
"This is <span>italics</span>"
- Close the panel and click 'Update', to activate.
Post-cards options
You can take advantage of several additional options for post-cards placed in the feed.
Top title for post-card
- To change the post-card size, just add an internal tag
#item-large
(tags which are prefixed by a#
character, are internal tags within Ghost) in 'Post settings' panel to the published post. - Click 'Update', to activate.
- The tag slug should be
hash-item-large
Large size for post-card
- To change the post-card size, just add an internal tag
#item-large
(tags which are prefixed by a#
character, are internal tags within Ghost) in 'Post settings' panel to the published post. - Click 'Update', to activate.
- The tag slug should be
hash-item-large
Responsive tables
The responsive table will display a horizontal scroll bar if the screen is too small to display the full content. The following description applies to the table added using the markdown card.
By default, the table adapts to the window width. If you have a table that is too wide, you can add a container <div class="responsive-table">
element with around the table, and it will display a horizontal scroll bar when needed.
Step-by-Step
- To add a responsive table, use the 'Markdown card'.
- Add a container
<div class="responsive-table">
element with around the table (in markdown there always needs to be a blank line between anyHTML
andmarkdown
).
Tip: What it takes to generate a table?
To generate a table, you can use the tool Markdown Tables Generator.
Custom pages
The members feature allows you to turn any site into a membership business with member signup, paid subscriptions and email newsletters.
The members feature is enabled by default. However, you need to create the following pages to avoid the 404 error.
Step-by-Step
- Create an Account page.
- Create Signup & Signin pages.
- Create a Membership page.
Tip: What to do in case of an 400 error with message e.g. 'Missing template members/signin.hbs for route /signin/'
The error indicates that there was previously used aroutes.yaml
file with another theme that required it. To solve the problem, reset theroutes.yaml
file to its default settings.
Login panel
The login panel is a navigation component that shows 'Sign in / Sign up' button when a member is logged out.
Tip: Replacing 'Sign up' with 'Membership' (Requires theme editing)
- You can easily replace the 'Sign up' page with 'Membership', for this purpose open
../partials/members/login_panel.hbs
file in your code editor and find:
<a href="{{@site.url}}/signup/" class="global-button">{{t "Sign up"}}</a>
- Then, replace with:
<a href="{{@site.url}}/membership/" class="global-button">Membership</a>
- Save your
login_panel.hbs
file in../partials/members/
folder.
Account page
The account page shows your members the type of account they’re having and gives them some subscription specific data.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- Provide the appropriate 'Page URL' as
/account/
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Account' template, close the panel.
- Finally, click 'Publish'.
Signup & Signin pages
The 'Signup' and 'Signin' pages are allowing your visitors to sign up to your site in order to access members only content.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- Provide the appropriate 'Page URL' as
/signin/
for the 'Signin' page and/signup/
for the 'Signup' page. - At the bottom of the panel, you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Signin' for the signin page and 'Signup' for the signup page.
- Finally, click 'Publish'.
Membership page
The 'Membership' page is helping your visitors to quickly visualize and compare the different pricing plans you offer.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Membership' template, close the panel.
- Finally, click 'Publish'.
Tip: How to add premium tier?
- Go to the 'Tiers' settings in the Ghost Admin.
- Click on the 'Connect with Stripe' and configure your Stripe account.
- If you have Stripe connected, click '+Add tier' – add your own tier name, description, monthly and yearly prices and list of benefits.
- Click 'Save & close'.
- Making tiers available to visitors – from the 'Portal settings', you can control which tiers appear on your site.
Tip: How to add description and list of benefits to free tier?
- Go to the 'Tiers' settings in the Ghost Admin.
- Click 'Free' position and add your tier description and list of benefits.
- Finally, click 'Save & close' to activate.
Tip: How to add position to FAQ?
You can add FAQ items in your page content using the HTML card by pasting the code below:
<section>
<h4>Your title</h4>
<p>Your description</p>
</section>
The page content on the Membership page only serves to add FAQ items, it is not designed for other types of content.
Subscribe page
The subscribe page is allowing your visitors to sign up to your site in order to access members only content and receive the premium newsletter.
Step-by-Step
- Create a new page, add a page title, and open the 'Page settings' panel using the icon in the top right of the screen.
- At the bottom of the panel you’ll see a dropdown menu titled 'Template'.
- Use the dropdown menu to select the 'Subscribe' template, close the panel.
- Finally, click 'Publish'.
Comments
The native comments feature in Ghost allows you to invite members to join the discussion and participate in a community directly on your website. Alternatively, you can opt for the Disqus option.
Ghost comments
- To enable native comments, go to the 'Access' settings in the Ghost Admin.
- Change the 'Commenting' level to 'All members' or 'Paid-members only'.
- Finally, click 'Save' to activate.
Disqus comments
- Go to the 'Design & branding' settings in the Ghost Admin.
- On the right you’ll see the tab 'Post' – expand this settings list and go to the 'Disqus shortname' position.
- Paste your 'Disqus shortname', e.g. copy only
your-site
fromyour-site.disqus.com
- Finally, click 'Save' to activate.
Editing a theme
To edit files, you will need to unzip the theme archive — at this point you will have access to the necessary files indicated in the theme documentation.
Step-by-Step
- To edit your theme files, download a copy of the theme. For this purpose go to the 'Design & branding' settings in the Ghost Admin and click 'Change theme' in the bottom right corner.
- Use the 'Installed' tab menu in the upper right corner to download your theme, then unzip the theme locally.
- Once the theme is unzipped, the files can be edited using an code editor – make the changes indicated in the theme documentation.
You can edit files using applications (code editor) such as Sublime Text, Visual Studio Code or Brackets. Using native text editors like TextEdit on macOS may add formatting may cause the theme to work incorrectly.
- When you’ve finished making changes to the theme code, re-zip the theme directory for uploading back to Ghost.
To create a zip archive on a macOS, right-click on the theme folder to view the context menu. Then, click the 'Compress' option. On Windows right-click on the theme folder, select 'Send to', and then select 'Compressed (zipped) folder'.
- To upload a theme, go to the 'Design & branding' settings in the Ghost Admin and click 'Change theme' in the bottom right corner.
- Then click the 'Upload theme' button in the upper right corner.
- Once uploaded, click 'Activate' to activate the theme on your site.
Updating a theme
Updates to the theme ensure compatibility with the latest Ghost version, performance improvements and minor bug fixes. So it is important that you use the latest available theme version.
If your theme features custom code, updating it with the latest versions will overwrite all your customizations.
Step-by-Step
- Download the latest version of the theme, then unzip the archive locally.
- Choose a theme version that is compatible with your Ghost version.
- To upload a theme, go to the 'Design & branding' settings in the Ghost Admin and click 'Change theme' in the bottom right corner.
- Then click the 'Upload theme' button in the upper right corner.
- Once uploaded, click 'Activate' to activate the theme on your site.
Tip: What if you’ve already edited the theme, and want to update it without losing your changes?
That’s a bit trickier to deal with but not impossible, as long as you can remember what the changes were, or more specifically which files you edited. Unfortunately in Ghost when updating a theme you have to re-enter your changes.
For more advanced users, it can be helpful to use a comparing files app like Sublime Merge – that way you can find your changes if you don’t remember them.
Tip: After uploading the theme my settings in Design section were reset, what should I do?
The best solution is to always use the same name e.g. theme-name.zip
– that way you will not have to enter your settings again after uploading a theme.
Ghost assigns the settings in the 'Design & branding' section to the name of the uploaded archive. If you uploadtheme-v1.zip
andtheme-v2.zip
– Ghost will recognize them as two different themes – so the settings will reset.
Theme translation
Translations are used both when you want to add a new language and when you want to edit current phrases used in the theme.
Editing current phrases used in the theme (Requires theme editing)
- You’ll need to open the theme’s
../locales/en.json
file in your code editor. - Change the sentences used in the theme following the pattern:
{
"Old translate": "New translate",
...
}
- After making your changes, save your file, compress the theme into a zip format, and upload it to Ghost.
Translation to another language (Requires theme editing)
- Inside the
../locales/
folder, add target language file for examplees.json
for Spanish andpl.json
for Polish (a valid language code must be used). - Based on the translation from the
en.json
file, add translations for your language in your code editor. For example, for Spanish, use in thees.json
file:
{
"Back": "Volver",
"Newer Posts": "Artículos Siguientes",
"Older Posts": "Artículos Anteriores",
...
}
- After making your changes, save your file, compress the theme into a zip format, and upload it to Ghost.
- Then, go to the 'Publication Language' settings in the Ghost Admin.
- Enter the correct language code into the 'Site language' field.
- Finally, click 'Save' to activate.
Posts per page
The number of posts provided will depend on the 'post per page' setting which you can configure in your package.json file.
Step-by-Step (Requires theme editing)
- You’ll need to open the theme’s
package.json
file in your code editor and find:
"config": {
...
"posts_per_page": <value>
...
}
- Change the current value to the expected value.
- Save your
package.json
file in root folder.
Social accounts
Link your social accounts to have them displayed in the footer of your publication.
Facebook and X
Tip: Adding other social accounts to the footer (Requires theme editing)
../partials/footer_icons.hbs
file in your code editor.{{!--
and--}}
for the chosen profile icon.#
for eachhref
value with your own profile links.footer_icons.hbs
file in../partials/
folder.