Shiro

Version 1.0.0

Introduction

This guide explains how to install, set up, and customize the Shiro theme for Ghost. It assumes basic familiarity with Ghost. For general Ghost help, check out the official Ghost documentation.

Setup

Installing the Theme

To get Shiro up and running on your Ghost site:

  1. Log in to your Ghost Admin panel.
  2. Go to Settings > Design & branding > Customize.
  3. Click Change theme at the bottom right.
  4. Choose Upload theme and select the Shiro theme zip file.
  5. Click Activate to apply the theme.

Removing the Theme

If you need to remove Shiro:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Click Change theme at the bottom right.
  3. Find Shiro in the theme list.
  4. Click the ... next to Activate.
  5. Select Delete and confirm.

Note: You can’t delete an active theme. Switch to another theme first if needed.

Updating the Theme

To keep Shiro current with the latest features and fixes:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Click Change theme at the bottom right.
  3. Upload the new Shiro zip file as described in the installation process.
  4. Activate the updated theme.

Important: Updating will overwrite any changes made directly to theme files. Back up your customizations before updating.

Customization

Your logo is a key part of your site’s identity. Here’s how to set it up:

  1. In Ghost Admin, go to Settings > Design & branding.
  2. In the Brand tab, find Publication logo.
  3. Click Upload logo and choose your image.
  4. Click Save.

Tip: Use a logo at least 60px tall with a transparent background for best results.

Logo Inversion for Dark Themes

Shiro can automatically adjust your logo for dark themes:

  1. Go to Settings > Design & branding > Customize.
  2. Find Invert logo colors when dark theme in the Site wide settings.
  3. Toggle the switch on or off.
  4. Click Save.

Fonts

Fonts play a crucial role in your site’s readability and style. To change the font:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Site-wide section.
  3. Find the Font family dropdown.
  4. Choose your preferred font.
  5. Click Save.

To use a custom font:

  1. Go to Settings > Code injection.
  2. In the Site Header section, add the font link and CSS. For example:
<link href="https://fonts.googleapis.com/css2?family=Your+Font+Name&display=swap" rel="stylesheet">
<style>
  :root {
    --font-family: 'Your Font Name', sans-serif;
  }
</style>
  1. Click Save.

Accent Color

The accent color highlights important elements across your site. To change it:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Brand section.
  3. Find Accent color.
  4. Click the color swatch and choose a new color.
  5. Click Save.

Color Scheme

Shiro offers various color schemes to match your brand and content style. To change the scheme:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Site-wide section.
  3. Find the Color scheme dropdown.
  4. Choose your preferred scheme.
  5. Click Save.

Available schemes: Light, Zensen, Sakura, Botan, Blau, Midnight, Dark

Dark Color Scheme

Shiro can automatically switch to a dark color scheme based on the user’s system preferences. To enable this feature:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Site-wide section.
  3. Find Enable dark color scheme and toggle it on.
  4. A new option Dark color scheme will appear. Select your preferred dark scheme.
  5. Optionally, you can enable Invert logo colors when dark color scheme to automatically adjust your logo for dark themes.
  6. Click Save.

When enabled, the site will use the selected dark color scheme when the user’s system is set to dark mode. This provides a seamless experience for users who prefer dark interfaces, especially in low-light environments.

Effective navigation helps readers explore your content easily. Shiro supports primary (header) and secondary (footer) navigation.

Primary Navigation (Header)

  1. In Ghost Admin, go to Settings > Navigation.
  2. Edit the “Primary navigation” section.
  3. Click Save.

Secondary Navigation (Footer)

  1. In Ghost Admin, go to Settings > Navigation.
  2. Edit the “Secondary navigation” section.
  3. Click Save.

Social Icons

Connect with your audience by adding social media icons to your footer:

  1. In Ghost Admin, go to Settings > Navigation.
  2. In “Secondary navigation”, click “Add item”.
  3. For the label, use the lowercase name of the social platform (e.g., “twitter”, “facebook”).
  4. For the URL, paste your profile link.
  5. Click Save.

