Introduction

The following documentation is your guide to the new theme. Since this is a Ghost theme documentation, it is assumed that you have a basic knowledge of the Ghost app.

If you’re just starting out with Ghost, it is best to see the guides in the official Ghost Help Center – check this out and you’ll have all the information that is available.

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

1. To upload a theme, go to the Design settings in the Ghost Admin and click Change theme in the bottom left corner.
2. Then click the Upload theme button in the upper right corner.
3. Once uploaded, click Activate to activate the theme on your site.

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 section to the name of the uploaded archive. If you upload theme-v1.zip and theme-v2.zip – Ghost will recognize them as two different themes – so the settings will reset.

Editing a theme

In many places in the following documentation you will encounter information about editing theme files. 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

1. To edit your theme files, download a copy of the theme. For this purpose go to the Design settings in the Ghost Admin and click Change theme in the bottom left corner.
2. Use the Advanced dropdown menu in the upper right corner to download your theme, then unzip the theme locally.
3. 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 Atom. Using native text editors like TextEdit on macOS may add formatting may cause the theme to work incorrectly.

1. 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.

1. To upload a theme, go to the Design settings in the Ghost Admin and click Change theme in the bottom left corner.
2. Then click the Upload theme button in the upper right corner.
3. 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

1. Download the latest version of the theme from Themeforest, then unzip the archive locally.
2. Choose a theme version that is compatible with your Ghost version.
3. To upload a theme, go to the Design settings in the Ghost Admin and click Change theme in the bottom left corner.
4. Then click the Upload theme button in the upper right corner.
5. 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 section to the name of the uploaded archive. If you upload theme-v1.zip and theme-v2.zip – Ghost will recognize them as two different themes – so the settings will reset.

Uploading a logo

A publication logo is the primary logo for your brand and is displayed across your theme.

Step-by-Step

1. To upload a logo, go to the Design settings in the Ghost Admin.
2. On the left you’ll see the option Brand – expand this settings list and go to the Publication logo position.
3. Click Upload logo to upload your logo.
4. Finally, click Save changes to activate.

Uploading a cover image

A publication cover is an optional large background image that can be used with your publication.

Step-by-Step

1. To upload a publication cover, go to the Design settings in the Ghost Admin.
2. On the left you’ll see the option Brand – expand this settings list and go to the Publication cover position.
3. Click Upload cover to upload your image.
4. Finally, click Save changes to activate.

Adding navigation

Adding a navigation menu to your publication can be implemented and edited quickly under the 'Navigation' settings menu.

Step-by-Step

1. To add a navigation, go to the Navigation settings in the Ghost Admin.
2. Once here, you can remove any navigation items that you want by using the trash icon to the right of the item. You can add new items by just typing them in. You can change the order by clicking on the icon on the left and dragging it to the spot you want.
3. Once your items are added, click Save to activate new navigation on your site.

Disqus

Disqus is a commenting platform that lets you communicate directly with your readers. The theme integrates with Disqus so you can collect user’s feedback on your articles.

Step-by-Step

1. Go to the Design settings in the Ghost Admin.
2. On the left you’ll see the option Post – expand this settings list and go to the Disqus shortname position.
3. Paste your Disqus shortname, e.g. copy only your-site from your-site.disqus.com
4. Finally, click Save changes to activate.

Description

The publication description are used in theme, meta data and search results.

Step-by-Step

1. To add Description, go to the General settings in the Ghost Admin.
2. Then at the top, you’ll see the option Title & description.
3. Click Expand.
4. Once your description are added, click Save settings to activate.

Tip: How to add secondary description?

The secondary description is visible under the primary description in the central part of the homepage.

1. To add your own secondary description, go to the Design settings in the Ghost Admin.
2. On the left you’ll see the option Homepage – expand this settings list and go to the Secondary description position.
3. Enter your own secondary description.
4. Finally, click Save changes to activate.

Featured section

Select which posts or pages you want to appear at the top of your site in the featured section.

Step-by-Step

1. Open the post you would like to add to the featured section.
2. Then, go to the Post/Page settings panel using the icon in the top right of the screen.
3. At the bottom of the panel, you’ll see a checkbox titled Feature this post/page.
4. Click on the checkbox, close the panel.

Tip: How to remove featured posts from the main collection?

1. Go to the Labs settings in the Ghost Admin and scroll down until you see the Routes section.
2. Upload the routes.yaml file with these settings:

