Flair Documentation

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 ( yoursite.com/ghost/#/settings/design/change-theme )
4. Click Upload theme and select the flair.zip file.
5. After the upload is complete, under Installed themes click Activate

Routes setup

Follow the steps below to upload the routes.yaml file (this is a separate step from theme upload)

1. Log in to your publication admin section at yoursite.com/ghost/
2. Go to Settings > Labs ( yoursite.com/ghost/#/settings/labs )
3. Under Beta features click on Upload routes file button and select the file from the root directory of the theme.

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 & Branding ( 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

Here's a preview of the available settings:

Homepage

The homepage is defined in the home.hbs file and it has several sections based on your theme settings:

• hero
• featured posts
• featured tags
• latest posts

Hero

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

• Hero headline - the hero section title

  Example from the demo (the <span> element can be used to highlight the text with the brand color):

  Flair <span>Blog</span> & Resources
  

• Hero subheading - the hero section description

  Here you can also use HTML elements like links, bold text, etc.

• Hero background style - the hero section background style, with the following options:

  • none - the default option
  • cover-image - the site cover image is used as background
  • full-width-cover-image - the site cover image is used, and it will always be full-width
  • brand-accent-color - the brand accent color will be in the background in the form of a subtle gradient

• Hero action - you can choose from the following actions for your hero section:

  • cta - this option is based on the Site-wide CTA text and link settings
  • subscribe-form - this option will render a subscribe form for capturing emails
  • none - no actions in the hero

Featured posts

To feature a post, toggle on the Feature this post field in Post settings. The homepage featured section will render upto 5 featured posts. The layout will adapt based on the number of featured posts you have.

In case you have not featured any post, the section will not be rendered.

Featured tags

The featured tags can be set from Settings > Design & Branding > Homepage > Featured tags.

Example from the demo:

features,guides,tutorials,data-analysis,data-management

The layout of featured tags can be set from Settings > Design & Branding > Homepage > Featured tags layout. The two options are:

1. list - all tags will be listed in one row with easy navigation to the tag pages
2. section - for each featured tag a separate section is rendered with 3 posts with the tag and a link to the tag page
3. cards - for each featured tag a card is rendered and this can be scrolled if you have many tags

Latest posts

The latest posts will render your articles in chronological order starting with the most recent. If you have more posts then your posts_per_page the pagination will be displayed and you can navigate to the subsequent pages.

The layout of this section can be list or grid based on what you set in Settings > Design & Branding > Homepage > Post feed layout.

More details in the post feed section.

Header

The header is defined in the partials/header.hbs and it renders your publication logo, primary navigation, the native search button and the main action buttons.

Customizing options:

• sticky header - By default the header is set to be sticky, meaning it will stay on top of the page as you scroll, this can be disabled from Settings > Design & Branding > Site-wide > Sticky header

• dark theme logo - For the logo, you have the publication logo from your Brand settings, this will be used for the light theme. There is another design setting to upload a another logo for the dark theme. You can do this from Settings > Design & Branding > Site-wide > Dark theme logo

• primary navigation - Your primary navigation is rendered in the middle of the header, with support for dropdown menus

• header action - _the default option is the CTA, which can be defined from Settings > Design & Branding > Site-wide then the two settings: CTA text and CTA link. Alternatively you can use other actions for the header: a subscribe button pointing to the Ghost portal or signin-signup buttons using the same Portal.

Tips:

• change the logo size
• remove the search

Footer

The footer is defined in the partials/footer.hbs and it renders your publication logo, site description, social links, primary (labelled with the site title) & secondary(labelled 'Legal') navigation, your featured tags(labelled 'Categories') and finally copyright and the theme toggle.

To change the labels you can edit the footer.hbs file, or alternatively do it with a code snippet from your Admin > Code injection.

Post feed

The logic and the layout is defined in the partials/post-feed.hbs file.

The layout of the feed is based on what you set in Settings > Design & Branding > Homepage > Post feed layout. and the possible values are list or grid.

Post card

When the grid layout is set, the individual article cards are rendered using the partials/post-card.hbs file. There are two design settings to customize these cards:

1. Post card style

• minimal - the default option - clean, minimal style
• bordered - the cards will have a border around them and a subtle background color
• shadowed - the cards will have a subtle shadow around them

2. Post card access - to show or hide the access indicator on the cards

CTA section

To display the cta section above the footer create a new page and make sure the page URL is cta. The content of the page will be used as the content of the CTA and the feature image of the page will be the background.

Custom pages

The theme comes with a couple of custom pages, to active them you must upload the routes.yaml file The following pages will be activated:

• /archive/
• /tags/
• /membership/
• /signin/
• /signup/

Meta data

For example, if you want to control the meta data for the /archive/ page:

1. Change the routes file and add the data property:

  /archive/:
    controller: channel
    template: archive
    data: page.archive

2. Create a new page in your admin and make sure the page URL is archive
3. Re-upload the routes.yaml

Membership page content

To add an faq section, or any additional content on the membership page, follow the steps below:

1. Create a new page in the Admin with the slug membership
2. Add your content, for an faq section you can use the native toggle cards:

3. Change the routes.yaml and extend the /membership/ route:

  /membership/:
    template: membership
    data: page.membership

4. Reupload the new routes.yaml file

Post templates

The theme comes with 3 custom post templates, these templates can be selected from the Post Settings menu:

• custom-with-narrow-feature-image.hbs - a template with a narrow feature image (same as the content)
• custom-with-wide-feature-image.hbs - a template with wide feature image
• custom-with-table-of-contents.hbs - a template with table of contents

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

• system
• 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-typography: hsl(0 0% 15%);
    --color-typography-tone: hsl(0 0% 40%);
    --color-typography-content: hsl(0 0% 35%);
    --color-typography-reverse: hsl(0 0% 95%);
    --color-background: hsl(0 0% 100%);
    --color-background-tone: hsl(0 0% 98%);
    --color-background-opac: hsla(0 0% 100% / 75%);
    --color-background-reverse: hsl(0 0% 12%);
    --color-border: hsl(0 0% 90%);
    --color-border-reverse: hsl(0 0% 20%);
  }
</style>

To change the dark theme:

<style>
  html[data-color-scheme="dark"]:root {
    --color-typography: hsl(0 0% 90%);
    --color-typography-tone: hsl(0 0% 70%);
    --color-typography-content: hsl(0 0% 70%);
    --color-typography-reverse: hsl(0 0% 15%);
    --color-background: hsl(0 0% 10%);
    --color-background-tone: hsl(0 0% 12%);
    --color-background-opac: hsla(0 0% 0% / 50%);
    --color-background-reverse: hsl(0 0% 98%);
    --color-border: hsl(0 0% 18%);
    --color-border-reverse: hsl(0 0% 92%);
  }
</style>

Some useful tools for choosing colors and gradients:

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

Fonts

You can set the font family from the Admin section, going to Settings > Design > Site-wide. There are two options, one for the headings and another for the rest of the elements:

Heading font options:

• System - loads the system font (no requests to Google Fonts)
• DM Sans
• Figtree
• Inter
• Kode Mono
• Lexend
• Noto Serif
• Outfit
• Playfair
• Sen
• Source Serif 4
• Space Grotesk

Body font options:

• System
• DM Sans
• Figtree
• Inter
• Kode Mono
• Lexend
• Noto Serif
• Outfit
• Playfair
• Sen
• Source Serif 4
• Space Grotesk

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.

Dropdown menus

flair 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

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.

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": 320
  },
  "m": {
    "width": 640
  },
  "l": {
    "width": 960
  },
  "xl": {
    "width": 1280
  },
  "xxl": {
    "width": 2000
  }
}

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

