About

Ampersand is a multipurpose Ghost blogging theme. You can use it to build blogs, online membership-based publications, and a lot more.

It is fully customizable and comes with two different navigation layouts and hero types.

• Two header navigations styles

• Two homepage hero styles

Fully customizable typography and color palette. The color scheme is fully customizable directly from your Ghost dashboard with no coding required at all.

Extra features:

• Membership plans page

• Posts archive page

• Tags archive page

• Search integrations available for:

  • Google programmable search engine

  • GhostHunter.js

• Prismjs code highlighting

• Photo zoom

• Comments

• Light & dark modes

Demos

1. ​Default​

2. ​Header Type 2​

3. ​Hero Full-Width Image​

Theme Installation

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 (the theme file will look something like this - ampersand-x.x.x)

5. Once uploaded, click on Activate now button to activate the theme immediately or Close if you want to activate it later.

Change Color Scheme & Fonts

Color Scheme

Changing the color scheme on the Ampersand theme is easy and can be done directly from the Ghost settings page:

1. Log in to your Ghost admin panel, and click on the Settings icon at the bottom right site

2. Go to Branding settings and set the Accent color.

If you want more control over the color scheme, you can modify the assets/sass/base/_variables.scss file. It contains all the CSS variables as shown below. After making changes in SCSS files, you'll have to compile the theme. Look into the Theme Development section to learn more about it.

:root {
    /* Colors */
    --color-primary: var(--ghost-accent-color);
​
    --color-text-bold: #222;
    --color-text: #323030;
    --color-text-lighter: hsl(0deg 0% 44%);
    --color-text-lightest: hsl(0deg 0% 58%);
​
    --color-bg: #ffffff;
    --color-bg-secondary: #fafafa;
    --color-bg-tertiary: #f0f0f0;
​
    --color-border: #e5e5e5;
    --color-border-darker: #d0d0d0;
​
    --color-error: hsl(4deg 90% 58%);
​
    /* General Colors */
    --white: #fff;
    --white-secondary: #eaeaea;
    --light-grey: hsl(0deg 0% 96%);
    --grey: hsl(0deg 0% 90%);
    --black: hsl(0deg 0% 0%);
​
    /* Fonts */
    --font-primary: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI',
        Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
        'Segoe UI Symbol';
    --font-secondary: 'Merriweather', georgia, times, serif; // For headings & links
​
    /* Font Weights */
    --weight-normal: 400;
    --weight-medium: 500;
    --weight-bold: 600;
    --weight-headings: 700;
​
    /* Radius */
    --radius-normal: 0px;
    --radius-medium: 4px;
    --radius-large: 8px;
}

Fonts

The theme has two types of fonts:

1. Primary font: which is used on paragraphs and links

2. Secondary font: which is used on headings.

To modify these fonts, first, you need to load the appropriate fonts in the theme. We are using Google Fonts to load the fonts in default.hbs file head section.

Next, update the assets/sass/base/_variables.scss file and update the --font-primary and --font-secondary variables.

After making these changes, follow the Theme Development section to re-compile the CSS files.

Search

The theme comes with Google Programmable Search Engine and GhostHunter search libraries. But you can use any other search service as well with the same search window and search icon.

Google Programmable Search Engine

Follow these steps to use GPSE search on your site:

1. First, enable the search icon in the navigation by editing partials/header.hbs file and un-commenting the search icon.

2. Create an account on Google Programmable Search Engine.

3. Create a new search engine and copy the embeddable code.

4. Edit the partials/search.hbs file and paste the embed code in the space provided for it.

5. Zip your theme and upload it to Ghost

By default, GPSE will show ads above your search results, but you can go for the paid plan to remove those ads.

GhostHunter

GhostHunter.js is another popular search option for Ghost users. This option is most suitable for small blogs with limited blog posts. Steps for activating ghostHunter search:

1. Enable the search icon by un-commenting it in partials/header.hbs file.

2. Edit default.hbs and un-comment the ghostHunter section at the bottom.

3. Edit partials/search.hbs and un-comment the ghostHunter section.

4. Zip your theme and upload it to Ghost.

5. Create a new integration on your Ghost admin panel, and copy the content API key displayed there.

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

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

Comments

The theme comes with space left for integrating comments. Here's a short guide on how to integrate Disqus comments, but the same can be followed for integrating comments from any other service.

Steps:

1. Edit post.hbs file and un-comment the {{> "post-widget-comments"}} line.

2. Paste the comment embed script in the space provided for it in partials/post-widget-comments.hbs file.

3. If you're using Disqus, then you can display the comment count as well by including the Disqus counts' script at the end.

Add Social Media Icons

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

1. Download SVG of the icon from Simple Icons.

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:

    <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

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

Change Header

To use the navigation header shown here, follow the steps below:

1. Edit the default.hbs file and un-comment the line containing {{> "header-type-b"}} .

