http://pixelandkraft.com/blockster/demo/docs/
BLOCKSTER
Master Documentation
Getting Started
Before installing Blockster, we recommend setting your configuration preferences. There's nothing wrong with doing this after installing, but it's generally easier to edit files on your local machine than on a remote server.
Insight on configuring Blockster follows. Once configured, you're ready to upload it to your Ghost site. For info on installing and activating themes, see the official ghost installation docs.
Configuring
All Blockster configuration settings are in the file config.hbs located in the theme's partials directory. To edit this file, follow these steps:
- Navigate to
config.hbsin thepartialsdirectory (blockster-root/partials/config.hbs). - Make a copy of
config.hbs(name it however you prefer, perhapsconfig.backup.hbs). This is simply standard good practice. It will be there for you if things go south and you need to start over. - Open the
config.hbsfile in a text editor (or a simple notepad application -- just not a rich text editor like Word or Open Office). - Adjust the settings according to your preferences. The config file is thoroughly commented to help make things as self-explanitory as possible. Don't forget to use the demo for reference.
- Save a copy of this file. Upon installing future updates of Blockster, having a saved copy will ensure that you settings are not overridden.
Editing the Config.hbs settings file should be intuitive. Should you have recommendations for how we can improve it, please contact us.
Customizing
All style source files are included with Blockster. The css is written in Sass using it's bracketed .scss syntax. If you're familiar with Sass then you'll have no problem jumping-in and customizing.
If you're not familiar with Sass, here are some resources and quick bits to understand:
Sass Overview
Sass is a css pre-processor. Checkout these great resources for learning more:
- Preprocessing is for Everybody presentation by Chris Coyier.
- A great brief overview
- Sass Level-Up Tuts Tutorials
- Lots more exist. A simple Google search is really all that's needed.
Being a pre-processor, .scss files need to be compiled.
Here are some options for compiling Sass:
All in one Desktop Apps:
- Prepos (Mac, Win - free)
- Compass App (Linux, Mac, Win - paid)
- Code Kit (Mac - paid)
- hammer (Mac - paid)
Command Line Approaches:
Each of the desktop apps are powerful applications that will do much more than simply compile your stylesheets. Check out their feature lists to understand their full capabilities.
Important!
However you choose to compile, it's crucial that the method include support for Autoprefixer. We've developed Blockster with the aid of Autoprefixer, which means that CSS3 elements don't have their vendor prefixes in the core Blockster code.
The good news? Autoprefixer will change your life (in an awesome way) and the above mentioned compiling tools (and others) make it easy to setup autoprefixing (Codekit even auto-prefixes by default, I believe).
Blockster Docs
Contents:
- Home Page Styles
- Post Excerpts
- Excerpt Images
- Background Images
- Image Captions
- Retina Images
- Logos and Avatars
- Static Pages
- Smooth Scrolling
- Banners
- Page Width (custom)
- Nav Widget
Home Page Styles
Blockster includes several home-page layout styles:
- Classic 1 (masonry)
- Classic 2 (stacked)
- Gallery 1 (masonry)
- Gallery 2 (tiles)
- Gallery 3 (tiles with horizontal/vertical 2x option -- ie: large rectangles)
- Gallery 4 (tiles with square 2x option -- ie: large squares)
- Gallery i (legacy gallery option with original hover style)
- Text Only (demo purposes only, create the same style manually for best performance)
Gallery Featured Images
Gallery1 is the only gallery layout option that fully shows a post's featured image. Other gallery layouts may at times leave your images only partially visible (depending on their sizes). This is because gallery1 uses a masonry layout, while the others use tiled layouts.
All gallery layouts preserve image ratios (preventing distortion).
Gallery Titles
Set gallery titles to "toggled on" via Blockster's global config.hbs file. This option is off by default.
Post Excerpts
Post excerpts are the blurbs of text connected to each post item on the home page. Post excerpts are only used with the following excerpt styles:
- Classic 1
- Classic 2
- Gallery i
- Text Only
By default, post excerpts are set to 30 characters (in the index.hbs file).
Custom excerpt content and length can be set on a post-by-post basis in one of two ways:
Method 1: Surround your desired excerpt text in an excerpt tag. Example:
<excerpt>I'm a post excerpt!</excerpt>
Method 2: Surround your desired excerpt text in a div with a class of excerpt.
<div class="excerpt">I'm a post excerpt!</div>
Which to use (and when)?
The tag method (<excerpt>Excerpt text here</excerpt>) only works with inline-level formatting (bold, italics, links, etc). This means that, the tag method will not work for multiple paragraphs, lists, etc.
The div method (<div class="excerpt">Excerpt text here</div>) can accept block-level html (lists are the primary use case here). The catch? Markdown formatting won't work between the div tags.
Essentially, use the:
- Tab Method when excerpts only need inline formatting (or none at all).
- Tab Method when you want to use markdown markup for inline excerpt formatting.
- Div Method when excerpts need block-level formatting.
- Div Method when you want to use HTML markup for inline/block excerpt formatting.
Home-only Excerpts
To have excerpt text only be shown on home-page excerpts (not shown on the actual post's page), add the class home-only to the tag or div used to create the excerpt (surrounding the excerpt).
Tag Example:
<excerpt class="home-only">Excerpt content here...</excerpt>
Div Example:
<div class="excerpt home-only">Excerpt content here...</div>
Excerpt Images
An image, video, or audio can be used as a post's featured "image" -- also referred to as an "excerpt image."
For Images: Upload a featured image via Ghost's cover-image uploader (introduced in Ghost's version 0.5.2).
Important: Blockster will automatically place a post's featured image at the top of its page. To disable this behaviour on a post-by-post basis simply add the tag no-cover to the post. This will completely remove the cover image from the post.
Depreciation Note: Before ghost 0.5.2, Blockster made use of the "alt-tag" method for post-excerpt images. This feature is depreciated in Blockster 2.0 and no longer works.
For Video and Audio: Two classes are needed on the iframe html:
featuredvideooraudio, as appropriate.
Video Example:
<iframe class="featured video" src="//player.vimeo.com/video/62022718?title=0&byline=0&portrait=0" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
Audio Example:
<iframe width="100%" height="166" scrolling="no" class="featured audio" frameborder="no" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/155100180&auto_play=false&hide_related=true&show_comments=true&&show_reposts=false&visual=false"></iframe>
Note: Adding the tag
no-coverto a post that uses an audio or video for it's featured image will remove it from the top of the post but not entirely from the post (contrary to featured images). To remove the featured audio or video from the post entirely (effectively using it only for a home-page featured audio or video), add the classhome-onlyto it.
2x Width, Height, and Square Excerpt Images
Horizontal and vertical 2x excerpt images can be set when using the gallery3 layout. 2x square excerpt imags can be set when using the gallery4 layout. These are set individually for each post excerpt.
Set 2x width, height, and square excerpts on a post-by-post basis by adding one (only one) appropriate tag to a post.
Tags to add:
For width: width2x
For height: height2x
For square: square2x
Background Images
As of version 1.1, Blockster supports the use of an image for the site's global background. As with most settings, activate this in Blockster's global config.hbs file. Twelve background images come with the theme (as seen in the demo, named bgImg1, bgImg2, etc. (respectively from left to right)). To use a custom image, follow the steps below.
How to use a custom background image
- Upload your image to Blockster's image background directory, located at
/assets/images/backgrounds/ - Name your image eith
bgImgCustom.jpg,bgImgCustomJPG.jpg, orbgImgCustomPNG.png. - In
config.hbs, setbackground_imageto the name you're using (from step 2).
NOTE: "bgImgCustom" is only for .jpeg images. "bgImgCustomJPG" was added for clarity.
Recommended Size: 1900 x 1250px
For Retina Screens: include a "twice-as-large" copy of the image in the same directory and suffix it with @2x before the extension (example: [email protected]).
Image Captions
Blockster will automatically use the title-tag text of an image and turn it into a caption. Since there's not yet any way to add title tags to images through Markdown in Ghost, use standard html.
Example:
<img src="/blockster/demo/content/images/2014/Jul/13.jpg"
title="Example caption of non-featured image">
Retina Images
Blockster is fully "retina ready."
Theme icons are vector based (svg), which by definition means they look sharp on all devices.
For images uploaded into Ghost (logos, post images, etc) that are pixel based (.png or .jpg), a second one of two-times the size will also need to be uploaded. Important: Add @2x to the end of the file name, but before the extension. This allows retina devices to detect the "retina-friendly image" and act appropriately.
For example: Say you're uploading a photo into a blog post named sky.jpg that is 750px x 400px. You'll need to also upload a second photo. Call this one [email protected]. It should be double the size, 1500px x 800px. We find that it's easier to think in terms of the "original" and "scaled-down" images, since the original image format is usually quite large.
Important: Ghost doesn't yet support multiple image size uploads (or image resizing) for the same picture. Thus, you'll need to upload this second "@2x" version of you images via FTP. The only criteria is to make sure it goes into the same folder as the original upload (image folders are organized by year and month). As soon as there's a better option for this within Ghost, Blockster will support it.
Logos and Avatars
Blockster has pre-defined sizing for logos and avatars, so no visual cons come from uploading an image that's too big. For best performance, however, it's best to use the optimal size (and include an @2x version as specified above).
Here are optimal image sizes in pixels (NOT retina @2x sizes):
Left-Nav Logo (square): 87 x 87
Mobile-width Logo (rectangle): 113 x 26
Author Avatar: 130 x 130
About page (cover): 890 x 526
Post page photos: 890 x 526
Where to Upload
inside Ghost Admin
Left-Nav Logo: general -> Blog Logo
Mobile-width Logo: general -> Blog Cover
Author Avatar: Users -> User -> Avatar (circle guy)
Static Pages
Blockster supports static pages. To create a static page:
- create a new post
- click on the gear icon button on the post editor page (located at the bottom right, next to the publish/update button)
- check "Turn this post into a static page"
- publish it
Featured Images in Static Pages
If you upload a "featured image" in a static page then the page will be formatted like a post page, with the featured image at the top with the page's title underneath. If you don't set a featured image, no title will be displayed on the page by default. This allows static pages to be treated as "blank slates."
Static Page Templates
About and Contact page templates are built into Blockster. If you don't want either of these, you can disable one or both in the config.hbs file. Otherwise, simply create an about and contact static page for the built-in navigation to work for these pages.
About Page
Blockster's about page template is essentially a blank canvas. Follow the above general rules for Blockster's static pages regarding the about page's featured image and header.
Contact Page
Blockster's contact-page template is more opinionated than the about-page template. Adjust this template to add your own contact info and Google map (everything is optional, include only what you would like).
The following is the contact page for the demo, use it as a starting point and reference:
<phone>(800) 123-1234, (177) 432-4321</phone>
<skype>[View my Skype Profile](skype:SkypeNameHere?userinfo)</skype>
<fax>(800) FAX-STILL-ROCKS</fax>
<address>555 Everyday Lane, Best Town, WA 232323, USA</address>
<website>[Pixel and Kraft Home](http://pixelandkraft.com)</website>
<email>[Click to Email](mailto:[email protected])</email>
<div class=map>
<iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d344863.67023592436!2d-122.22632229780181!3d47.52404578640302!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x5490102c93e83355%3A0x102565466944d59a!2sSeattle%2C+WA!5e0!3m2!1sen!2s!4v1403704783891" width="100%" height="450" frameborder="0"></iframe>
</div>
<blurb>Blockster is made by Pixel & Kraft. Should you like to be in touch for any reason, you now know how to contact us. This "blurb" area will always be shown beside your author photo at the bottom of this default contact-page template.<br>
- The Creators @Pixel&Kraft</blurb>
Smooth Scrolling
To create in-page links that smoothly scroll to an area of the page (anchor links), follow this simple formula:
Add to the link
href="#destination" + data-toggle="smoothScroll"
Add to the destination
id="destination"
Here's an example of a link that would smoothly scroll to the top of the page (assuming that this div with an id of top be located at the top of the page, say, just after the <body> tag):
Link:
<a href="#top" data-toggle="smoothScroll">Go to Top</a>
Destination:
<div id="top"></div>
Banners
Home-page banners are possible as of Blockster version 1.1. Options include top and bottom, minimally formated or unformated.
How to Add a Banner
- Create a new post
- Create an empty div with the class of
bannerToporbannerBottom. - Put your banner content into this div (using html markup).
- Optional: Add a class of
rawto the banner div to remove default margin and padding (inner and outer spacing). - Publish.
Example:
<div class="bannerTop"><b>This is a banner...</b> if and how you use it is up to you. Use it for any sticky content... such as announcements or ads.</div>
Banner Use Cases
Since the top/bottom banner feature simply takes a chunk of html, there are lots of possible ways to use it. Here are a few:
- Advertisments
- Site notifications
- A welcome message
Pro Tip: Use inline css to customize the banners' appearances.
Page Width
Per request of a Blockster user, it's now (as of v1.1) possible to set custom page widths for different breakpoints via the config.hbs file. These settings affect the container width for all non-homepage posts/pages. Rather than editing the theme's core css (which is completely fine, of course, only it's not update-proof), this option allows for quick and easy customization (that is update proof).
Here's what the custom page width settings section of the config.hbs file looks like:
var use_custom_container_width = false; {{! make true to activate any width customizations below }}
{{! initial values here are Blockster's defaults }}
{{! breakpoint values are MAX widths, meaning anything BELOW the px amount will be targeted }}
{{! BREAKPOINTS }}
var breakpoint_1 = '1250px';
var breakpoint_2 = '850px';
var breakpoint_3 = '600px';
{{! WIDTHS }}
var wider_than_breakpoint_1 = '50%';
var breakpoint_1_width = '63%';
var breakpoint_2_width = '75%';
var breakpoint_3_width = '100%';
How To Customize:
First, activate the custom settings by setting use_custom_container_width to true (note that this has no quotes, as it's a simple boolean value). Then, begin making your customizations. All initial settings are Blockster's defaults. Use them as a starting point.
Two sections makeup this area of the config file: 1) Breakpoints 2) Widths.
Breakpoints
The breapoints are MAX widths, which means that their settings are for anything under their pixel value. Pixel values must be used here. To customize, simply change the value.
Widths
Width values can use percentages or pixels.
Nav Widget
(Like the one at the bottom right of this page)
Creating an in-page navigation widget (like the one here in the docs) is simple and easy. Here's how:
Inside of the Markdown editor for a post or page, at the bottom of the page, create two html tags, one for the widget title and the other to wrap the navigation items:
<!-- Title -->
<tocTitlte>NAV WIDGET TITLE HERE</tocTitle>
<!-- Wrapper for navigation items -->
<toc>
NAVIGATION ELEMENTS HERE
</toc>
Then, for each navigation item you'd like in the widget, wrap the name you'd like for the navigation item (this can be anything) inside bracket tags of the heading id to which it should scroll.
Important: Ghost automatically adds an id to every header element in your page. These have no spaces and hyphens are stripped away, leaving one alpha-numeric string. Here are some examples:
markdown: html:
## My Heading <h2 id="myheading">My Heading</h2>
###Hyphenated-heading <h3 id="hyphenatedheading">Hypnentated-heading</h3>
Note: you can have a space after the markdown hashmark heading declaration, or not. Some markdown interpreters care, but the one Ghost is using doesn't.
TIP: You can inspect your post/page's heading ids by right clicking on the text in the page and clicking
inspect element. Then inside of the browser inspector that pops up, look for the id on the h1, h2, h3, h4, h5, or h6 tag. Chrome is suggested for this, but Firefox should also work.
Here's a full example:
<!-- Markdown Page Content -->
### What you need to know
<!-- paragraphs, lists, image, and other content here -->
###Always Remember
<!-- more paragraphs, lists, image, and other content here -->
### Point-3
<!-- more paragraphs, lists, image, and other content here -->
<!-- Nav Widget markup/text -->
<tocTitle>Contents</tocTitle>
<toc>
<whatyouneedtoknow>Knowledge</whatyouneedtoknow>
<alwaysremember>Always Remember</alwaysremember>
<point3>Point Three</point3>
</toc>
Here's the code for the nav-widget here on the Blockster-docs page:
<tocTitle>Contents</tocTitle>
<toc>
<top>Top</top>
<gettingstarted><b>Getting Started</b></gettingstarted>
<blocksterdocs><b>Blockster Docs</b></blocksterdocs>
<postexcerpts>Post Excerpts</postexcerpts>
<featuredimages>Images</featuredimages>
<logosandavatars>Logos and Avatars</logosandavatars>
<staticpages>Static Pages</staticpages>
<smoothscrolling>Smooth Scrolling</smoothscrolling>
<navwidget>Nav Widget</navwidget>
</toc>
Tip: If you have a key section of your page or post that you'd like to stand out, wrap it in
<b></b>tags as seen above for the "Getting Started" and "Blockster Docs" links. In other words, you can use inline html.
You can create these for long or short posts. The idea is to help people quickly and easily navigate to different areas of the page without having to spend time scrolling. Even for a short post, depending on the content, they can be quite nice.
Something Missing?
Is there something missing from these docs? Perhaps you'd like more examples for a particular aspect of working with Blockster? Make a request!
Help us make improve the Blockster docs, contact us to make a request.