Comments

The theme uses the native Ghost comment feature. The Native Comment System requires at least Ghost v5.9.0, you have to enable it from Settings > Membership > Access > Commenting.

Here are the options you can choose from:

• All members - Logged-in members
• Paid-members only - Only logged-in members with an active subscription
• Nobody - Disable commenting completely

Icons

The icons used in the theme are from Tabler Icons, the library consists of 5000+ icons. Only the icons used in the theme are included in the partials/icons directory 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" strokeWidth="1.5" stroke="#2c3e50" fill="none" strokeLinecap="round" strokeLinejoin="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"}}

Social links

Social links are shown in the footer by default. The basic social links that Ghost comes with can be edited from Settings > General settings > Social accounts:

• Facebook
• X(Twitter)

The theme also comes with the following list of social platforms:

• threads
• linkedin
• discord
• github
• instagram
• pinterest
• reddit
• telegram
• tiktok
• whatsapp
• youtube

To activate any of these platforms, add the following in your Admin Settings > Code Injection > Site footer. For example to activate GitHub:

<script>
  socials.github = 'https://github.com/brightthemes'
</script>

Social sharing

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

• X(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 implement your own components, you can take advantage of the developer-friendly setup of the theme.

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

The theme is built with TailwindCSS and Alpine.js. The development environment is based on Vite, the tasks can ran with npm scripts.

This guide is assuming that you have installed Ghost locally. Add the theme directory inside Ghost's content/themes/ directory then move to the theme directory in your command line. Run the npm install command to install all the dependencies.

After that is done, you have access to run the npm scripts:

1. npm run dev (vite build --watch & vite) The dev script will start the development process, watching for changes and building. The vite.config.js file contains the main configuration for Vite.

2. npm run build (vite build) The build script will start the build process.

3. npm run test (gscan . --verbose) The test will test the theme using gscan the official Ghost test tool.

4. npm run zip The zip script will create a zip file in the dist directory.

Code Snippets

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

How to change the logo size?

Go to the Admin, Settings > Code Injections and in the Site Header add, changing the values as needed:

<style>
:root {
  --logo-h-mobile: 28px;
  --logo-w-mobile: auto;
  --logo-h-desktop: 32px;
  --logo-w-desktop: auto;
}
</style>

How to change the footer labels?

Go to the Admin, Settings > Code Injections and in the Site Header add:

<style>
  [data-footer-nav="primary"] > span { visibility: hidden; }
  [data-footer-nav="primary"] > span:before { 
    content: "Your label"; 
    visibility: visible; 
  }

  [data-footer-nav="secondary"] > span { visibility: hidden; }
  [data-footer-nav="secondary"] > span:before { 
    content: "Your label"; 
    visibility: visible; 
  }

  [data-footer-nav="categories"] > span { visibility: hidden; }
  [data-footer-nav="categories"] > span:before  { 
    content: "Your label"; 
    visibility: visible; 
  }
</style>

How to remove the header search?

Go to the Admin, Settings > Code Injections and in the Site Header add:

<style>[data-header] [data-ghost-search] { display: none; } </style>