Tuuli Theme Documentation

Compatible Ghost version: v5.0 or any newer version.

Starting with theme version v1.1.8 you need Ghost v5.54.1 or later.

Install the theme

Follow the steps below to upload the theme:

Log in to your publication admin section at yoursite.com/ghost/
Go to Settings > Design ( yoursite.com/ghost/#/settings/design/ )
Click Change theme and then click Upload theme and select the tuuli.zip file.
After the upload is complete click Activate

Routes Setup

For the theme to function properly you must upload the routes.yaml file.

The theme is intended for blogs primarily, and it comes with a specific route setup to support this use case. There are specific pages and templates like /membership/ and /archive/.

Follow the steps below to upload the routes.yaml file (The file is located inside the zip)

Log in to your publication admin section at yoursite.com/ghost/
Go to Settings > Labs.
Click on Upload routes YAML button and select the file from the root directory of the theme.

Ghost routes.yaml

The routes file defines the following custom routes and collections:

/ - the homepage
/archive/
/authors/
/tags/
/membership/
/signin/
/signup/
/account/
/search/

Custom Settings

The theme comes with custom settings available in the Ghost Admin. Go to Settings > Design ( yoursite.com/ghost/#/settings/design/)

Custom settings are defined and can be changed in the package.json file. These settings are placed under three categories:

Site-wide settings
Homepage settings
Post settings

Site-wide

Color scheme - set the default color scheme (system, light, dark, midnight, ivory, skyblue)
Font family - select from a predefined list of font families or use system fonts
Header position - set the header position (normal, sticky, floating)
Search type - set the search type(native, custom, none)
Use portal links - set your signin, signup, and membership links to use the portal or custom pages
CTA headline - the headline for CTA's above the footer and post sidebar
CTA description - the description for CTA's above the footer and post sidebar

Homepage

Home page layout - set the preferred home page layout(hero-as-left-sidebar, hero-as-right-sidebar, hero-with-image-on-left, hero-with-image-on-right, hero-with-image-below)
Hero source page slug - set the page that will be used for the hero title and description
Featured post feed layout - set the post feed layout for the featured posts section (list-with-images, list, grid-with-images, grid)
Post feed layout - set the post feed layout (list-with-images, list, grid-with-images, grid)
Featured posts section - show or hide the featured posts section
Background accent - set the background accent color for the hero section and the CTA above the footer (brand, mango, mojito, skyline, violet, cherry, sunset, none)
Featured tags slugs - set the tag slugs you want to feature on the homepage

Post

Comment plugin - set your comment plugin (Native, Cove, Disqus)
Comment plugin id - set the commend plugin ID (Cove ID, Disqus ID)

Homepage

The homepage layout is defined in the index.hbs file and has the following sections (besides the header and footer):

hero
posts
featured tags
subscribe CTA

Hero

The hero section can be completely customized from the Ghost Admin, including the title, description, and style.

By default the title and description will be the {{@site.title}} and {{@site.description}} (from Settings > General > Title & Description), and the image will be the {{@site.cover_image}} (from Settings > Desgin > Brand > Publication cover )

If you want a more flexible description, with links and other Ghost editor elements, you have to set the Hero source page slug in Settings > Design > Homepage. You have to add the slug of an existing page, and when you do that, the hero title will be your page title, the hero description will be your page content and the hero image will be your page feature image. (For example, in the demo, the value in settings is homepage, which means that the title, description, and image, will be taken from the /homepage/ page).

To change the style of the hero section you have to set the Home page layout in Settings > Design > Homepage. You can choose from the following options:

hero-as-left-sidebar - the hero section appears as a sidebar on the left side, posts appearing on the right (on desktop)
hero-as-right-sidebar - the hero section appears as a sidebar on the right side, posts appearing on the left (on desktop)
hero-with-image-on-left - this is a wide hero section with the image on the left
hero-with-image-on-right - this is a wide hero section with the image on the right
hero-with-image-below - this is a wide hero section with the image appearing below the hero content

Posts

First of all, you can enable a separate featured posts section, simply by toggling the Featured posts section in Settings > Design > Homepage.

To change the style, you have to set the Post feed layout in Settings > Design > Homepage. You can choose from the following options:

list-with-images - post feed with post cards appearing as a list, including the feature image
list - post feed with post cards appearing as a list, without the feature image
grid-with-images - post feed with post cards appearing as grid items, including the feature image
grid - post feed with post cards appearing as grid items, without the feature image

The Post feed layout setting will apply to both the 'Featured posts' and 'Latest posts' as well as the 'Tag' and 'Author' templates.

The pagination is in classic style allowing you to navigate to each page separately, but you can change this style by changing the partials/pagination.hbs template.

Featured tags

To highlight some tags of your choosing, you just have to provide the tag slugs, separated by a comma in Featured tags slugs in Settings > Design > Homepage.

You can add any number of tags, but ideally, it should be a multiple of 4. For example, in the demo, the value of the custom setting: growth, balance, health, focus This means that the tags with slug 'growth', 'balance', 'health', and 'focus' will be fetched and rendered.

The subscribe section right above the footer uses the {{@site.title}} and {{@site.description}}, for the headline and the description, but you can easily change it with the CTA Headline and CTA description in Settings > Design > Site-Wide.

Additionally, the Background accent in Settings > Design > Homepage provides different predefined background-color options for the CTA section.

Custom Pages

As explained in the routes setup, the theme comes with a couple of custom pages, which need some actions from your side to be activated.

Uploading the routes.yaml file is a key requirement for these custom pages.

By default, that is the only requirement, but if you want even more control over the pages then you should activate the data property and create the page with the correct slug.

To create a Page:

Log in to your publication admin section at yoursite.com/ghost/
Go to Pages ( yoursite.com/ghost/#/pages/ )
Click New page and set the Title and Page URL
Finally, click Publish

Account

The account page is implemented in the account.hbs template.

If you want to control the meta properties for this page, you have to activate the data property:

/account/:
  template: account
  data: page.account # When active data will be taken from the  "/account/" page

If you activated the data property, you also have to create the page with the account slug.

Membership

The membership page is implemented in the membership.hbs template.

If you want to control the meta properties for this page, you have to activate the data property:

/membership/:
  template: membership
  data: page.membership # When active data will be taken from the  "/membership/" page

If you activated the data property, you also have to create the page with the membership slug.

The membership tier names, prices, and benefits can all be changed in the Admin, by going to Settings > Membership ( /ghost/#/settings/members). Edit existing tiers or add new ones under the Membership Tiers section.

Search

By default the native Ghost search is active, but you can change it from the custom settings: Search type in Settings > Design > Site-wide.

The options are:

Native - the Ghost native search function will be used
Custom - the custom search function will be used
None - deactivate the search and the icon will not be displayed

Both the native and custom search functions, work out of the box, you don't need to configure anything (besides uploading the routes file for the custom search).

The custom search is implemented in the search.hbs template and it's based on the fuse.js library To customize how the custom search works, you can edit the template.

Custom search demo

Authors

The authors page is implemented in the authors.hbs template.

If you want to control the meta properties for this page, you have to activate the data property:

/authors/:
  template: authors
  data: page.authors # When active data will be taken from the  "/authors/" page

If you activated the data property, you also have to create the page with the authors slug.

Custom templates

The default post layout is defined by the post.hbs template and the default page layout is defined by the page.hbs template.

The theme comes with several custom templates, which can be selected for both posts and pages, in the Post Settings menu.

Custom templates:

custom-with-background-image.hbs - template with feature image in the background
custom-with-full-width-background-image.hbs - template with feature image being a full-width background
custom-with-image-on-side.hbs - template with feature image being on the side (on desktop)
custom-with-narrow-image.hbs - template with a narrow image format (same width as the post content)
custom-with-sidebar.hbs - template with sidebar beside the post content (on desktop), sidebar template is partials/sidebar.hbs
custom-with-table-of-contents-and-sidebar.hbs - template with table of contents on the left and sidebar on the right side of the post content

If you want to edit the templates these are in the root directory of the theme.

Color customization

The most important CSS configurations of the theme are defined as custom CSS properties, so you can easily overwrite them from code injection to change background colors, text colors, and more.

The theme comes with 5 different color schemes, the default one can be set in the admin using the Default color scheme in Settings > Design > Site-Wide.

The included color schemes:

light
dark
midnight
ivory
skyblue

The default option is system which will be either the dark or light theme, depending on the user's preference.

It's possible to change the color schemes by changing the properties. This can be done by adding the following in code injection and adjusting the values.

To change the light theme:

<style>
  :root {
    /* color configuration */
    --color-text: hsl(0 0% 15%);
    --color-text-acc: hsl(0 0% 25%);
    --color-text-reverse: hsl(0 0% 85%);
    --color-bg: hsl(0 100% 100%);
    --color-bg-acc: hsl(0 0% 97%);
    --color-bg-reverse: hsl(0 0% 15%);
    --color-bg-base: 0 0% 100%;
    --color-bg-base-reverse: 0 0% 0%;
    --color-neutral: hsl(0 0% 50%);
    --color-border: hsl(0 0% 92%);
  }
</style>

To change the dark theme:

<style>
  html[data-color-scheme='dark'] {
    --color-text: hsl(0 0% 85%);
    --color-text-acc: hsl(0 0% 75%);
    --color-text-reverse: hsl(0 0% 15%);
    --color-bg: hsl(0 100% 100%);
    --color-bg-acc: hsl(0 0% 97%);
    --color-bg-reverse: hsl(0 0% 15%);
    --color-bg-base: 0 0% 100%;
    --color-bg-base-reverse: 0 0% 0%;
    --color-neutral: hsl(0 0% 50%);
    --color-border: hsl(0 0% 20%);
  }
</style>

To change the midnight theme:

<style>
  [data-color-scheme='midnight'] {
    --color-text: hsl(250 63% 90%);
    --color-text-acc: hsl(250 63% 85%);
    --color-text-reverse: hsl(250 63% 10%);

    --color-bg: hsl(250 63% 10%);
    --color-bg-acc: hsl(250 63% 20%);
    --color-bg-reverse: hsl(250 63% 90%);
    --color-bg-base: 250 63% 0%;
    --color-bg-base-reverse: 250 63% 100%;

    --color-neutral: hsl(250 63% 50%);
    --color-border: hsl(250 63% 25%);
  }
</style>

To change the ivory theme:

<style>
  [data-color-scheme='ivory'] {
    --color-text: hsl(34 36% 10%);
    --color-text-acc: hsl(34 36% 15%);
    --color-text-reverse: hsl(34 36% 90%);

    --color-bg: hsl(34 36% 90%);
    --color-bg-acc: hsl(34 36% 85%);
    --color-bg-reverse: hsl(34 36% 10%);
    --color-bg-base: 34 36% 100%;
    --color-bg-base-reverse: 34 36% 0%;

    --color-neutral: hsl(34 36% 50%);
    --color-border: hsl(34 36% 75%);
  }
</style>

To change the midnight theme:

<style>
  [data-color-scheme='skyblue'] {
    --color-text: hsl(210 100% 10%);
    --color-text-acc: hsl(210 100% 15%);
    --color-text-reverse: hsl(210 100% 90%);

    --color-bg: hsl(210 100% 92%);
    --color-bg-acc: hsl(210 100% 88%);
    --color-bg-reverse: hsl(210 100% 10%);
    --color-bg-base: 210 100% 50%;
    --color-bg-base-reverse: 210 100% 50%;

    --color-neutral: hsl(210 100% 50%);
    --color-border: hsl(210 100% 86%);
  }
</style>

Some useful tools for choosing colors and gradients:

You can even define your color schemes, but that would require changing the theme files. Steps to define new color schemes:

Change the package.json file, adding a new option under the color_scheme property.
Add the new color scheme to the dropdown editing the partials/color-scheme-dropdown.hbs
Add the CSS, either in code injection (using the previous code blocks as a template) or in the CSS files.

Ghost config

Some configurations in Ghost themes can be defined in the package.json file, including Posts per page, Image sizes, and Custom settings.

Posts per page

The posts per page defines the number of posts that appear in your collections until it's paginated. For example, the value of posts_per_page is used on the home page, tag, and author templates.

By default, this is set to 12, and you can change it in the package.json file:

"config": {
  "posts_per_page": 12
}

Image sizes

Ghost can handle responsive image sizes, and this is defined in the package.json file, under the image_sizes property. You can change the default configuration by editing this file before uploading the theme.

"image_sizes": {
  "xxs": {
    "width": 30
  },
  "xs": {
    "width": 100
  },
  "s": {
    "width": 300
  },
  "m": {
    "width": 600
  },
  "l": {
    "width": 1000
  },
  "xl": {
    "width": 2000
  }
}

The image sizes defined there will be used to generate copies of images at the specified sizes when uploading images in Ghost Admin.

The theme also comes with the lazysizes library for lazyloading images, to improve performance.

When it comes to aspect ratios, the postcards can have a ratio of 4/3(for list type) and 16/9(for grid type).

The aspect ratio in the post layouts differs based on the template used and device size, but generally, the 4/3 and 16/9 aspect ratio images should work fine.

Syntax Highlighting

The theme comes with prism.js integration by default, to activate syntax highlighting just add the internal tag #syntax-highlight to your post.

Why is this necessary? In short, for performance. To avoid loading the library when it's not necessary. If you don't add the tag, the library will not load at all.

If you are someone who shares code regularly and wants to have the plugin on all your posts, without having to add the tag, you can do so by changing the partials/syntax-highlight.hbs file. Simply remove the condition checking for the tag.

Additionally, in this partial file, it's defined which version of the prism library is loaded as well as the components, languages, and theme. So you can easily customize it, add new languages, or a different code highlighting the theme without having to go into theme development.

Table of contents are generated using the TocBot library and this is integrated into the theme by default. You can use the ToC functionality in two ways:

Using the With Table Of Contents And Sidebar template.
Using the internal tag #toc.

With the first option, you get a fixed Table of Contents on the left side next to the post content and also a sidebar on the right. (You can select this template for any post in the Post Settings menu in the Admin).

With the second option, you get a floating ToC on the top-right part of the website, with this option you can add a Table of Contents to any template you are using.

If you want to make changes to the ToC layout or the TocBot library configuration, you can edit the partials/toc.hbs file.

Comments

Tuuli comes with several comment platforms integrated:

By default, comments will not appear on your posts. To activate one of these platforms:

Inside Ghost Admin go to Settings > Design > Post
Change the Comment Plugin dropdown from None to either Native, Cove or Disqus.
Provide the Comment Plugin Id (not necessary for the Native comment system)

The Native Comment System requires Ghost v5.9.0 at least. Additionally, you have to enable it from Settings > Membership > Commenting. By default, native comments are not active, so you have to select either All members or Paid-members only

The Comment Plugin Id for Cove is your cove_id, which you can get from your cove.chat account.

The Comment Plugin Id for Disqus is your disqus_shortname, which you can get from your Disqus account.

Both Cove and Disqus comment integrations have their own integrations in separate partial files: partials/comments-cove.hbs and partials/comments-disqus.hbs.

Google Fonts

You can set the font family from the Admin section, going to Settings > Design > Site-wide and under Font family select one of the options.

The theme comes with the following options:

System font - the default value, loads the system font (no requests to Google Fonts)
Literata & Inter - Literata for headings and Inter for the body font
Inter - Inter for both headings and body
Bitter - Bitter for both headings and body font
Outfit - Outfit for both headings and body font
Space Grotesk - Space Grotesk for both headings and body font
Inconsolata - Inconsolata for both headings and body font

With the System font option, you can avoid requests to the Google servers in case GDPR is a concern.

If you still want to use Google fonts and want to self-host the font files check out this guide for self-hosting Google Fonts.

Icons

The icons used in the theme are from Tabler Icons, the library consists of 4000+ icons. Not all icons from the library are included to save on the file size, but the most common icons are included in the partials/icons directory.

Inside the partials/icons directory, you can find all included icons, in separate .hbs files.

Here are the steps to add new icons:

Go to Tabler Icons and click on the Icon you want to add, this will copy the code to your clipboard.
Go into the partials/icons directory and create a new file: your-icon.hbs
Open the new file and paste the copied code from the clipboard.
Save the file.

For using the icons inside the theme files, there is a special partial file partials/icon.hbs which accepts name and size as parameters.

Let's see an example and try to add a new icon. Assuming we want to add the icon camera and by clicking on the icon on the website, we get this code:

<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-camera" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="#2c3e50" fill="none" stroke-linecap="round" stroke-linejoin="round">
  <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
  <path d="M5 7h1a2 2 0 0 0 2 -2a1 1 0 0 1 1 -1h6a1 1 0 0 1 1 1a2 2 0 0 0 2 2h1a2 2 0 0 1 2 2v9a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-9a2 2 0 0 1 2 -2" />
  <circle cx="12" cy="13" r="3" />
</svg>

The next step is to create a new file: partials/icons/camera.hbs and paste the copied code in the file. The new file must be of .hbs type, so we can use it into the theme files:

{{>icon name="camera" size="lg"}}

Social links are shown in the footer and by default, the theme comes with:

Facebook (Settings > General > Social accounts)
Twitter (Settings > General > Social accounts)
RSS

To add other links you need to edit the partials/social-links.hbs file. There are several other links in there already, you just have to uncomment the relevant parts and add your link in the href attribute.

Social sharing is part of the post layout and the following is included:

Twitter
Facebook
Linkedin
Email
Copy to clipboard

To add other social sharing options you need to edit the partials/social-share.hbs file.

Translations

By default, everything is in English (en.json), additionally, the theme comes with translations in:

🇩🇪 German (de.json)
🇪🇸 Spanish (es.json)
🇫🇷 French (fr.json)
🇮🇹 Italian (it.json)
🇳🇱 Dutch (nl.json)
🇵🇹 Portuguese (pt.json)
🇹🇷 Turkish (tr.json)

For a translation to apply, you have to set the language in Settings > General > Publication language.

If you want to edit the translation in a specific language, you have to edit the corresponding translation file. The files are stored in the locales a directory (inside the theme zip).

|__ locales
|   |__ de.json
|   |__ en.json
|   |__ es.json
|   |__ fr.json

If the language file for your language doesn't exist, you have to create it (make sure to use the correct language code) The best way is to copy the content en.json file in your new language file, then change the translations.

Theme development

If you want to make more advanced changes to the theme, or you want to develop your components, the theme comes with a developer-friendly setup. You can take advantage of the Gulp tasks that are set up for compiling Javascript and PostCSS.

All the assets are combined and minified for better speed and performance. To customize the theme make sure you have Node.js and npm installed.

Follow the official guide for installing Ghost locally. After you have installed Ghost and put the theme directory inside the content/themes/ directory, run the following commands in the theme directory:

npm install

This will install all the dependencies for the theme

Then run:

gulp

This will compile PostCSS and javascript and will watch for changes. So when you edit a .hbs, .css or .js file the change will trigger the gulp watch task and this will compile the assets whenever you change a file.

If you want to compile just CSS:

gulp css

If you want to compile just JS:

gulp js

FAQ & Code Snippets

Frequently asked questions and useful snippets you can use to make some quick changes to your site.

How to resize the header logo?

Go to the Admin, Settings > Code Injections and in the Site Header add (adjust the height value depending on your preference):
```
<style>.header__brand img { height: 42px; }</style>
```
How to resize the footer logo?

Go to the Admin, Settings > Code Injections and in the Site Header add (adjust the height value depending on your preference):
```
<style>.footer__brand img { height: 50px; }</style>
```
How to remove the color scheme dropdown?

Go to the Admin, Settings > Code Injections and in the Site Header add:
```
<style>.color-scheme { display: none; }</style>
```

Support

Don't hesitate to reach out if you need help or have any suggestions.

Contact - Feedback

Tuuli Documentation

Tuuli v1.3.0 for Ghost 5.x

Install the theme

Routes Setup

Custom Settings

Site-wide

Homepage

Post

Homepage

Hero

Posts

Featured tags

Custom Pages

Archive

Account

Membership

Search

Authors

Tags

Custom templates

Color customization

Ghost config

Posts per page

Image sizes

Syntax Highlighting

Table of Contents

Comments

Google Fonts

Icons

Translations

Theme development

FAQ & Code Snippets

Support

Tuuli Documentation

Tuuli v1.3.0 for Ghost 5.x

Install the theme

Routes Setup

Custom Settings

Site-wide

Homepage

Post

Homepage

Hero

Posts

Featured tags

Subscribe CTA

Custom Pages

Archive

Signup

Signin

Account

Membership

Search

Authors

Tags

Custom templates

Color customization

Ghost config

Posts per page

Image sizes

Syntax Highlighting

Table of Contents

Comments

Google Fonts

Icons

Social links

Social sharing

Translations

Theme development

FAQ & Code Snippets

Support