Saaga Documentation

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

Install the theme

Follow the steps below to upload the theme:

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

Routes Setup

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

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

The routing file defines the following custom pages and collection:

• / - the homepage and main collection
• /tags/ - the custom tags page, for showcasing all the topics (tags)
• /membership/ - the custom membership page, to show all active membership tiers
• /account/ - the custom account page
• /signup/ - the custom sign up page
• /signin/ - the custom sign in page

Custom Settings

The theme comes with custom design settings, which are accessible from the Ghost Admin panel. To view and edit these settings go to Settings > Design ( yoursite.com/ghost/#/settings/design/)

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

1. Site-wide settings
2. Homepage settings
3. Post settings

Site-wide settings

• Color scheme - set the default color scheme (system, light, dark)
• Font headings - select from a predefined list of font families or use system fonts
• Font body - select from a predefined list of font families or use system fonts
• Use portal links - set your signin, signup, and membership links to use the portal or custom pages

Homepage settings

• Hero style - set the style (accent background, image background, image side, image bottom)
• Hero headline - set the hero headline
• Hero description - set the hero description
• Hero button text - set the hero button text
• Hero button link - set the hero button link
• Featured stories - set the style for the featured articles section
• Featured topics - set the tags for the topics section
• Post feed style - set the preferred post feed style(timeline, grid, list, full-articles)
• Post feed toggle - activate or deactivate the toggle buttons for changing the post feed layout
• Post card image aspect ratio - set the post card image aspect ratio(auto, 16/9, 4/3, 1/1, 3/4, hidden)

Post settings

• Default post template - set the default post template for your posts

Homepage

The homepage is defined in the home.hbs file. The following sections are part of this template:

• hero section
• featured stories
• featured topics
• latest stories

Hero

The hero section is completely customizable from Settings > Design > Homepage, with the following options:

• Hero style - the hero section style and the cover image style

  The following options are available:

  • accent-background - default option: no image, and the background color is your brand color
  • image-background - the cover image in the background
  • image-bottom - the cover image below the hero title & description
  • image-right - the cover image next to the hero title & description
  • no-image - the cover image isn't displayed

• Hero headline

  • the hero section title
  • the title can highlight specific words by using <em> elements, for example:

  Tell your <em>stories</em> in the most <em>compelling</em> and <em>visual</em> way.
  

• Hero description

  • the hero section description
  • here you can also use HTML elements like links, bold text, etc:

• Hero button text

  • the hero section button text
  • if you leave this option empty there will be no button

• Hero button link

  • the hero section button link
  • you can set a custom link to go with your button text
  • the default option is subscribe-form, with this option you get the Ghost subscribe form for collecting members

Featured stories

There are three options you can choose from for your featured posts:

• colored-list - all featured posts will be listed one after the other

For this option the background color is dynamically changed as you scroll the page. Each post will set its own background color with the color being taken from the first tag assigned to the post (tag accent color).

Additionally, the feature image has a special effect on hover, if you want to disable this effect, add the following in code injection:

<script>themeGlobal.featuredImageAnimation = false;</script>

• list - the featured posts will be listed one after the other in a simple minimal way.

• slider - all featured posts will be rendered within a slider element, with buttons for navigating through the list

• none - there will be no featured posts section in this case

Featured topics

Add the tag slugs you want to appear in "Stories about" section. The tags have to be separated by commas and no spaces, no comma after the last item.

Example from the demo:

moon,venus,jupiter,mars,neptune,uranus,saturn,earth,galaxy

For the tags to appear, they have to be assigned to at least 1 post, and the order is exactly the order of your input.

Post feed

The post feed displays the articles ordered by the published date. The layout and design of the post feed can be set from Settings > Design > Homepage > Post feed style with the following options:

• alternating-list - latest posts listing in an alternating format, on one item the image is on the left and on the next the image is on the right. Demo ->
• grid - latest posts in grid format. Demo 2 -> & Demo 5 ->
• list - latest post in a simple list format. Demo 3 ->

Post card

The post card markup is defined in partials/post-card.hbs. The post card image aspect ratio can be changed from Settings > Design > Homepage > Post card image aspect ratio with the following option:

• auto - the uploaded image aspect ratio will be respected
• 16/9 aspect ratio
• 4/3 aspect ratio
• 1/1 aspect ratio
• 3/4 aspect ratio
• hidden - image will not be displayed

Navigation dropdown

Saaga comes with a custom feature to create dropdown menus easily for your header navigation. All you have to do is add the minus sign (-) in front of the items in Settings > Navigation

Items having the - sign will be added as subitems to the previous navigation item. For example from the demo:

• - Membership, - Sign up and - Sign in will belong to the Members item

Custom templates

The default post layout is can be set from the Design settings > Post, this 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 individual posts from the Post/Page Settings menu:

• custom-with-excerpt-on-the-side.hbs - template with excerpt on the right side
• custom-with-full-background-image.hbs - template with feature image in the background
• custom-with-image-on-the-side.hbs - template with image on the right side
• custom-with-narrow-image.hbs - template with a narrow feature image
• custom-with-wide-image.hbs - template with a wide feature image

Post elements

In posts the hero displays post and author information, then at the end of the articles there are other elements like:

• social sharing
• author box (info about the primary author)
• comments section
• read next section for related articles

Additionally, if can enable the image lightbox by adding the following line in Code Injection:

<script>themeGlobal.imageLightbox = true;</script>

Custom Pages

As explained in the routes setup, the theme comes with a couple of custom pages, to activate these pages, there are some actions you have to take.

By default, that is the only requirement, but if you want even more control over the pages then you should activate the data property (remove the # symbol in front of the data property in the routes.yaml file) and create the page with the correct slug.

To create a Page:

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

Archive

Defined by the archive.hbs template, renders articles in chronological order and grouped by month (by the Published Date).

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

/archive/:
  controller: channel
  template: archive
  # data: page.archive # When active data will be taken from the  "/archive/" page

Authors

Defined by the authors.hbs template, renders all authors ordering them by the number of posts.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

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

Tags

Defined by the tags.hbs template, renders all tags ordering them by the number of posts.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file. In this case, you also need to create a page in the Admin with the tags slug.

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

Membership

Defined by the membership.hbs template, renders all tiers with price and benefits.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

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

To use different colors for the your tiers, you can add the following in Code Injection:

<style>body { --color-tier-2: #bfa7ff; --color-tier-3: #4a91f8; }</style>

Signup

Defined by the signup.hbs template.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

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

If you activated the data property, you also have to create the page with the signup slug. Additionally, the feature image of this page will appear on the side.

Signin

Defined by the signin.hbs template.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

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

If you activated the data property, you also have to create the page with the signin slug. Additionally, the feature image of this page will appear on the side.

Account

Defined by the account.hbs template.

If you want to control the meta properties for this page, you have to activate the data property, by removing the # symbol in the routes.yaml file.

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

Color customization

You can change the main accent color from Settings > Design > Brand. 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 light and dark color schemes (and system), 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

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>

Some useful tools for choosing colors and gradients:

• Fuel HSL color picker
• Gradients | Components AI
• CSS Gradient Generator

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

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

For example, here's a purple accent color configuration:

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

Similar configuration for the dark theme:

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

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 8, and you can change it in the package.json file:

"config": {
  "posts_per_page": 8
}

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 post card images can have different format, based on your design settings, the default value being 16/9.

The aspect ratio in the post layouts differs based on the template used and device size.

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.

Comments

Saaga comes with the native comment feature that Ghost offers. The Native Comment System requires at least Ghost v5.9.0, you have to enable it from Settings > Membership > Commenting.

Font options

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

Options for the heading font:

• Sora
• Inter
• Archivo
• Syne
• Open Sans
• Playfair Display
• Space Grotesk
• Red Rose
• JetBrains Mono
• System - no requests to Google fonts

Options for the body font:

• Inter
• Open Sans
• Classic
• Humanist
• Geometric
• Neo Grotesk
• System - no requests to Google fonts

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.

Logo

The publication logo is used for both the header and footer elements. The same logo is used for both light and dark themes, however, you can use filters for changing how the logo looks in certain scenarios.

1. Reduce the brightness of the logo for the homepage only:

<style>.home-template .header__logo { filter: brightness(0); }</style>

2. Increase the brightness and contrast for the dart theme only:

<style>[data-color-scheme="dark"] .header__logo { filter: brightness(10); contrast(200%); }</style>

3. Change the footer logo color with hue-rotate:

<style>.footer-logo { filter: hue-rotate(90deg); }</style>

4. Invert the footer logo color for the light theme only:

<style>[data-color-scheme="light"] .footer-logo { filter: invert(1); }</style>

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:

1. Go to Tabler Icons and click on the Icon you want to add, this will copy the code to your clipboard.
2. Go into the partials/icons directory and create a new file: your-icon.hbs
3. Open the new file and paste the copied code from the clipboard.
4. 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

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

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)

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

Support

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

Contact - Feedback