2. Comment out the default header on the line containing {{> "header"}}

3. Zip and upload the theme to your Ghost dashboard.

Change Hero Layout

The theme comes with three different Hero types:

1. Default

   1. With image

   2. Without image

2. Full-width image

Add Default Hero

To add the default hero:

1. Go to your Ghost admin panel, and create a new page

2. The title of the page will be used as the Hero title

3. Add content on the page. This content will be shown in the hero description. Here you can use links, bold, italics, etc.

4. Set the Page URL to "home"

5. Add the feature image or leave it empty if you don't need image on hero.

6. Publish the page and you'd see the hero added to your home page.

Add Full-Width Image Hero

To add a full-width image hero, follow these steps:

1. Edit index.hbs and un-comment the line containing {{> "hero-image-full"}} .

2. Comment-out the {{> "hero"}} line.

3. Save and upload the zipped theme to Ghost

4. Go to your Ghost admin panel, and create a new page

5. The title of the page will be used as the Hero title

6. Add content on the page. This content will be shown in the hero description. Here you can use links, bold, italics, etc.

7. Set the Page URL to "home"

8. Add the feature image or leave it empty if you don't need image on hero.

9. Publish the page and you'd see the hero added to your home page.

Membership Plans Page

To add a membership plans page, create a new page. Set the title as "Membership" or anything else of your choice. From the settings menu, set the Template to Membership plans.

Posts Archive Page

To add a posts archive page, create a new page. Set the title to anything of your choice. From the settings menu, set the Template to Posts archive.

Tags List Page

To add a tags list page, create a new page. Set the title to "Tags" or anything of your choice. From the settings menu, set the Template to Tags.

Customize Subscribe CTAs

The theme comes with Subscription call-to-action widgets on the homepage sidebar and at the end of the post view as well.

By default, the CTA will read "Join the newsletter to receive the latest updates in your inbox" and show an email input field.

But you can change this to show subscription plans and subscribe/learn more buttons, to read something like "Become a member for $5/month or $50/year and get unlimited access to the great stories you won’t find anywhere else."

You can customize this by following this video tutorial:

These subscribe CTAs with membership plans will automatically pull the plan amounts from Ghost settings. The subscription message to the user based on if they are a paid subscriber/un-paid subscriber/not-subscribed will change.

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.

To add a new language, follow these steps:

1. Create a new file in the theme’s locales folder with the language ISO Code 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).

Adding Buttons in Post Content

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

1. Primary Button: Class name .button--primary

2. Secondary Button: Class name .button--secondary

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:

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

Check out the Style Guide to see how buttons look.

Add Table of Contents

To show a table of contents on a post, simply set the template to "Table of contents" from settings menu. See the screenshot below:

Theme Development

The theme uses Gulp and Node.js 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 ready on your machine, run the following commands from the theme root directory:

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

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

LiveReload

​LiveReload chrome plugin watches over the handlebars, CSS, SCSS, and JS files and automatically reloads the browser while developing the theme.

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.

Modify Footer Copyright Text

You can modify the footer copyright & attribution text by modifying the partials/footer.hbs file at lines 25 & 28.

Hide Portal Subscribe Button

The theme already has a subscribe button in header navigation, so you might want to hide the default portal button (at bottom right corner). Follow the following tutorial to hide it:

Disable Memberships Portal on Ghost

In the video below, see how you can disable the memberships portal and how Ampersand theme will look like in that case:

Make Dark Mode as Default

Ampersand theme comes with two color modes – "Light" & "Dark", which users can change by clicking the color modes toggle switch in footer.

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

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

    <html lang="{{@site.locale}}" class="color-scheme--dark">

2. Zip and upload the theme to Ghost.

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 will commit the update to the original branch. Then you would switch over to your customization branch and rebase it with the original branch.

  For example, you create two branches –

  1. original : This will have the original theme

  2. master : This will have your customized theme

     When an update on theme is released, you would copy updated theme and comit it to the original branch.

     Next, checkout to the master branch and rebase as shown:

     # Switch to the original branch
     $ git checkout original
     ​
     # Copy, paste the updated theme in original branch
     $ git add .
     $ git commit -m "Theme updated to v1.1.0"
     ​
     # Switch over to master branch 
     $ git checkout master
     ​
     # Rebase the master with original. 
     # This will apply the customization commits on top of commits from original branch
     $ git rebase original

• Another choice is to manually apply the updates to files changed from the Changelog.

• One good practice is to keep third-party scripts like Google Analytics in code injection.

Sources and Credits

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

• ​Ghost open-source publishing platform

• ​Unsplash for stock images on demo site

• ​Google Fonts for fonts

• ​PrismJs for code highlighting

• ​Simple Icons for social media brand icons

• ​Feather Icons for utility icons

• ​GhostHunter for the search feature

• ​Lightense photo zoom library

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 [email protected]. We'll do our best to assist you.

Thanks so much!