Bokeh Theme Documentation

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

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 bokeh.zip file.
After the upload is complete click Activate

Routes Setup

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

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.
Under Beta features click on Upload routes YAML button and select the file from the root directory of the theme.

Ghost routes.yaml

The routing file defines the following custom pages and collection:

/tags/ - the homepage and main collection
/recommendations/ - the custom membership 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 & Branding ( yoursite.com/ghost/#/settings/design/)

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

Site-wide settings
Homepage settings
Post settings

Site-wide settings

Color scheme - set the default color scheme (system, light, dark, wood, orchid, mint, midnight)
Font headings - select from a predefined list of font families for the headings or use system fonts
Font body - select from a predefined list of font families for the body text or use system fonts
Dark theme logo - upload the site logo for the dark version of the theme
Grain background - enable or disable the grain background effect on the site
Header CTA button text - set the text for the custom CTA button in the header & hero
Header CTA button link - set the link for the custom CTA button in the header & hero
Header navigation - display the primary navigation in the left side of the header

Homepage settings

Hero headline - set the hero headline
Hero description - set the hero description
Hero image format - set the hero image style (square, portrait, landscape, auto)
Featured posts section - enable or disable the featured posts slider
Featured tags - set a list of tags to be rendered on the homepage
Featured tags style - set the style for the featured tags (cards, sections)
Post feed style - set the preferred post feed style(1-column, 2-column, 3-column, 4-column, bento-grid, or hidden)
Post card image aspect ratio - set the post card image aspect ratio(16/9, 4/3, 3/2, 1/1, 2/3, 3/4, auto)
Post card content - set the post card content style(stacked, overlay, overlay-on-hover)
Show post card tags - show or hide the post tags

Post settings

Default post template - set the default style for your posts
Enable image lightbox - enable or disable the image lighbox (applied for image cards and gallery images)

Homepage

The homepage is defined in the home.hbs file and includes a hero section, a featured post slider, a list of tags, and a post feed (besides the default header and footer elements)

Hero

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

Hero headline - the hero section title
Hero description - the hero section description
- here you can also use HTML elements like links, bold text, etc:
Hero image format - the hero section image format
- the image can be square, portrait, landscape, or auto

Additionally, the Header CTA button text and Header CTA button link settings (Site-wide), will be rendered under the hero description.

CTA button in the header & hero

Featured posts

To enable or disable the featured posts slider, go to Settings > Design & Branding > Homepage. Click the Featured posts section toggle button.

The featured posts section markup is implemented in the partials/feauted-posts.hbs file. The slider function is using the Glidejs library.

By default, all featured posts are fetched and rendered within the slider. Navigating through the list of posts is possible either using the arrows in the top right corner, or the bullet navigation below the slider.

Featured tags

To showcase specific tags on the homepage, you have to set the Featured tags from Settings > Design & Branding > Homepage.

Important: use the tag slugs separated by commas, and no spaces.

Example from the demo:

portrait,wedding,fashion,nature

You can find the slug of a tag in your Admin > Tags, opening a specific tag and check the Slug field.

There is a second setting, for controlling how the tag is rendered, called Featured tags style. It comes with two options:

cards - this option will render tag cards, with a link to the individual tag pages. You can see it live on the demo.
sections - this option will render an entire section for each tag with up to 3 posts. You can see it live on the demo.

Post feed

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

1-column - each article occupies the full-width available. Demo ->
2-column - articles are rendered in a 2-column grid. Demo ->
3-column - articles are rendered in a 3-column grid. Demo ->
4-column - articles are rendered in a 4-column grid.
bento-grid - articles are rendered in a 2-column bento style grid. Demo ->

The post cards can also be customized, see the section below for details.

Post card

The post card markup is defined in partials/post-card.hbs file, with some settings you can do from Settings > Design > Homepage.

Post card image aspect ratio - the following options are available:

16/9 aspect ratio
4/3 aspect ratio
3/2 aspect ratio
1/1 aspect ratio
2/3 aspect ratio
3/4 aspect ratio
auto - the uploaded image aspect ratio will be respected

Post card content - set the appearance of the content (title) in post cards, with the following options:

overlay - show the title on top of the image (with a darkened background)
stacked - show the title below the image
overlay-on-hover - don't show the title by default, only show it on top of the image when you hover over the card

Post card show tags - show/hide the tags on the post card

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

- Home page 1, - Home page 2 and - Home page 3 will belong to the Home pages item

Bokeh dropdown menu setup

CTA section

To create the CTA section above the footer, follow the steps below:

Go to Admin > Pages and create a new page
Add the internal tag #cta to the page (must start with # and the slug of the tag must be hash-cta)
Upload a featured image which will be rendered on the left side.
Add your content, including, text, buttons, links.

Bokeh CTA setup

Bokeh CTA

The CTA section, when set up, will be displayed on every page, and regardless of member status.

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.

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

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

The data property can be used to make templates dynamic that otherwise would be static.

Recommendations

Defined by the recommendations.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.

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

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

Custom templates

The theme comes with several custom templates, which can be selected for individual posts from the Post Settings menu.

You can choose from the following templates:

custom-with-auto-image.hbs - a template where the feature image kis displayed in it's original aspect ratio
custom-with-landscape-image.hbs - a template where the feature image is rendered in 3/2 aspect ratio
custom-with-portrait-image.hbs - a template where the feature image is rendered in 3/4 aspect ratio
custom-with-square-image.hbs - a template where the feature image is rendered in 1/1 aspect ratio

To set the default post template, go to Settings > Design > Post and set the Default post template value, with the template you prefer.

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

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
wood
orchid
mint
midnight

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% 30%);
    --color-typography-reverse: hsl(0 0% 85%);
    --color-background: hsl(0 0% 100%);
    --color-background-tone: hsl(0 0% 98%);
    --color-background-reverse: hsl(0 0% 12%);
    --color-border: hsl(0 0% 92%);
    --color-border-reverse: hsl(0 0% 20%);
  }
