Kyochi v1.1 - Responsive Ghost Theme Documentation



GHOST

We advise reading and familiarizing yourself with the Ghost Theme Manual. It is a well written and thorough guide to understanding the Ghost blogging platform, written by Ghost themselves. It will help with understanding many aspects of the customization of your theme as well as using Ghost in general. Note that the Ghost platform is still relatively new and is constantly being developed and changing, so settings may vary depending on how you are hosting your blog. All 'line' numbers referenced in this document correspond the line at which a particular piece of code starts on, this line number is used from the default files that you downloaded. If you add or remove any lines yourself this number may vary slightly.

 

INSTALL

After downloading the .zip file you will need to upload it to your Ghost blog. There are various ways to install a Ghost theme depending on your hosting and setup. If you are hosting your Ghost blog through Ghosts hosting plan, simply log into your Ghost account on Ghost, go to 'My Blogs' and click 'Edit' next to the blog you wish to install the theme on. Under the 'Custom Theme' section, select 'Choose File' and browse your computer for the .zip file and press 'Save Settings'. Your Ghost theme will now be installed over the default theme.

If you are hosting your Ghost blog on a separate hosting plan such as Digital Ocean or A2 Hosting. You will have access to your Ghost directories and files via their FTP or File Manager, each hosting provider will have different processes to get to these locations. Locate your 'content' directory, from there, go to the 'themes directory and copy the theme folder (unzipped) into this directory. It should look like this: 'content/themes/_THEME_NAME_/'. In this directory should place the .hbs files and the assets folder which includes all CSS/LESS and JavaScript files, as well as any images included within the theme.

You may also need to restart Ghost for the theme to be recognized, to do this you'll need to follow your hosting providers instructions on how to do so, or get in touch with them and ask them to do this for you as it may vary from each providor.

Now that your theme is installed, you'll need to select it from your settings to apply it to your blog (you do not need to do this if you're using Ghosts official hosting platform). Sign in to the admin section of your blog (where you create/edit your posts etc), click 'Settings', in the 'General' tab, scroll to the bottom and you will see a Theme dropdown option, select the theme you wish to apply and hit 'Save'.

 

CUSTOMIZE

The majority of the customization is done through the .hbs, .less, .css and .js files that you receive with your download and you will need some form of text editor to help with your customization. We recommend using Sublime Text or Notepad++ to edit these files on your computer. Installation and usage guides are provided with both of these pieces of software. You can use the default text editor that comes bundled with your computer, however, these are usually fairly basic and don't have syntax highlighting or other extras to help with the editing of the files.

After making any changes you may have to go back and reinstall/upload your theme and restart Ghost for the changes to take effect. We also recommend creating a backup of the theme before customizing, just incase any mistakes are made you will always have something to revert back to.


BLOG DETAILS

To start, lets customize your blog title, description and images, as well as any other default changes applicable within your Ghost blog. First sign in to the admin section of your blog and click 'Settings', from here you can adjust your blog details and add a logo and a cover photo. For the cover photo we recommend using an image which is at least 1180px wide to cover the majority of screen sizes, as this image is stretched to fill the entire width of the page. You can also set how many articles are displayed on your blogs index page from here.

 

AUTHOR/USER DETAILS

Next click on the 'User' tab in the 'Settings' page to start customizing your profile image, location, links and bio. This is the information that will appear underneath articles on the post page. Note that this theme doesn't support an author cover photo, so a cover photo isn't necessary as of this time.

 

FAVICONS / APPLE ICONS

In the directory '/assets/images/' there are 5 icons, a Favicon for browser bookmarks/favorites and then there are 4 Apple icons for various Apple devices. To use your own images, simply replace the default theme images with your own, making sure to give them the exact file name as the originals to make sure they work correctly. Images should be in .png format and take the following dimensions:

fav-icon: 16px by 16px
app-icon-60: 60px by 60px
app-icon-76: 76px by 76px
app-icon-120: 120px by 120px
app-icon-152: 152px by 152px

 

FACEBOOK OPENGRAPH

The Facebook OpenGraph is a way for data (such as the blog title, description and page url etc) to be pulled from your site when a user posts a link to your blog in a Facebook status/post. You can find this data in the 'default.hbs' file on line 29. By default, information from your blog settings are placed into these fields and it uses the large Apple Icon as its base image. To test your data you can use Facebooks debugger to see the results.

 