Supported platforms: discord, dribbble, facebook, flickr, github, gitlab, instagram, linkedin, mastodon, medium, messenger, pinterest, quora, reddit, skype, snapchat, soundcloud, spotify, telegram, threads, tiktok, tumblr, twitch, twitter, vimeo, wechat, whatsapp, x, youtube

Pagination

Shiro offers three pagination types to control how additional posts are loaded. This feature lets you customize your site’s browsing experience to suit your readers’ preferences:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Site-wide section.
  3. Find Pagination type.
  4. Choose Classic, Infinite Scroll, or Load More.
  5. Click Save.

App Mode

App Mode allows your site to be installed on Android and iOS devices as a Progressive Web App (PWA). This can improve user experience and engagement by providing a more app-like interface on mobile devices.

To enable App Mode:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find the “Enable app mode” option under the “Site-wide” settings.
  3. Toggle the switch to enable App Mode.
  4. Click “Save” to apply the changes.

When enabled, visitors using compatible mobile browsers will be prompted to add your site to their home screen, creating an app-like shortcut for easy access.

Hero Section

The hero section is the first thing visitors see on your homepage. Customize it to make a strong first impression:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Cover image position.
  3. Choose Background, Left, or Right.
  4. Click Save.

To update site title and description:

  1. In Ghost Admin, go to Settings > General.
  2. Edit Site title and Site description.
  3. Click Save.

To set a cover image:

  1. In Ghost Admin, go to Settings > Design & branding.
  2. In Brand, find Cover image.
  3. Click Upload cover image.
  4. Click Save.

Highlight your best content by displaying featured posts on your homepage:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Homepage, find Show Featured Posts Section.
  3. Toggle the switch on or off.
  4. Click Save.

To feature a post:

  1. In Ghost Admin, go to Posts.
  2. Select a post.
  3. In the sidebar, find Feature this post.
  4. Toggle the switch on.
  5. Click Update.

Hiding Featured Posts from Main Listings

For advanced users who want to remove featured posts from the main collection:

  1. In Ghost Admin, go to Settings > Labs.
  2. Click on the Beta features tab.
  3. Find the Routes section.
  4. Upload a routes.yaml file with the following content:
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}/

This configuration creates a separate /featured/ URL for all featured posts and removes them from the main collection. After applying these changes, featured posts will only appear in the dedicated featured section and not in the main post listings.

Encourage readers to explore more of your content by showing related posts:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Show Related Posts.
  3. Toggle the switch on or off.
  4. Click Save.

Scroll Indicator

Help readers track their progress through your posts with a scroll indicator:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Enable Scroll Indicator.
  3. Toggle the switch on or off.
  4. Click Save.

Syntax Highlighting

Make your code snippets more readable with syntax highlighting:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Enable Syntax Highlighting.
  3. Toggle the switch on or off.
  4. Click Save.

Comments

Engage with your readers through comments. Choose between Ghost’s built-in system or Disqus:

For Ghost’s built-in comments:

  1. In Ghost Admin, go to Settings > Membership.
  2. Click Edit in Access.
  3. Choose who can comment: Nobody, Paid members, or All members.

For Disqus comments:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Disqus Comments Shortname.
  3. Enter your Disqus shortname.
  4. Click Save.

Copyright Text

Customize your footer’s copyright notice:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Site-wide, find Copyright Text.
  3. Enter your desired text.
  4. Click Save.

If left empty, it will show: ”© [Your Site Title] [Current Year]. Published with Ghost.”

Post Styles

The theme offers 9 distinct post styles to customize the appearance of individual posts.

Default

Default

Default + Background

Default + Background

Left Image

Left Image

Left Image + Background

Left Image + Background

Right Image

Right Image

Right Image + Background

Right Image + Background

Excerpt first + Cover

Excerpt first + Cover

Excerpt first + Cover + Background

Excerpt first + Cover + Background

Background Only

Background Only

Wide Post Cards

To make a post card appear wide in the feed, add the tag #mod-wide-card to the post.

Custom Color Scheme for Post/Page