</style>

To change the dark theme:

<style>
  html[data-color-scheme="dark"] {
    --color-typography: hsl(0 0% 85%);
    --color-typography-tone: hsl(0 0% 70%);
    --color-typography-reverse: hsl(0 0% 15%);
    --color-background: hsl(0 0% 12%);
    --color-background-tone: hsl(0 0% 15%);
    --color-background-reverse: hsl(0 0% 98%);
    --color-border: hsl(0 0% 20%);
    --color-border-reverse: hsl(0 0% 92%);
  }
</style>

To change the wood theme:

<style>
  [data-color-scheme="wood"]:root {
    --color-typography: hsl(33 60% 15%);
    --color-typography-tone: hsl(33 60% 25%);
    --color-typography-reverse: hsl(33 60% 90%);
    --color-background: hsl(33 60% 80%);
    --color-background-tone: hsl(33 60% 75%);
    --color-background-reverse: hsl(33 60% 10%);
    --color-border: hsl(33 60% 70%);
    --color-border-reverse: hsl(33 60% 30%);
  }
</style>

Some useful tools for choosing colors and gradients:

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

When it comes to aspect ratios, the post card images can have different format, based on your design settings, the default value being 1/1.

The aspect ratio in the post layouts differs based on the template set for each individual post.

Comments

Bokeh 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 > Access > Commenting.

By default, native comments are not active, so you have to select either

All members or Paid-members only

Google 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)
Inter
Cinzel
Cormorant
DM Serif Display
Philosopher - the default option
Playfair Display
Abril Fatface
DM Sans
Lexend
Inconsolata

Body font options:

System
Inter
Lato
Lora
Inconsolata
Quattrocento

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

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

Facebook
X(Twitter)

For adding other social links you have two options (either one will work):

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.

Create a page with slug: socials.

In this page create a new HTML card and add your links using <a> tags. Here's an example from the demo:

<a href="https://facebook.com" class="hover:text-brand" aria-label="Facebook">
  <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5 stroke-2 icon icon-tabler icon-tabler-brand-facebook" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M7 10v4h3v7h4v-7h3l1 -4h-4v-2a1 1 0 0 1 1 -1h3v-4h-3a5 5 0 0 0 -5 5v2h-3"></path>
  </svg>
</a>

<a href="https://instagram.com" class="hover:text-brand" aria-label="Instagram">
  <svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6 stroke-2 icon icon-tabler icon-tabler-brand-instagram" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M4 4m0 4a4 4 0 0 1 4 -4h8a4 4 0 0 1 4 4v8a4 4 0 0 1 -4 4h-8a4 4 0 0 1 -4 -4z"></path>
    <path d="M12 12m-3 0a3 3 0 1 0 6 0a3 3 0 1 0 -6 0"></path>
    <path d="M16.5 7.5l0 .01"></path>
  </svg>
</a>

<a href="https://pinterest.com" class="hover:text-brand" aria-label="Pinterest">
  <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5 stroke-2 icon icon-tabler icon-tabler-brand-pinterest" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M8 20l4 -9"></path>
    <path d="M10.7 14c.437 1.263 1.43 2 2.55 2c2.071 0 3.75 -1.554 3.75 -4a5 5 0 1 0 -9.7 1.7"></path>
    <path d="M12 12m-9 0a9 9 0 1 0 18 0a9 9 0 1 0 -18 0"></path>
  </svg>
</a>

<a href="https://unsplash.com" class="hover:text-brand" aria-label="Unsplash">
  <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5 stroke-2 icon icon-tabler icon-tabler-brand-unsplash" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
    <path d="M4 11h5v4h6v-4h5v9h-16zm5 -7h6v4h-6z"></path>
  </svg>
</a>

Icons are from Tabler Icons.

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)

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

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.
npm run build (vite build) The build script will start the build process.
npm run test (gscan . --verbose) The test will test the theme using gscan the official Ghost test tool.
npm run zip The zip script will create a zip file in the dist directory.

Support

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

Contact - Feedback

Bokeh Documentation

Bokeh v1.1.0 for Ghost 5.x

Install the theme

Routes Setup

Custom Settings

Site-wide settings

Homepage settings

Post settings

Homepage

Hero

Featured posts

Featured tags

Post feed

Post card

CTA section

Custom Pages

Tags

Recommendations

Custom templates

Color customization

Ghost config

Posts per page

Image sizes

Comments

Google Fonts

Icons

Translations

Theme development

Support

Bokeh Documentation

Bokeh v1.1.0 for Ghost 5.x

Install the theme

Routes Setup

Custom Settings

Site-wide settings

Homepage settings

Post settings

Homepage

Hero

Featured posts

Featured tags

Post feed

Post card

Navigation dropdown

CTA section

Custom Pages

Tags

Recommendations

Custom templates

Color customization

Ghost config

Posts per page

Image sizes

Comments

Google Fonts

Icons

Social links

Social sharing

Translations

Theme development

Support