TWITTER CARD

Twitter Cards are a similar idea to the Facebook OpenGraph but for use on the Twitter platform. It is a way to show media cards along with a Tweet when someone links to your blog. You can find this data just under the Facebook OpenGraph code in the 'default.hbs' file on line 37. As with the Facebook OpenGraph, information from your blog settings are placed into these fields and it uses the large Apple Icon as its base image. There are 2 fields that you will need to edit and that is the 'twitter:site' and 'twitter:creator' meta elements, you will need to place the corresponding Twitter handles (username) over the default handles that are currently there. Unfortunately Twitter does not have a debugging tool like Facebook do for their OpenGraph, however, you can read up on Twitter Cards with their documentation.

 

GOOGLE ANALYTICS

If you are using Google Analytics to track your sites traffic, you can place the code provided by Google in an allocated section of the 'default.hbs' file. Go to line 70 for the Google Analytics section, on the line below, place you code here for your analytics to start tracking data from within your blog.


CSS/LESS SETTINGS

Adjusting the LESS/CSS files requires that you have some basic knowledge of CSS and how stylesheets work. Our themes are created using the Backbone Responsive Framework, this framework (and the theme) is styled using a CSS pre-processor called LESS. LESS allows us to expand on the capabilities of standard CSS and use variables, mixins and functions etc to make development and updating easier and more consistent as well as making minor adjustments for you a simpler process. View the LESS documentation for more details on how to properly use and understand LESS.

Since we are using LESS, it does however make it easier to customize the more obvious styles of the theme such as primary colors, backgrounds and borders etc. You will notice there are 4 .less files located in the '/assets/css/' directory:

'Backbone Vars' contains all the base variable settings for the framework and theme colors. 'Backbone Mixins' contains all the mixins for quickly assigning certain styles to theme elements. 'Backbone Frame' sets everything from the responsive grid template, typography and form elements. 'Style' is specifically for styling the actual theme rather than the framework itself, although settings within the framework can be overridden in this file. All colors are in HEX format and if you wish to find a new color you may find using a Color Picker helpful, always remember to put the correct suffix on variables which require a dimension or size. As we mentioned before, unless you have an understanding of CSS (and in this case LESS) we don't suggest adjusting other settings/values outside of the 'Backbone Vars' file as it may throw back errors which will cause page breakages on your theme or even stop your theme working completely.

Remember always create a backup before making any changes!

 

COMPILING

If you alter any of the .less files, you will then need to compile them to CSS, to do this go to LessTester and copy/paste each .less document into the left panel, in the same order as they are listed above: Vars, Mixins, Frame and Style. Since the 'style.less' file imports the 'backbone-*.less' files into it, you will need to comment out the '@import' lines on lines 17, 18 and 19 as it will trigger an error when compiling on LESS Tester, as it won't find those files to import on their server. To comment out the imports, simply adding '//' to the start of each import line (without apostrophes). Once these have been pasted into LessTester, click the 'Compile' button, if done correctly it should output a minified CSS version of all the code in the right panel. This outputted code needs to be pasted over the content within the 'style.min.css' file, which is also located in the '/assets/css/' directory.

If you are going to be making a lot of adjustments to the LESS files and don't want to compile everytime, you can take the theme out of Production Mode and put it into Development Mode, meaning it will read the LESS files and compile them in the browser. Although it may seem easier to do this as standard, compiling in the browser slows the load time of the pages, as well as not styling the theme at all in older browsers such as IE8. To swap from Production Mode to Development Mode, open the 'default.hbs' file and go to line 59 and swap lines 59-62 from this: 

<link href="{{asset "css/style.min.css"}}" rel="stylesheet" type="text/css" media="all" />

<!--<link href="{{asset "css/style.less"}}" rel="stylesheet/less" type="text/css" media="all" />
<script src="http://cdnjs.cloudflare.com/ajax/libs/less.js/1.6.3/less.min.js" type="text/javascript"></script>-->

to this:

<!--<link href="{{asset "css/style.min.css"}}" rel="stylesheet" type="text/css" media="all" />-->

<link href="{{asset "css/style.less"}}" rel="stylesheet/less" type="text/css" media="all" />
<script src="http://cdnjs.cloudflare.com/ajax/libs/less.js/1.6.3/less.min.js" type="text/javascript"></script>

To revert back to Production Mode, simple swap the code back over..

 