Each post or page can have a specific color scheme. To apply different color scheme try adding one of these tags to the post or page

  • #mod-theme-zensen
  • #mod-theme-blau
  • #mod-theme-sakura
  • #mod-theme-botan
  • #mod-theme-midnight
  • #mod-theme-dark

Custom Pages

Tags

A Tags page helps readers discover content by presenting all tags used on your site. This theme offers two variations: a grid layout and a list layout.

To create a Tags page:

  1. In Ghost Admin, create a new page.
  2. Give it a title (e.g., “Tags” or “Topics”).
  3. Open the page settings (gear icon in the top right).
  4. In the Template dropdown, select either Tags Page [Grid] or Tags Page [List].
  5. Publish the page.

Tags Page [Grid]

Tags Page [Grid]

Tags Page [List]

Tags Page [List]

The Grid layout presents tags as cards, while the List layout offers a alternative view. Choose the layout that best fits your site’s style and number of tags.

To customize tag appearance, edit individual tags in Ghost Admin to add descriptions, feature images, or accent colors. Remember to add your new Tags page to your site’s navigation menu for easy access.

Contact

The Contact page allows visitors to send messages directly through your site. It uses Formspree or Getform for form submissions.

To create a Contact page:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Contact form url and enter your Formspree or Getform URL.
  3. Create a new page and select Contact from the Template dropdown.
  4. Publish the page.

Customize the page content to include additional contact information or instructions as needed.

Empty Template

The Empty template provides a blank canvas without header or footer. Use it for landing pages or custom layouts where you need full control over the page content.

To use the Empty template:

  1. Create a new page in Ghost Admin.
  2. In page settings, select “Empty” from the Template dropdown.
  3. Add your content and publish.

This template is ideal for creating unique, standalone pages within your Ghost site.

Members

Ghost’s Members feature allows you to turn your site into a membership business with sign-ups, paid subscriptions, and email newsletters. By default, Ghost uses Portal, a flexible membership framework, to handle all member-related interactions.

Ghost’s Portal system provides a seamless, out-of-the-box solution for membership functionality. It includes:

  • Sign-up and sign-in flows
  • Account management
  • Subscription handling
  • Newsletter subscriptions

With Portal, there’s no need to create separate pages for these functions. Ghost automatically injects the necessary components into your site.

To customize Portal’s appearance:

  1. In Ghost Admin, go to Settings > Membership.
  2. Scroll down to the Portal settings section.
  3. Here you can customize colors, button text, signup terms, and more.

While Portal provides a complete solution, some users might prefer to create custom member pages for a more tailored experience. If you choose this route, you can use the provided templates to create the following pages:

Account Page

The Account page shows members their account type and subscription details.

To create a custom Account page:

  1. In Ghost Admin, create a new page.
  2. Give it a title (e.g., “Account”).
  3. Open the page settings (gear icon in the top right).
  4. Set the page URL to /account/.
  5. In the Template dropdown, select “Account”.
  6. Publish the page.

Signup & Signin Pages

These pages allow visitors to create accounts or log in to access member-only content.

To create custom Signup and Signin pages:

  1. Create two new pages in Ghost Admin.
  2. For the Signin page:
    • Set the page URL to /signin/.
    • Select “Signin” from the Template dropdown.
  3. For the Signup page:
    • Set the page URL to /signup/.
    • Select “Signup” from the Template dropdown.
  4. Publish both pages.

Membership Page

This page helps visitors compare your different pricing plans.

To create a custom Membership page:

  1. Create a new page in Ghost Admin.
  2. Give it a title (e.g., “Membership” or “Join Us”).
  3. In the page settings, select “Membership” from the Template dropdown.
  4. Publish the page.

To add pricing tiers:

  1. Go to Ghost Admin > Settings > Tiers.
  2. Connect your Stripe account if you haven’t already.
  3. Click + Add tier to create a new pricing tier.
  4. Fill in the tier details (name, description, prices, benefits).
  5. Save the new tier.
  6. In Settings > Tiers > Portal settings, choose which tiers to display on your site.

To add an FAQ section to your Membership page, use the Toggle card in the Ghost editor to create FAQ items in the page content.

