# Sapphire

## About

Sapphire is a Ghost theme most suitable for building niche publications and personal websites. You can use this theme to show your work, run a blog, build premium memberships for your audience and share what you do.

{% hint style="info" %}
Supports Ghost version **4.x**
{% endhint %}

**Demo:**[ sapphire.stylesheets.dev](https://sapphire.stylesheets.dev)

## Theme Installation

The first step is to **unzip** the downloaded package. Inside the new directory **sapphire**, you'll find the zipped theme and a documentation file. 

Follow these steps to upload the theme to Ghost: 

1. Login to your ghost admin dashboard (example.com/ghost).
2. Click the **settings icon** at the bottom of the left-hand side.
3. Go to **Themes** and click **Upload a theme.**
4. Select the theme file.
5. Once uploaded, click on **Activate now** button to activate the theme immediately or **Close** if you want to activate it later.

## Theme Development

The theme uses [Gulp](https://gulpjs.com/) and [Node.js](https://nodejs.org/en/) for development purposes. You'll need Node.js `v12.x.x` or `v14.x.x` installed on your machine. (If you're on a different version of Node, we recommend using NVM to manage multiple versions of Nodejs and set the correct one for developing this theme).

Once you have Node.js and [Ghost setup](https://ghost.org/docs/install/local/) ready on your machine, run the following commands from the theme root directory:

```bash
# To install node modules
npm install

# To compile and watch for changes in SCSS and JS files
npm run dev
```

Now you can edit the SCSS and JS files in `/assets/sass/` & `/assets/js/` directories. These will get compiled to `/assets/built/` automatically. 

To generate a production-ready theme zip file, run the following command. It will minify all the CSS & JS files and package the theme into `dist/<theme-name>-<version>.zip` .

```bash
# To generate production ready theme zip file.
# check the /dist folder after completion. 
npm run build
```

### LiveReload

[LiveReload](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en) chrome plugin watches over the handlebars, CSS, SCSS, and JS files and automatically reloads the browser while developing the theme.&#x20;

The configuration for LiveReload has already been done in the theme Gulpfile. You can install this chrome plugin and activate it to make your development easier.&#x20;

## Change Color Scheme & Fonts

All the colors and fonts are managed through CSS variables. You can change colors and fonts by editing the `/assets/sass/base/_variables.scss` file.&#x20;

This file contains variables for primary color, text colors, background color, and primary & secondary fonts.&#x20;

```css
:root {
    /* Colours */
    --color-primary: #222222;
    --color-primary-lighter: color-mod(var(--color-primary) tint(35%));
    --color-text: color-mod(var(--color-text-bold) l(30%));
    --color-text-secondary: #757575;
    --color-text-bold: #222;

    --color-bg: #ffffff;
    --color-bg-secondary: color-mod(var(--color-bg) shade(4%));
    --color-border: #e7e7e7;
    --color-border-lighter: #f1f1f1;

    /* Fonts */
    --font-primary: 'Work Sans', -apple-system, blinkmacsystemfont, 'Segoe UI',
        'Roboto', 'Oxygen', 'Ubuntu', 'Helvetica Neue', sans-serif;
    --font-secondary: 'Merriweather', georgia, times, serif;
    --font-normal: 400;
    --font-bold: 700;
}

```

After making the required changes, you'll have to re-compile the theme. This can be done by running the `npm run build` command. This will generate the zip file. Follow the [Theme Development guide](#theme-development) for more details on compiling the theme.

## Search

Sapphire has two options in-built for adding search:

1. [Programmable Search Engine](https://programmablesearchengine.google.com/) by Google
2. [ghostHunter](https://github.com/jamalneufeld/ghostHunter) search

You can explore other options as well from [Ghost documentation](https://ghost.org/docs/search/).

Follow these steps to activate search:&#x20;

**Step 1: Enable the search icon**&#x20;

Edit `partials/header.hbs` file and un-comment the search icon as shown in the screenshots:

![Un-comment the search icon](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDOnQf-qCGkdJ4m0k6%2Fadding-search-step-1.png?alt=media\&token=96842bd1-05cc-4279-b3c0-73fa375db088)

![Step 1: final result](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDOw-RQC4jdzGisZyz%2Fadding-search-step-1-final.png?alt=media\&token=9b7691a7-1ad7-4671-b5bd-664556fb0478)

This was the common step. Based on which search service you want to use, you can follow the steps below.&#x20;

### Google Programmable Search Engine

This is the easiest and free option available for adding search to Ghost blogs.&#x20;

Steps:&#x20;

1. Create an account on [Google Programmable Search Engine](https://programmablesearchengine.google.com/about/).&#x20;
2. Create a new search engine and copy the embeddable code.
3. Edit the `partials/search.hbs` file and paste the code in the space provided for it.&#x20;

![Paste your GPSE embed code as shown in screenshot](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDR5rGsDu91tnwevib%2Factivate-google-programmable-search-engine-on-ghost.png?alt=media\&token=2296ce72-800b-48a8-b5bd-f7551191f4e6)

![Final](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDQQc3NFSzdrvxMUSg%2Factivate-google-programmable-search-engine-on-ghost-final.png?alt=media\&token=4c5b5d58-7877-45eb-9621-5a1f1dab8ee6)

4\. Next, In the GPSE settings set the layout to full width

![](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDRU5sSfBkhsk7rVMc%2Factivate-google-programmable-search-engine-on-ghost-step-2.png?alt=media\&token=11a04b59-699a-4822-af5c-4a24d749f222)

That's it. You can now check the search on your Ghost blog.&#x20;

By default, Google will show ads on top of the search results for free accounts. You can disable that by adding a [paid API key](https://developers.google.com/custom-search/docs/paid_element#api_key).&#x20;

### GhostHunter

[GhostHunter](https://github.com/jamalneufeld/ghostHunter) is a Lunr.js based search engine. It is completely free and open-source.

{% hint style="info" %}
This option is useful for small sites that need basic site search functionality.&#x20;
{% endhint %}

Steps to add ghostHunter:&#x20;

1. Edit `default.hbs` and un-comment the ghostHunter section at the bottom.&#x20;

![](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDV6bc6eOSS-bFuefL%2Fadd-ghosthunter-search-sapphire-theme-step-1.png?alt=media\&token=ade7c19c-ece9-4512-8fb1-7d794f9fdf86)

![Final](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDVB7sEORB-Uh77Bs-%2Fadd-ghosthunter-search-sapphire-theme-step-1-final.png?alt=media\&token=6690b623-c395-4fd0-baf3-f6976484be0c)

2\. Edit `partials/search.hbs` and un-comment the ghostHunter section.&#x20;

![](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDVgg0g1sFOGnSpghQ%2Fadd-ghosthunter-search-sapphire-theme-step-2.png?alt=media\&token=40e810b5-ba4f-4fce-a93c-d55a92944f08)

3\. Create a new integration on your Ghost admin panel, and copy the content API key displayed. &#x20;

![](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDW6jjVs2eSw3JXKrl%2Fadd-ghosthunter-search-to-ghost-step-2.png?alt=media\&token=90e1173b-59c1-4b3f-9009-eb2b767d8197)

4\. Visit **Code Injection** on your Ghost admin panel, and paste the following snippet in the **Page Header** section. Update the ghosthunter\_key variable with the content API key obtained in last step.&#x20;

```markup
<script>
  	var ghosthunter_key = 'PASTE-CONTENT-API-KEY-FROM-INTEGRATION';
      //optional: set your custom ghost_root url, default is `"/ghost/api/v2"`
  	var ghost_root_url = "/ghost/api/v4"
</script>
```

![](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDHr9zpRXQMV5vLOIZ%2F-McDX71Zl7X8d7J31VH_%2Fadd-ghosthunter-search-to-ghost-step-3.png?alt=media\&token=1eb1fba8-6881-45df-b609-20877f9da3e3)

Done. You should see a functional search on your site.&#x20;

## Make Dark Mode as Default

Sapphire theme comes with three color modes – "Light", "Dark", "Warm", which users can change by clicking the color modes icon on the bottom left-hand side.&#x20;

Light mode is the default for the theme, but you can change the defaults by making the following changes:&#x20;

1. Edit `default.hbs` and add class `color-scheme--dark` or `color-scheme--warm` to the HTML tag as shown below.

   ```markup
   <html lang="{{@site.locale}}" class="color-scheme--dark">
   ```
2. Edit `assets/js/main.js` and change the `colorSchemes` array according to the sequence of color schemes that users will see.&#x20;

   ```css
   /* Dark Mode */
   const colorSchemes = ['dark', 'light', 'warm'] 
   ```

3\. Recompile the theme (Follow theme development steps for recompiling)

## Comments

The theme supports comments from services like [Disqus](https://disqus.com/), [Commento](https://commento.io/), etc.&#x20;

Look for the following space in the `post.hbs` file:

```
{{!--  
<div class="post-widget post-comments-widget post-widget--no-margin">
    If you want to embed comments, this is a good place to do it!
</div>
--}}
```

### Disqus&#x20;

Create a Disqus account and retrieve embed code for your site. Paste the embed code inside the space left for it as shown below. &#x20;

```markup
<div class="post-widget post-comments-widget post-widget--no-margin">
    
    <!-- Disqus Embed Code -->
    <div id="disqus_thread"></div>
    <script>
        /**
        *  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
        *  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables    */
        
        var disqus_config = function () {
        // this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
        this.page.identifier = "ghost-{{comment_id}}"; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
        };
        
        (function() { // DON'T EDIT BELOW THIS LINE
        var d = document, s = d.createElement('script');
        s.src = 'https://sapphire-2.disqus.com/embed.js';
        s.setAttribute('data-timestamp', +new Date());
        (d.head || d.body).appendChild(s);
        })();
    </script>
    <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
    
</div>
```

## Add Social Media Icons

Twitter, Facebook, and RSS feed icon are already implemented in the theme. To add more icons follow these steps:&#x20;

1. Download SVG of the icon from [Simple Icons](https://simpleicons.org/).&#x20;
2. In `partials/icons/` paste SVG file and change its extension to .hbs (instead of .svg)

   \
   For example, you created a file called `partials/icons/pinterest.hbs` , It should look like this:&#x20;

   ```
   <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor"><path d="M12.017 0C5.396 0 .029 5.367.029 11.987c0 5.079 3.158 9.417 7.618 11.162-.105-.949-.199-2.403.041-3.439.219-.937 1.406-5.957 1.406-5.957s-.359-.72-.359-1.781c0-1.663.967-2.911 2.168-2.911 1.024 0 1.518.769 1.518 1.688 0 1.029-.653 2.567-.992 3.992-.285 1.193.6 2.165 1.775 2.165 2.128 0 3.768-2.245 3.768-5.487 0-2.861-2.063-4.869-5.008-4.869-3.41 0-5.409 2.562-5.409 5.199 0 1.033.394 2.143.889 2.741.099.12.112.225.085.345-.09.375-.293 1.199-.334 1.363-.053.225-.172.271-.401.165-1.495-.69-2.433-2.878-2.433-4.646 0-3.776 2.748-7.252 7.92-7.252 4.158 0 7.392 2.967 7.392 6.923 0 4.135-2.607 7.462-6.233 7.462-1.214 0-2.354-.629-2.758-1.379l-.749 2.848c-.269 1.045-1.004 2.352-1.498 3.146 1.123.345 2.306.535 3.55.535 6.607 0 11.985-5.365 11.985-11.987C23.97 5.39 18.592.026 11.985.026L12.017 0z"/></svg>
   ```
3. Next, edit `partials/social-media-icons.hbs` and add the icon&#x20;

   ```markup
    <ul class="social-media-icons">
       ...other icons
       
       <li>
          <a href="https://pinterest.com/" title="Pinterest" target="_blank" rel="noopener">{{> "icons/pinterest"}}</a>
      </li>
   </ul>
   ```

## Language Translations

The theme is translation ready and includes translation files for English (en) and German (de). To add a translation for any other language, create the translation file in `locales/` directory.&#x20;

To add a new language, follow these steps:

1. Create a new file in the theme’s `locales` folder with the language [ISO Code](https://www.w3schools.com/tags/ref_language_codes.asp) code. So, if the new language is Spanish, the new file name will be `es.json`.
2. Copy the `en.json` file content into your new file and start to translate each line. The key is plain English that exists in all translation files and **should not be** changed. You should change only the value.

To set the language in Ghost, Go to **Admin > General > PUBLICATION INFO > Publication Language** and enter the language code (`es` in this example).

## &#x20;Add Custom Bio Section in Sidebar

To add the custom bio section in the header, follow these steps:

![Custom bio section in header](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-MYneJ-6r6Kt5-KjwrOK%2F-MYo4CiyTjrh_LV-CcaI%2FScreenshot%202021-04-21%20at%204.27.27%20PM.png?alt=media\&token=18e18d57-9954-4447-8462-1277d057f4fe)

1. Edit `partials/header.hbs` file and uncomment the `{{!-- {{> "header-bio"}} --}}` line as shown in screenshot:

![Step 1](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-MaX3bZ_mrmPOGOtPi4O%2F-MaX4omz4ozmlYoSWMD4%2Factivate-header-bio-step-1.png?alt=media\&token=5a313e9c-2065-46ec-8de2-6fa11e18262c)

![Step 1: final](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-MaX3bZ_mrmPOGOtPi4O%2F-MaX524GfZl50aM6RSUi%2Factivate-header-bio-step-1-final-file.png?alt=media\&token=113d14fd-8b9e-42f8-ba44-c700b571ed38)

2\. edit `partials/header-bio.hbs` and change the slug author's slug as shown in screenshots:&#x20;

![Step 2](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-MaX3bZ_mrmPOGOtPi4O%2F-MaX5NLH_y1V3PxNFt0P%2Factivate-header-bio-step-2.png?alt=media\&token=cc64024b-de1d-4730-b31d-01fb145c3753)

![Step 2: final](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-MaX3bZ_mrmPOGOtPi4O%2F-MaX5Sba-rfe8sbOJAUF%2Factivate-header-bio-step-2-final-file.png?alt=media\&token=97e21094-bf4a-4412-8146-525f16346280)

3\. Zip the theme folder, and upload it to your Ghost installation.&#x20;

{% hint style="warning" %}
**Make sure you have at least one post by this author.** Ghost sends 404 when there are no posts by the author. **The bio section won't display anything if the author has no published posts**.
{% endhint %}

## Adding Buttons in Post Content

You can add buttons to your blog post content. There are two styles available –&#x20;

1. Primary Button: Class name `.button--primary`
2. Secondary Button: Class name `.button--secondary`&#x20;

To add a button, click the "+" icon next to the line in Ghost editor and select HTML. Then add anchor tags with the class of the button you want to use. For example, to add a primary button you would paste the following HTML:&#x20;

```markup
<a href="http://example.com" class="button--primary">Primary</a>
```

Check out the [Style Guide](https://sapphire.stylesheets.dev/styling-guide/#buttons) to see how buttons look.&#x20;

## Customize Logo Dimensions

If you're using a logo on your Ghost blog, then you can follow these steps to customize the height of the logo. By default, we have set the height of the logo to *55 pixels (and 45px for mobile)*, which works well for most logos, but you might want to customize this setting depending upon your logo.&#x20;

1. First, make sure there is no empty padding around your logo's image file. If there is padding around your logo, then you can crop that using any of the image editors.&#x20;
2. Next, on your Ghost dashboard go to **Settings** > **Code Injection**, and paste the following snippet of CSS code in the **Site Header** section.&#x20;

```markup
<style>
    /* Customize height of site logo */
    /* FOR MOBILE */
    .site-logo-image {
    	max-height: 45px; /* Set height for your logo on mobile here */
    }
    
    /* FOR TABLETS & DESKTOPS */
    @media (min-width: 768px){
        .site-logo-image {
        	max-height: 55px; /* Set height for your logo on tablets & desktops here */
        }
    }
</style>
```

3\. Edit the values of max-height property according to your needs. You can change these values and experiment with them to see what works for you.&#x20;

Note: You can make this change directly in CSS files as well, but this is easier because you won't have to make these changes again when any new update is released on the theme.&#x20;

## Remove Footer Attribution Text

To remove the "Published with Ghost & Sapphire" text from the footer, you can edit `partials/footer.hbs` file and delete the lines (12-14) containing this text.&#x20;

## Add a Tags List Page

To add a tags list view follow these steps:&#x20;

1. Create a new page. You can set the title to anything you want. We'll call it Topics.&#x20;
2. Next, select the template to "Tags" and save the page.&#x20;

![Create a page, and set the template to Tags](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDAei2hN_apZtMl5DV%2F-McDFJXsBAjH_xL0DzQt%2Fadd-tags-view.png?alt=media\&token=38e53e51-19cd-41e0-87b7-7090df47a4e2)

Done. You can now visit this page to see all your tags rendered in descending order of the number of posts associated with them.&#x20;

![Tags archive view](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDAei2hN_apZtMl5DV%2F-McDFn16UDr1ka_BysGS%2Fsapphire-tags-view.png?alt=media\&token=ace2cb9b-5e9c-4a61-9789-fdfc239cf69f)

## Add a Posts Archive View

To add a posts archive view, follow these steps:&#x20;

1. Create a page. You can set the title to anything you want.&#x20;
2. Next, from the settings menu, set the template to "Posts Archive" and save the page.

![Create a page, and set the template to Posts Archive](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDFz_oKytWc0rrT8D3%2F-McDGpFIdA6gQvUeoZzE%2Fadd-posts-archive-view.png?alt=media\&token=1e5b97b8-bdeb-443d-aeb5-d6ded94c6b4f)

That's it. You can now visit that page to view your posts archive.

Pro Tip: You can add the Featured Image and Excerpt as well to show them on this view. &#x20;

![Post Archive Page](https://2725273375-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M30NeNS-akxU0zYyKJm%2F-McDFz_oKytWc0rrT8D3%2F-McDHEHKbc0ctfglOvpy%2Fsapphire-posts-archive-view.png?alt=media\&token=b4f4a8c2-a492-48e5-ba0f-78e6d1bbaf6d)

## Keeping Your Theme Updated

Keeping your theme updated with its latest releases can be a little challenging if you have lots of customizations. We would recommend the following ways:

* Use Git version control. You can create two branches. One will have your customized theme and one will have the original theme. When an update is released, you can commit the update to the original branch. Then you would switch over to your customization branch and rebase it with the original branch.
* Another choice is to manually apply the updates to files changed from the [Changelog](https://docs.stylesheets.dev/sapphire/changelog).&#x20;
* Another good practice is to keep third-party scripts like Google Analytics in code injection.&#x20;

## Sources and Credits

Thanks to the following services and libraries used in building this theme:

* [Unsplash](https://unsplash.com/) for stock images on demo site.
* [Google Fonts](https://fonts.google.com/) for fonts.&#x20;
* [PrismJs](https://prismjs.com/) for code highlighting.&#x20;
* [Simple Icons](https://simpleicons.org/) for social media brand icons.
* [Feather Icons](https://feathericons.com/) for utility icons.

## Support

Thank you for using our themes. If you have any questions that are beyond the scope of this documentation, please feel free to email us at <support@stylesheets.dev>. We'll do our best to assist you.

Thanks so much!