GOOGLE FONTS

Google Fonts is a vast library of web fonts that you can use for any text within a theme, by default our themes either use a Google Font in the original design, or it will have the 'link' HTML tag in place ready to start loading them. To use a Google Font, first choose the font you wish to use on the Google Fonts website. For this example we'll change the Header 1 '<h1>' elements' font to 'Roboto'. Search for 'Roboto' on Google Fonts, press the 'Quick Use' button located to the right of that font and look at Step 3, where you will see a snippet of code similar to this:

<link href="http://fonts.googleapis.com/css?family=Roboto" rel="stylesheet" type="text/css" />

The main part of this you need to take note of here is the query section 'family=', after this bit is where your font name and it's weight will be displayed. You can load multiple fonts in one line by using '|' as a separator for example 'Roboto|Open+Sans'. Note how any spaces in the font name are replaced with '+' (without apostrophes).

To load a specific font weight, choose the weights you want in Step 1 which will give you something similar to 'Roboto:300,400' where 300 and 400 will load the 'light' and 'normal' versions of this font. Font weights are separated with a comma, with the first weight value separating the font name and itself with a ':' (without apostrophes). Add this section to the 'default.hbs' file on line 54, always remember, if you're using a Google Font already, add the new font to the end of the 'family' query with the correct separators.

Finally, look at Step 4 on the Google Fonts page, there is another line of code declaring the CSS value for the font family, which should look similar to this:

font-family: 'Roboto', sans-serif;

Depending on which variable/element you wish this font to apply for, in the LESS/CSS files, find that particular variable or element and replace the current font-family value with "'Roboto', sans-serif;". Since we're adjusting the Header 1 tag, in the 'backbone-vars.less' file, scroll down to '@h1-font-family' (line 78 by default), and replace the value of this to "'Roboto', sans-serif".

Try not to load too many Google Fonts (or web fonts in general) at any one time as the more fonts that are loaded the slower your page load time will be.


GENERAL

This theme uses a plugin called Animations which is included in the Backbone Responsive Framework, it includes a vast library of predefined animation effects for elements, you will also find the documenation on how this plugin works on the linked GitHub page. Which we greatly suggest reading before trying to edit animations so you can correctly add, edit or delete default animations set within the theme. If you don't wish to have these animation effects at all, in the 'default.hbs' file, go to line 58 and change this line:

<link href="{{asset "css/animations.min.css"}}" rel="stylesheet" type="text/css" media="all" />

to this:

{{! <link href="{{asset "css/animations.min.css"}}" rel="stylesheet" type="text/css" media="all" /> }}


Then go to line 194 and change this line:

<script src="{{asset "js/animations.min.js"}}" type="text/javascript"></script>

to this:

{{! <script src="{{asset "js/animations.min.js"}}" type="text/javascript"></script> }}

This stops the loading of the animation files, but still keeps the class name and data attributes set in your theme incase you ever wish to enable animations in the future.


NAVIGATION

By default, we include social newtwork icons to various social media websites within the sites navigation. You can add and remove these as you please by following the same format but slightly altering specific values in each line. Open the 'default.hbs' file and scroll to line 107. In this section look for the first social icon element (line 122), which should look something like this:

<li><a href="#" target="_self" class="tip-t-fade" data-tooltip="Facebook"><i class="fa fa-facebook fa-fw"></i></a></li>

There are 2 values which determine what social network this displays and links to. The 'a' HTML tag has a href value of '#' which is where you put the full URL of your social network profile, for example href="http://www.facebook.com/cloudeightdesigns", the data-tooltip has value of "Facebook" which is where you put the title of the social network which will appear in the tool tip (above by default) (to learn more about these tool tips, check the 'Tooltips' section in the Backbone Responsive Framework documentation). If you wish to remove the tooltip completely, remove the class attribute value and the data-tooltip attribute. The 'i' HTML tag has a class value of 'fa-facebook' which corresponds to the FontAwesome Facebook icon.

Since these social networks use FontAwesome for their icons, it's best to stick to the icons that FontAwesome supports for consistency, you can see a full list of their brand icons here. The 'i' HTML tag, also needs the 'fa' and 'fa-fw' included to work as intended.

 


IMAGES

If you place an image in one of your posts, the image by default will be placed on the left hand side of the page and the text will continue underneath. You may wish to float the image left or right and have the text wrap around the image accordingly, to achieve this, simply give the image a class name of 'image-left' or 'image-right', like this:

<img src="http://www.mysite.com/image.jpg" alt="" title="My Image" class="image-left" />

Alternatively, you can center the image by adding the class name 'image-center'. Centering an image will set the image to center itself within the container, and if it's not as wide as the container it will display at its maximum width to stop the image pixelating. However, adding the class 'full-width', you can force the image to stretch to the width of the container, like this:

<img src="http://www.mysite.com/image.jpg" alt="" title="My Image" class="image-center full-width" />


GENERAL

By default your comments section will load the Disqus platform linking to the Cloud Eight profile. To edit the comments section open the 'theme.js' file located in the '/assets/js/' directory. In your text editor scroll down to line 102 for the comments section of this file. The first part sets all the variables for your comments, the first variable 'disable_comments' is set to 'false', this means comments are currently enabled. To disable comments completely, change this value to 'true' (without apostrophes). The next variable sets which comment plugin you wish to use within your theme, your 2 options here are 'disqus' or 'facebook' (with apostrophes). Depend on your choice follow the relative section below.

 

DISQUS

To use Disqus comments on your blog you'll first need to create a Disqus account and set your username/shortname, head over to Disqus and check it out and when you're ready, click 'Add Disqus to Your Site'. Where it says "disqus_shortname = '';" for the 3rd variable on the 'theme.js' file, you will need to add your Disqus username between the apostrophes. This plugins' font color is set automatically by Disqus based on it's parent font color, this parent font is set in the 'backbone-vars.less' file with the '@disqus-font-color' variable.

 

FACEBOOK

If you chose to use the Facebook comments plugin, there are no other variables to set for this plugin to work in the 'theme.js' file, as the API has already loaded. There are a couple of values you can adjust via HTML on the 'post.hbs' file on line 86. If you wish to alter the amount of comments/posts that the Facebook comment plugin displays, alter the numerical value in the 'data-numposts' attribute. Same goes for the color scheme, if you decide to adjust the colors of the site to a darker tone, change the value of the 'colorscheme' attribute to 'dark', instead of 'light'.


FRIENDLY URL

Once you have created a post and set it as a static page you will need to take note of the 'SEO Friendly URL' which you can find by clicking the settings icon next to the 'Save' button on the add/edit post page. It will usually be the same as the title of your post, all lowercase with any spaces replaced by hyphens. For example if you page was called 'Example Static Page', the value would be 'example-static-page', but always double check to make sure you have the correct URL handle.

 

NAVIGATION

To link to these page(s) in your sites navigation you will need to manually enter this into the 'default.hbs' page, go to line 107 in this file, where you will find an unordered list containing 4 links to different example pages. By default there are 4 links: Home, Static Page, About Us and Contact Us. Simply add and remove lines, depending on how many static pages you wish to link to. On these lines there are 2 important values you will need to change, first is the link to the static page which you can enter in the 'href' value, using the above example this would be 'href="/example-static-page"' notice the preceeding '/' which is needed. The next is the display text, towards the end of the line, where the opening 'a' tag ends, this is where you enter your display text, remembering to close of your 'a' tag.

So, for example, from the default navigation, lets say we want to put in a link to the page we just created above as a static page inbetween the About Us and Contact Us links, we would do it like so:

<li><a href="/" target="_self">Home</a></li>
<li><a href="/static-page" target="_self">Static Page</a></li>
<li><a href="/about-us" target="_self">About Us</a></li>
<li><a href="/example-static-page" target="_self">Example Static Page</a></li>
<li><a href="/contact-us" target="_self">Contact Us</a></li>

As you can see, we place the line inbetween the About Us and Contact Us list items, entered the friendly URL of '/example-static-page' into the href value and also adjusted our display text to Example Static Page.


GENERAL

Currently updating your theme will require a fresh install of the theme, meaning any alterations you make such as color styles, navigational/static page links or additional social network icons will have to be altered on the new files also. If however you feel you could copy and paste sections from the updated files into your current files, then by all means, do so. However, if this causes errors, we unfortunately could struggle to help rectify any of the possible errors. Included in future updates will be a changelog which will note new theme features or adjustments, which could also help with manually updating your theme too.

When a new version of this theme is available we will send an email through ThemeForest to notify you. This is the sent to the email associated with your ThemeForest account.