Note: Choosing Between Portal and Custom Pages

  • Use Portal if you want a quick, easy, and automatically maintained membership system.
  • Consider custom pages if you need more control over the design and layout of your membership flows.

Advanced

This section covers more technical aspects of working with the theme, including editing theme files and language translations.

Editing Theme Files

To edit the theme files:

  1. Download the theme ZIP file from Ghost Admin.
  2. Unzip the file on your local machine.
  3. Open the theme folder in your preferred code editor.

The theme uses SCSS for styling and TypeScript for scripts. You’ll need to set up a development environment to compile these files.

Setting Up the Development Environment

  1. Ensure you have Node.js installed on your system.
  2. Open a terminal/command prompt in the theme folder.
  3. Run npm install to install the required dependencies.

Working with SCSS and TypeScript

The theme uses Parcel to bundle and compile SCSS and TypeScript files. To work with these files:

  1. Make your changes in the styles/*.scss or scripts/*.ts files.
  2. Run npm run dev to start Parcel in watch mode. This will automatically compile your changes.
  3. To build for production, run npm run build.

Building and Testing

After making changes:

  1. Run npm run build to create a production-ready version of the theme.
  2. Use npm run gscan to check your theme for Ghost compatibility issues.
  3. Zip the theme folder and upload it to your Ghost site to test.

Remember to thoroughly test all changes across different devices and browsers before deploying to a live site.

Important Files and Folders

  • styles/: Contains all SCSS files
  • scripts/: Contains all TypeScript files
  • partials/: Contains reusable Handlebars template parts
  • locales/: Contains language translation files

Language Translations

This theme is translated into 46 languages. The translation files are located in the locales/ folder.

  • 🇿🇦 Afrikaans af
  • 🇧🇬 Bulgarian bg
  • 🇧🇦 Bosnian bs
  • 🇪🇸 Catalan ca
  • 🇨🇿 Czech cs
  • 🇩🇰 Danish da
  • 🇨🇭 Swiss German de-CH
  • 🇩🇪 German de
  • 🇬🇷 Greek el
  • 🇬🇧 English en
  • 🌍 Esperanto eo
  • 🇪🇸 Spanish es
  • 🇫🇮 Finnish fi
  • 🇫🇷 French fr
  • 🏴󠁧󠁢󠁳󠁣󠁴󠁿 Scottish Gaelic gd
  • 🇭🇷 Croatian hr
  • 🇭🇺 Hungarian hu
  • 🇮🇩 Indonesian id
  • 🇮🇸 Icelandic is
  • 🇮🇹 Italian it
  • 🇯🇵 Japanese ja
  • 🇰🇷 Korean ko
  • 🇱🇹 Lithuanian lt
  • 🇲🇰 Macedonian mk
  • 🇲🇳 Mongolian mn
  • 🇲🇾 Malay ms
  • 🇳🇱 Dutch nl
  • 🇳🇴 Norwegian Nynorsk nn
  • 🇳🇴 Norwegian no
  • 🇵🇱 Polish pl
  • 🇧🇷 Brazilian Portuguese pt-BR
  • 🇵🇹 Portuguese pt
  • 🇷🇴 Romanian ro
  • 🇱🇰 Sinhala si
  • 🇸🇰 Slovak sk
  • 🇸🇮 Slovenian sl
  • 🇦🇱 Albanian sq
  • 🇷🇸 Serbian sr
  • 🇸🇪 Swedish sv
  • 🇹🇭 Thai th
  • 🇹🇷 Turkish tr
  • 🇺🇦 Ukrainian uk
  • 🇺🇿 Uzbek uz
  • 🇻🇳 Vietnamese vi
  • 🇹🇼 Traditional Chinese zh-Hant
  • 🇨🇳 Chinese zh

To use a different language:

  1. In Ghost Admin, go to Settings > General.
  2. Set the “Site language” to the desired language code (e.g., “es” for Spanish).

To modify translations:

  1. Open the corresponding language file in the locales/ folder (e.g., es.json for Spanish).
  2. Edit the translations as needed.
  3. Save the file and rebuild the theme.