Biron Themes
$0
Biron
$ 39
Voice
$ 29
Escript
$ 39
Gazette

Voice Documentation

Current Version: 1.5.1

Last updated: Feb 03, 2019

Link: Voice Theme

Table of Contents

  1. Theme Info
  2. Install Theme
  3. Publication Settings
    1. Logo
    2. Icon
    3. Static Pages
    4. Navigation
    5. Content API
    6. Subscribers
    7. Language
    8. Ghost Search
  4. Customization
    1. Posts Per Page
    2. Translation
    3. Custom Pages
    4. Social Media Links
    5. Advertisement
    6. Disqus Comments
    7. Google Analytics
  5. Theme Development
  6. Credits
  7. Support
  8. Change Log

1. Theme Info

Name: Voice - Ghost Theme
Description: a News & Magazine Ghost Theme
Released: 2018.05.24
Creator: Biron Themes

Requirements

Ghost version: 1.0 or higher
Ghost Content API: v2
Ghost Subscribers Feature: Active (Optional)

2. Install Theme

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Go to Settings > Design from the admin menu
  • Under the Themes section click Upload a theme
  • Click inside the upload box to select a voice.zip, or drag-and-drop the voice.zip into the upload box
  • If you want to activate the theme immediately click Activate Now or Close if you want to do it later

3. Publication Settings

Some basic settings for your publication:

To Upload a new logo follow these steps:

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Click General under the settings menu.
  • Under Publication logo, click Upload Image and select your logo

Publication Logo

  • Finally click Save settings

3.2 Icon

To Upload a new icon follow these steps:

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Click General under the settings menu.
  • Under Publication icon, click Upload Image and select your icon

Publication Logo

  • Finally click Save settings

3.3 Static Pages

To create a static page within your publication, follow the steps below.

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Either create a New Story or edit an existing one.
  • Open the Post Settings Menu by clicking on the gear icon in the top right corner
  • Check the box to Turn this into a static page

Static Page

Click Publish or Update(for an existing story) at the top of the editor to publish the static page.

3.4. Navigation

To add menu items to your publication, follow the steps below.

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Click Design from the admin menu
  • Under Navigation, enter a label for the menu item in the label field
  • In the URL field, enter the destination for the menu item to link

Ghost Blog Navigation

  • Click Save

3.5. Content API

As mentioned in the Requirements section, this theme uses the Content API v2, so in order to take advantage of all the theme features make sure the Content API v2 is used, this is set in the theme by default.

You can check this in the theme’s package.json file:

{
  "name": "...",
  "description": "...",
  "demo": "...",
  "version": "...",
  "engines": {
    "ghost": ">=2.0.0",
    "ghost-api": "v2"
  },
  ...

3.6. Subscribers

This theme supports the Ghost subscribers feature. To activate the feature follow the steps below.

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Click Settings > Labs.
  • Check the box for Subscribers, under the Enable Beta Features.

Beta Features

If the feature is active, the subscription form will appear in the sidebar.

Subscribe feature

To view subscribers click Subscribers from the admin menu.

3.7. Language

To set the publication language follow the steps below.

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Go to General from the admin menu
  • Under Publication Language, click Expand and set the language/locale to be used on the site. The default is set to English (en).

Publication Language

  • Click Save settings

Language Code Reference

This theme uses the Ghost Search Plugin by HauntedThemes.

In order for the search to work you need to edit the default.hbs file:

{{!-- Settings --}}
<script>
  /* Ghost Search */
  // Replace it with your domain: ghost_host = 'https://yoursite.domain'
  var ghost_host = 'http://localhost:3568';
  // Settings > Integrations > New Custom Integration. Copy Key. Replace ghost_key below.
  var ghost_key = '42695d4e682a4757b736928a19';
...
<script>

You will have to replace the ghost_host and ghost_key values.

ghost_host should be the the domain of your blog (ex. ‘https://yoursite.domain’).

ghost_key has to be generated in the admin panel.

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Click Settigns > Integrations.
  • Click Add custom integration.
  • Name it Ghost Search
  • Copy the generated key
  • Add this key in default.hbs for the ghost_key value.

4. Customization

Different customizations for the theme.

4.1 Posts Per Page

From Ghost 1.0 the “Posts per page” settings was moved from the Ghost Admin to the theme. You can set it in the package.json of the theme:

"config": {
  "posts_per_page": 9
}

For Voice the default value is 9, you can change it to whatever number you wish, we recommend a number that can be devided by 3.

4.2 Translation

Voice supports Ghost i18n and it comes with translations for the following languages:

  • de for German
  • fr for French
  • es for Spanish

To change the publication language to one of the available languages check out this guide.

Editing the translations

The translation files are stored in the locales folder within the theme folder.

|__locales
| |__de.json
| |__en.json
| |__es.json
| |__fr.json

Open up the file for the language you want to edit. Example de.json:

{
  "Previous": "Bisherige",
  "Next": "Nächster",
  "Back": "Zurück",
  "Forward": "Weiter",
  "Post": "Post",
  "Posts": "Artikel",
  "Page": "Seite",
  ...
}

Each line consist of a key-value pair.

"key": "value"

The key is on the left side and it should not be changed (it’s the same in all the files) and right value which you can adapt if necessary.

If you have suggestions to improve the translations or adding a new language, drop us a line.

Adding a new language

To add a new language you have to create a new translation file with the language code of the desired language.

For example if you want to create new translation for Hungarian language you have to create hu.json within the locales folder.

And add the translations for each key value.

For more details check the Official Ghost Documentation.

4.3. Custom Pages

Voice comes with 4 custom pages by default:

  • Contact Page
  • Tags Page
  • Authors Page
  • About Page
Contact Page

To create the Contact page, do as follows:

  • Create a new story and call it Contact.
  • Make sure the the Post URL is contact.

Post URL

  • Check the box Turn this post into a page.
  • Click Publish.

To add the page to the navigation, please check the Navigation section above.

[Voice Theme Contact Page]

Tags Page

To create the Tags page, do as follows:

  • Create a new story and call it Tags.
  • Check the box Turn this post into a page.
  • Select the Tags template from the Template dropdown.

Post URL

  • Click Publish.

To add the page to the navigation, please check the Navigation section above.

Authors Page

To create the Authors page, do as follows:

  • Create a new story and call it Authors.
  • Check the box Turn this post into a page.
  • Select the Authors template from the Template dropdown.

Post URL

  • Click Publish.

To add the page to the navigation, please check the Navigation section above.

The social media links are stored in a partial file partials/social-media.hbs.

Ghost supports Facebook and Twitter social accounts, to change them do the following

  • Log in to your publication admin section at yourblog.com/ghost/signin
  • Go to General from the admin menu
  • Click Expand under Social Accounts, and enter the URLs for your Facebook and Twitter.

Social Accounts

  • Click Save settings

To edit the other social links follow the steps below. Open up the social-media.hbs file and change the href value to your profile’s URL for that specific social platform.

  ...
  {{!-- Instagram --}}
  <a class="social-links__item instagram"
     href="https://instagram.com" target="_blank" title="Instagram" aria-label="Instagram">
    {{>icon name="instagram"}}
  </a>
  ...
</div>

For example to change the Instagram link, you have to change the existing href value:

href="https://instagram.com"

Add your instagram accound link, example:

href="https://instagram.com/bironthemes"

4.5. Advertisement

Voice comes with an advertisement widget.

Voice Advertisement

To edit the image open the sidebar.hbs file located in the partials folder. Look for the {{!-- Advertisement --}} section.

{{!-- Advertisement --}}
<div class="sidebar__section">
  <h5 class="sidebar__title">{{t "Advertisement"}}</h5>
  <a href="{{@blog.url}}" class="sidebar-ad ad-unit">
    <img class="lazyload js-fadein" src="/assets/img/ad-unit-300-250.jpg" alt="{{t 'Advertisement'}}"/>
  </a>
</div>

Replace the src value /assets/img/ad-unit-300-250.jpg with your image URL and change the href value with the link where you want your advertisement to point.

If you want to remove the advertisement, delete the code above from the sidebar.hbs file.

4.6. Disqus Comments

Voice comes with Disqus comments enabled.

Make sure you have registered your website with Disqus and you know your disqus_shortname.

Open default.hbs file located in the root folder. Change the biron-demo value for the disqus_shortname variable to match your Disqus account shortname.

{{!-- Global variables --}}
<script>
  // The number of pages available for loading more posts
  var maxPages = parseInt('{{pagination.pages}}');

  // Disqus shortname
  // Replace 'bironthemes-demo' with your disqus account shortname
  var disqus_shortname = 'biron-demo';
</script>

That’s all, Disqus comments should work now.

If you don’t want disqus comments to show delete the comments.hbs file located in the partials folder. And delete the following section from the post.hbs file located in the root folder of the theme:

{{!-- Include Disqus Comments --}}
{{> comments}}

4.7. Google Analytics

To add Google Analytics to Ghost follow this tutorial from Ghost.

5. Theme Development

Voice is developer friendly, if you need to make advanced customization you will take advantage of the Gulp tasks that are set up for compiling Javascript and SASS/CSS.

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

Run the the following commands in the voice theme directory:

npm install

This will install all the dependencies for the theme

Then run:

gulp

This will compile SASS/CSS and javascript and will watch for changes. So when you edit a .scss or .js file the change will trigger the gulp watch task and this will compile the assets with your changes.

If you want to comile sass or javascript separately, you can run:

gulp sass

For compiling SASS/CSS

Or:

gulp scripts

For compiling javascript files.

For more details on how to customize the theme check out How to customize our Ghost Themes

You also have the option to use Code Injection to do customizations. For example if you want to change the default color of the buttons, add the following code in the Blog Header section.

.btn, a.btn, button.btn {
    background: #333; // set it to your desired color
}

6. Credits

Voice uses the following packages/plguins:

Images are not included in the download files!

7. Support

Don’t hesitate to contact us if you have suggestions or need help.

Contact

8. Change Log

------------  VERSION - 1.5.1: Release on 02 Feb 2019  ------------
[*] - Minor Bug Fixes

------------  VERSION - 1.5.0: Release on 01 Feb 2019  ------------
[*] - Dependency updates

------------  VERSION - 1.4.0: Release on 22 Jan 2019  ------------
[+] - Ghost Content API support
[+] - New Ghost Search Plugin

------------  VERSION - 1.3.0: Release on 23 Jan 2019  ------------
[*] - Minor fixes
[*] - Dependency updates

------------  VERSION - 1.2.0: Release on 05 Sep 2018  ------------
[+] - Ghost 2.1 Image Gallery Support added

------------  VERSION - 1.1.2: Release on 18 Aug 2018  ------------
[+] - Ghost 2.0 Support 
[*] - Minor fixes
[*] - Dependency updates

------------  VERSION - 1.0.3: Release on 14 Jun 2018  ------------
[+] - Added embed-card and image card support
[*] - Fixed subscribe and read-time translation

------------  VERSION - 1.0.2: Release on 10 Jun 2018  ------------
[+] - Added Portuguese language
[+] - Added Koenig editor support
[*] - Fixed first post background when it has no image

------------  VERSION - 1.0.0: Release on 23 May 2018  ------------
[+] - Initial release