Documentation

Setting Up Tiles Ghost Theme

Luke Edwards Luke Edwards

Before you publish your site for the world to see, there are a few minor steps you need to take.

General Settings

Navigate to your general settings:

http://your_url.com/ghost/settings/general/

General Settings

  1. Upload a Blog Logo.
    This will be used as your navigation's logo image.
    The image's size should not exceed 170x50 pixels.

  2. Set the Posts per Page to 1000!
    Even if you're not planning on 1,000 posts, this will ensure that all your posts can be found on the home page (there is no pagination, for now).

Note: An on-scroll infinite loader is on the Roadmap!

  1. Select the Tiles theme as your current theme.
    Of course, Tiles theme must actually be selected before you can see it.

Note: If Tiles does not appear as an option, make sure that you've uploaded the theme correctly and that you've restarted Ghost.

Go to your navigation settings:

http://your_url.com/ghost/settings/navigation/

Pages

If you wish to link to a static page, you may link to it directly here.

Please make sure the page exists before linking to it.

Categories

After you've linked to a set number of static pages, you may want to begin linking to "category" or "tag" archives.

However, Tiles theme requires that you insert a "trigger" link so that it can properly assemble the animated sub-menu.

SubMenu Setup

You will notice that 'Categories' is an empty link. This will become the label for our sub-menu's trigger!

All the links that follow 'Categories' will populate the sub-menu.

The last step is to tell our JavaScript which navigation item is supposed to be the trigger:

  1. Count items from the top, starting at 0.
    This means that 'About' link is 0, 'Contact' is 1, and our trigger's index position is 2.

  2. Edit the JavaScript.
    Navigate to src/scripts/nav/index.js and change the IDX variable on line 3 to our new index position, 2.

  3. Recompile the JavaScript.
    Following best practices, we need to minify & compress our code changes. See the Build Tools section for info.

After making and compiling the changes, you can head back to your homepage and view the menu and sub-menu bars' new links!

Static Pages

Please note that any static pages will default to the generic page.hbs layout.

If you wish to customize the look of a page, you must:

  1. Create a page-{slug}.hbs file in your theme's root folder, where {slug} is the URL root of your page. So if your page's URL is blog.com/about-me, your file should be called page-about-me.hbs.

  2. Copy markup from page.hbs and then make tweaks to customize the look as you want, or start from scratch.

Tags

Go to your tag settings:

http://your_url.com/ghost/settings/tags/

In this area, you may create new tags or edit existing ones.

Note: You may also create new tags when creating a Post!

When editing a new tag, you may customize its URL, which is what you'll use as a link within the tag sub-menu.

You may also modify its description and upload an image for each tag, which will be shown on the tag's archive page as a tile header, as shown below.

Tag Tile Example

The image area will be left blank if no image is uploaded.

User Profiles

Each user is referred to as an "author", thus earning them their own archive page:

http://your_url.com/author/{slug}

...where {slug} is the author's username slug.

In order to modify a user's information, navigate to:

http://your_url.com/ghost/team/

Since an author is essentially treated like a "category" (tag), each user's tiles and pages appear like a tag page.

To manage the description or cover images, please see the Tags documentation.

Code Injection

To manage code injection settings, head to:

http://your_url.com/ghost/settings/code-injection/

Fonts

By default, Tiles uses the Oxygen and Source Sans Pro from Google Fonts.

If you would like to change these, browse through Google Fonts and add favorites to your collection.

Note: It's advised that you don't use more than 4 files total, which includes font variations/styles.

When you're done, you should find a link that resembles:

<link href="https://fonts.googleapis.com/css?family=Oxygen:300,700|Source+Sans+Pro:400,400italic,700,700italic" rel="stylesheet">

Place this link in the Blog Header section, replacing any existing font links.

You will then need to open the src/styles/_config/_defaults.sass file inside your text editor.

Modify the $base-font-family with the name of your new body/text font.

Modify the $base-heading-family with the name of your new headers font.

Note: You may also need to change the values of $base-font-weight and $base-heading-weight accordingly.

Save this file when you're done.

Then see the Build Tools section for instructions on compiling your changes!

Analytics

Tiles theme comes ready to support Google Analytics out of the box.

If you'd like to use it, you must first set up tracking. At the end of this setup, copy your full tracking code and paste it into the Ghost section labeled Blog Footer.

That's it -- Tiles will automatically track all AJAX-loaded content!

Comments

If you'd like to enable Commenting on your posts, you must setup Disqus, a free commenting plugin.

After you've signed up, save your Disqus unique shortname.

You will then need to enter this value as a JavScript variable through the Blog Footer:

<script>var disqus_url = '{shortname}';</script>

Note: Replace {shortname} with your unique shortname. The '' should remain. This is not a full URL.

By default, comments are disabled on static pages.

If you wish to disable comments for a single Post only, you may include an additional script tag within the content body of your Post.

In the Post's markdown editor, you should write:

<script>var no_comments = true;</script>

Contact Form

If you'd like to make the included contact.hbs form functional, you need to provide an email via the Blog Footer in the form of another JavaScript variable.

<script>var contact_url = 'https://formspree.io/your@email.com';</script>

Note: Not providing this variable will invalidate the contact form!

The mail provider is Formspree, a free mail forwarder.

Before your contact form can become functional, you must confirm your email by sending yourself an email through your new contact form. Formpsree will send you a confirmation email which contains simple instructions for continuing.

Google Maps

You may embed a google map on any post or page.

First, you get an API key.

Then, inject this API key into the Blog Footer of your settings area:

<script>var google_maps_key = '{ key }';</script>

Note: Replace { key } with the full string. The '' should remain.

At this point, all you need to do is enter one line of HTML within the Markdown editor:

<div class="map" data-center="{ coordinates }"></div>

Note: Replace { coordinates } with the latitude and longitude of your desired center.

To convert addresses to coordinates easily, use this online tool.

Map Options

Each of the following keys can be used to customize your map, as long as it's prepended with data-:

  • center: The map's center & the marker's location.

    Default: null

    Example: data-center="78.123,-122.23"

  • type: The type of Google Map to display.

    Default: 'ROADMAP'

    Options: ROADMAP, SATELLITE, HYBRID, TERRAIN

  • zoom: The starting zoom level of the map.

    Default: 17

    Example: data-zoom="12"

  • title: The marker's title, when clicked.

    Default: null

    Example: data-title="Custom Title"

  • scroll: If mousewheel scrolling should be used to control the zoom level.

    Default: 0

    Options: 1 or 0

You may also pass a custom height (and other style properties) via the style property.

A final example may look like:

<div class="map" 
  data-center="37.7749295,-122.41941550000001"
  data-title="San Francisco!"
  data-type="HYBRID"
  data-zoom="14"
  data-scroll="1"
  style="height: 350px;"></div>

Build Tools

Note: Using the build tools requires Command Line / Terminal access and, preferably, a basic familiarity with the command line.

You must also have Node installed.

Tiles theme is constructed with Taskr, an insanely fast, asynchronous alternative to Gulp.

Setup

Before you can run any build commands, you must first install the NPM dependencies.

  1. Navigate to your Tiles directory.
    cd path/to/tiles
  2. Ensure this is the right directory.

    There should be a taskfile.js present here.

  3. Install dependencies.
    npm install

Tasks

With all dependencies in order, you may now begin running different tasks to develop or compile changes.

Build -- build production-ready assets

npm run build

Export -- create & compress a ZIP file that's ready for upload

npm run export

Watch -- start a dev server; watches & recompiles files on change.

npm run watch