routes:

collections:
  /:
    permalink: /{slug}/
    filter: featured:false
    template: index
  /featured/:
    permalink: /featured/{slug}/
    filter: featured:true
    template: index

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

The most important thing to know when working with .yaml is that it uses indentation to denote structure. That means the only type of nesting which works is 2 spaces. The most common reason for .yaml files not working is when you accidentally use the wrong type or quantity of spacing for indentation.

Social accounts

Enter your Facebook and Twitter account details in the 'General' settings of the Ghost Admin to enable links to your social profiles.

Step-by-Step

1. To add Facebook and Twitter account to your publication, go to the General settings in the Ghost Admin.
2. Then scroll down and at the bottom, you’ll see the option Social accounts.
3. Once adding social accounts, click Save settings to activate.

Tip: Adding other social accounts to the footer

1. Open ../partials/social_icons.hbs file in your code editor.
2. Then, uncomment the block – remove the lines which contains {{!-- and --}} for the chosen profile icon.
3. Now replace the # for each href value with your own profile links.
4. Save your social_icons.hbs file in ../partials/ folder.

Tags page

To present all tags from your publication in an elegant way, you can add a custom tags page.

Step-by-Step

1. Create a new page, add a Page title, and open the Page settings panel using the icon in the top right of the screen.
2. At the bottom of the panel you’ll see a dropdown menu titled Template.
3. Use the dropdown menu to select the Tags template, close the panel.
4. Finally, click Publish.

Tip: Adding page to the navigation

If you want this page to appear in the main navigation of your site, just add it to the Navigation list in your site settings.

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

1. To add a responsive table, use the Markdown card.
2. Add a container <div class="responsive-table"> element with around the table (in markdown there always needs to be a blank line between any HTML and markdown).

<div class="responsive-table">

| # | Heading | Heading | Heading | Heading | Heading |
|:--|:--------|:--------|:--------|:--------|:--------|
| 1 | Cell    | Cell    | Cell    | Cell    | Cell    |
| 2 | Cell    | Cell    | Cell    | Cell    | Cell    |
| 3 | Cell    | Cell    | Cell    | Cell    | Cell    |

</div>

Tip: What it takes to generate a table?

To generate a table, you can use the tool Markdown Tables Generator

Subscription form

The subscription form is placed at the bottom of the homepage and posts.

Tip: How to remove the subscription form?

1. You’ll need to open the theme’s default.hbs file in your code editor.
2. You need to remove {{>members/subscribe_form}} partial reference.
3. Save your default.hbs file in root folder.

Accent color

Primary color used in your publication.

Step-by-Step

1. To change the accent color in your publication, go to the Design settings in the Ghost Admin.
2. On the left you’ll see the option Brand – expand this settings list and go to the Accent color position.
3. Choose your color.
4. Finally, click Save changes to activate.

Posts per page

By default, the homepage, author’s and tag’s page display a maximum of 8 posts per page, but you are able to change this number.

Step-by-Step

1. You’ll need to open the theme’s package.json file in your code editor and find:

"config": {
    ...
    "posts_per_page": 8
    ...
}

1. Change the value of the 8 to the expected value.
2. Save your package.json file in root folder.

Theme translation

The theme is fully translatable by enabling a publication language in the settings of the Ghost Admin. Before that, you must prepare your language file.

Step-by-Step

1. Inside the ../locales/ folder, add target language files for each translatable language used on your site. For example es.json for Spanish and pl.json for Polish. A valid language code must be used.
2. Translate the sentences used in theme inside your new language files, for example, in en.json:

{
    "Back": "Back",
    "Newer Posts": "Newer Posts",
    "Older Posts": "Older Posts",
    ...
}

1. And edited to translate into Spanish for es.json:

{
    "Back": "Volver",
    "Newer Posts": "Artículos Siguientes",
    "Older Posts": "Artículos Anteriores",
    ...
}

1. Upload a theme with a new language file.
2. Go to the General settings in the Ghost Admin.
3. At the top of the page, you’ll see the Publication info section.
4. Enter the correct language code into your Publication language settings menu.
5. Finally, click Save settings to activate.

Tip: Reactivate the translation file

If you edited the active language, you have to restart Ghost to make the changes effective. Alternatively, enter another language code and click Save settings to activate, then switch back to your language code.