Nikko Documentation

Install the theme

Follow the steps below to upload the theme:

1. Log in to your publication admin section at yoursite.com/ghost/
2. Go to Settings > Design ( yoursite.com/ghost/#/settings/design/ )
3. Click Change theme ( yoursite.com/ghost/#/settings/design/change-theme )
4. Click Upload theme and select the nikko.zip file.
5. After the upload is complete, under Installed themes click Activate

Routes setup

Follow the steps below to upload the routes.yaml file (this is a separate step from theme upload)

1. Log in to your publication admin section at yoursite.com/ghost/
2. Go to Settings > Labs ( yoursite.com/ghost/#/settings/labs )
3. Under Beta features click on Upload routes file button and select the file from the root directory of the theme.

Custom settings

The theme comes with custom design settings, which are accessible from the Ghost Admin panel. To view and edit these settings go to Settings > Design & Branding ( yoursite.com/ghost/#/settings/design/)

Custom settings are defined in the package.json file. These settings are placed under three categories:

1. Site-wide settings
2. Homepage settings
3. Post settings

Here's a preview of the available settings:

theme-config.hbs

In this file you will find a config array where you can change the following options:

• DEFAULT_COLOR_SCHEME - set the default color scheme
  • preference - will detect the user preference (os color scheme)
  • light - the light theme will be set as default, until the user changes it
  • dark - the dark theme will be set as default, until the user changes it
• ENABLE_FLOATING_HEADER - enable/disable the floating header
  • true - header will disappear when scrolling down and will be pinned when scrolling up
  • false - header will be sticky all the time
• ENABLE_IMAGE_LIGHTBOX - enable or disable the image lightbox on posts. Possible values:
  • true - image lightbox will be enabled
  • false - image lightbox will be disabled
• ENABLE_PWA - enable or disable Progressive web app functionality. Check the progressive web app section in the documentation to see what you have to add for this to work. Possible values:
  • true - enabled
  • false - disabled
• DISQUS_SHORTNAME - set your own disqus_shortname here
• COVE_ID - if you are using Cove, set your cove id here

You can either change the theme-config.hbs file or you can also use the Ghost Admin to change these values. In Ghost Admin go to Code Injection then in the Site Header section you can change the config like this:

<script>
  CONFIG.ENABLE_FLOATING_HEADER = true; CONFIG.GHOST_SEARCH_LIMIT = 5;
  CONFIG.IMAGE_LIGHTBOX = false;
</script>

Besides the CONFIG array you can also change some global css properties:

• --global-theme-notifications - enable or disable the theme notifications(for signin/signup/subscribe events). Possible values:
  • none - disable
  • flex - enable
• --global-theme-toggle - enable or disable the theme toggle. Possible values:
  • none - disable
  • flex - enable
• --global-search - enable or disable the search. Possible values:
  • none - disable
  • flex - enable
• --global-max-width - Set the site max width. Ex 1280px
• --global-content-width - Set the post content max width. Ex 40rem
• --global-radius - Set the radius of the UI elements. Ex 5px
• --global-header-height - Set the height of the header. Ex 80px
• --global-progress-bar - enable or disable the progress bar. Possible values:
  • visible - enable
  • hidden - disable
• --global-scroll-top - enable or disable the scroll top icon/function. Possible values:
  • visible - enable
  • hidden - disable

To change these values you can either change the theme-config.hbs file or you can use the Ghost Admin (go to Code Injection then in the Site Header)

<style>
  body {
    --global-max-width: 1400px;
    --global-radius: 20px;
    --global-header-height: 100px;
  }
</style>

Post Templates

Nikko comes with 5 different post templates:

• post.hbs - default
• custom-with-sidebar.hbs - post with sidebar
• custom-with-table-of-contents.hbs - post with table of contents
• custom-with-background-image.hbs - post with hero and image as the background
• custom with-full-width-image.hbs - post with a full-width image (limited to site width)

When a new post is created, automatically the default post template is assigned. You can change it by going to Post Settings, and under the Template section select the template you would like for the post.

Search

Native search functionality is integrated with version v1.7.0, this works out of the box, no configuration needed.

Other possible options to add Search to Ghost CMS Themes.

Fonts

Nikko comes with Google Fonts integrated, using the 'Inter' font by default. You can use Ghost custom fonts to set the heading and body fonts for your site. This can be done from Settings > Design > Brand > Typography.

Home Page

The home page is customizable, if you want to make changes to the layout you have to change the index.hbs file.

Nikko comes with 4 different home layouts:

• index.hbs - hero CTA for subscription, a two-column layout formed by posts and sidebar, a list of authors and tags
• index2.hbs - personal profile style, content from a custom page (using internal tag #profile), a list of tags
• index3.hbs - featured posts slider, a 3 column post-card layout, a list of authors and tags
• index4.hbs - intro overlay, featured posts slider, a simple one-column layout formed by posts, a list of tags

If you want to set one of the alternatives as your default home page, open the file copy the code and paste it into index.hbs replacing the current code.

If you use the featured section and want to remove the featured posts from the rest of the home page, you can do that by modifying the routes.yaml file. More specifically the collections section, adding the filter:

collections:
  /:
    permalink: /{slug}/
    template: index
    filter: featured:false

The above setup will exclude featured posts from the main collection and to have a working URL the featured posts have to be part of another collection. For example, you can define an additional collection (/featured/):

/featured/:
  permalink: /{slug}/
  template: index
  filter: featured:true

The postcard appearance can be adjusted with several properties that can be passed to the post-card.hbs helper:

{{> post-card
  show_img=true
  show_access=false
  show_excerpt=true
  is_reversed=false
  class="col"
}}

• show_img - to show/hide the image of the postcard
• show_access - to show/hide the access level of the post (Public, Members, Paid Members)
• show_excerpt - to show/hide the excerpt
• is_reversed - to have a reversed style card
• class - to pass any other class to the post-card (col - will modify the postcard layout to be column-based)

Personal home page

If you opt for this home page (index2.hbs) then the most important thing is to create a new page where the data for the home page will be taken from.

On the page, the hero section will take the following data from the created page:

• feature_image - page image will be used as the main image of the hero section
• title - the title of the page will be displayed in the hero section
• custom_excerpt - the excerpt will be used as the description right before the subscribe form
• content - the content of the page will be displayed after the hero section.

The hero-profile.hbs partial is used to render the personal hero section.

The content from the demo:

<!-- Stats section -->
<div class="row m-b">
  <div class="col-xs-12 col-sm-6 col-md-3 m-b">
    <div class="stat flex-cc radius p bg-acc-1 h-100 flex flex-col text-center">
      <div class="stat_count text-20 fw-800 text-gradient">10+</div>
      <div class="stat_text text-acc-3">Years of experience.</div>
    </div>
  </div>

  <div class="col-xs-12 col-sm-6 col-md-3 m-b">
    <div class="stat flex-cc radius p bg-acc-1 h-100 flex flex-col text-center">
      <div class="stat_count text-20 fw-800 text-gradient">80+</div>
      <div class="stat_text text-acc-3">Successful projects.</div>
    </div>
  </div>

  <div class="col-xs-12 col-sm-6 col-md-3 m-b">
    <div class="stat flex-cc radius p bg-acc-1 h-100 flex flex-col text-center">
      <div class="stat_count text-20 fw-800 text-gradient">50+</div>
      <div class="stat_text text-acc-3">Satisfied customers.</div>
    </div>
  </div>

  <div class="col-xs-12 col-sm-6 col-md-3 m-b">
    <div class="stat flex-cc radius p bg-acc-1 h-100 flex flex-col text-center">
      <div class="stat_count text-20 fw-800 text-gradient">100%</div>
      <div class="stat_text text-acc-3">Professional & dedicated.</div>
    </div>
  </div>
</div>

<!-- What I do section -->
<div class="section__title m-b">What I do</div>
<div class="row m-b">
  <div class="col-xs-12 col-md-4 m-b">
    <div class="card p-lg h-100 flex flex-col">
      <h3 class="card__title">UX/UI Design 🎨</h3>
      <div class="card__description flex-1">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi.
      </div>
      <a href="https://nikko.brightthemes.com/" class="card__cta btn btn--xs"
        >Read more</a
      >
    </div>
  </div>

  <div class="col-xs-12 col-md-4 m-b">
    <div class="card p-lg h-100 flex flex-col">
      <h3 class="card__title">Web Development 🖥️</h3>
      <div class="card__description flex-1">
        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
        dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
        proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
      </div>
      <a href="https://nikko.brightthemes.com/" class="card__cta btn btn--xs"
        >Read more</a
      >
    </div>
  </div>

  <div class="col-xs-12 col-md-4 m-b">
    <div class="card p-lg h-100 flex flex-col">
      <h3 class="card__title">Ghost Themes 👻</h3>
      <div class="card__description flex-1">
        Gravida rutrum quisque non tellus orci ac auctor. Consectetur purus ut
        faucibus pulvinar elementum integer enim neque volutpat. Aliquet nec
        ullamcorper sit amet risus. Amet tellus cras adipiscing.
      </div>
      <a href="https://nikko.brightthemes.com/" class="card__cta btn btn--xs"
        >Read more</a
      >
    </div>
  </div>
</div>

<!-- About me section -->
<div class="section__title m-b">About me</div>
<div class="row">
  <div class="col-xs-12 col-md-6 m-b-lg">
    <p class="p-lg bg-acc-1 text-acc-2">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
      veniam, quis nostrud exercitation ullamco laboris nisi. Sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua.
    </p>

    <p class="p-lg bg-acc-1 text-acc-2 m-b-0">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
      veniam, quis nostrud exercitation ullamco laboris nisi.
    </p>
  </div>
  <div class="col-xs-12 col-md-6">
    <details>
      <summary>1. Velit aliquet sagittis id consectetur purus?</summary>
      <p>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Dignissim enim sit
        amet venenatis urna.
      </p>
    </details>

    <details>
      <summary>2. Ornare lectus sit amet est placerat in egestas?</summary>
      <p>
        Velit aliquet sagittis id consectetur purus ut faucibus pulvinar. Platea
        dictumst quisque sagittis purus. Nullam eget felis eget nunc lobortis
        mattis aliquam faucibus.
      </p>
    </details>

    <details>
      <summary>3. Euismod elementum nisi quis eleifend quam?</summary>
      <p>
        Ornare lectus sit amet est placerat in egestas erat imperdiet. Enim nunc
        faucibus a pellentesque. Facilisis magna etiam tempor orci eu lobortis
        elementum nibh tellus.
      </p>
    </details>

    <details class="m-b-0">
      <summary>4. Morbi non arcu risus quis varius quam quisque?</summary>
      <p>
        Feugiat in fermentum posuere urna nec tincidunt praesent semper. Tortor
        id aliquet lectus proin. Sit amet commodo nulla facilisi. Eros donec ac
        odio tempor orci dapibus.
      </p>
    </details>
  </div>
</div>

Home page hero

The hero-cta.hbs partial is used to render the hero section on the default home page.

If you are looking to change the content of the hero section you have to adapt the text in the file, which is in the partials directory. You can change the appearance of the section with some parameters that the helper comes with:

{{> hero-cta
  img_bg=true
  class="bg-gradient"
  form_class="is-joined"
}}

• img_bg - should the image be a background (cover)
• class - pass any other class to the hero (such as a background)

The section also contains the subscribe form to sign up as a member.

Sidebar

To change the content of the sidebar you have to edit the sidebar.hbs file in the partials folder. By default the theme contains the following sections:

• subscribe/upgrade section (on posts only)
• featured posts (on posts only)
• latest posts - sorted by published date (on posts only)

Custom Pages

Nikko comes with several custom pages by default:

• Tags Page
• Authors Page
• Archive Page
• Membership Page

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

Tags Page

To create the Tags page, do as follows:

• Create a new page and call it Tags.
• Make sure the Page URL is tags.
• Click Publish.

Authors Page

To create the Authors page, do as follows:

• Create a new page and call it Authors.
• Make sure the Page URL is authors.
• Click Publish.

Archive Page

The archive page will list all posts starting from the latest, grouped by year. To create the Archive page, do as follows:

• Create a new page and call it Archive.
• Make sure the Page URL is archive.
• Click Publish.

Membership Page

To create the Membership page, do as follows:

• Create a new page and call it Membership.
• Make sure the Page URL is membership.
• Click Publish.

Translations

By default, everything is in English (en.json), additionally, the theme comes with translations in:

• 🇩🇪 German (de.json)
• 🇪🇸 Spanish (es.json)
• 🇫🇷 French (fr.json)
• 🇮🇹 Italian (it.json)
• 🇳🇱 Dutch (nl.json)
• 🇵🇹 Portuguese (pt.json)

If you want to edit the translation in a specific language, you have to edit the corresponding translation file. The files are stored in the locales directory (inside the theme zip).

|__ locales
|   |__ de.json
|   |__ en.json
|   |__ es.json
|   |__ fr.json

If the language file for your language doesn't exist, you have to create it (make sure to use the correct language code) The best way is to copy the content en.json file in your new language file, then change the translations.

Social links

Social links are shown in the footer and by default, the theme comes with:

• Facebook (Settings > General > Social accounts)
• Twitter (Settings > General > Social accounts)
• RSS

To add other links you need to edit the partials/social-links.hbs file. There are several other links in there already, you just have to uncomment the relevant parts and add your link in the href attribute.

Comments

The theme uses the native Ghost comment feature. The Native Comment System requires at least Ghost v5.9.0, you have to enable it from Settings > Membership > Access > Commenting.

Here are the options you can choose from:

• All members - Logged-in members
• Paid-members only - Only logged-in members with an active subscription
• Nobody - Disable commenting completely

Icons

The icons used in the theme are from Tabler Icons, the library consists of 4000+ icons. Not all icons from the library are included to save on the file size, but the most common icons are included in an icon sprite file.

This file is placed in the /assets/icons/ directory in SVG format: icon-sprite.svg. The icons are placed in separate <symbol> tags with a unique id.

Here are the steps to add new icons:

1. Go to Tabler Icons and click on the Icon you want to add, this will copy the code to your clipboard.
2. Open the file (icon-sprite.svg) in a text editor and go to the end of the file.
3. After the last <symbol> create a new <symbol> tag with a unique id (which can be the icon name)
4. Paste the code from the clipboard inside the opening <symbol> and closing </symbol> tags
5. Remove the line starting with <svg and also the closing </svg> tag from the code you pasted.
6. Save the file.

For using the icons inside the theme files, there is a special partial file partials/icon.hbs which accepts name and size as parameters.

Let's see an example and try to add a new icon. Assuming we want to add the icon battery-charging and by clicking on the icon on the website, we get this code:

<svg
  xmlns="http://www.w3.org/2000/svg"
  class="icon icon-tabler icon-tabler-battery-charging"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  stroke-width="1.5"
  stroke="#2c3e50"
  fill="none"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <path stroke="none" d="M0 0h24v24H0z" fill="none" />
  <path
    d="M16 7h1a2 2 0 0 1 2 2v.5a0.5 .5 0 0 0 .5 .5a0.5 .5 0 0 1 .5 .5v3a0.5 .5 0 0 1 -.5 .5a0.5 .5 0 0 0 -.5 .5v.5a2 2 0 0 1 -2 2h-2"
  />
  <path d="M8 7h-2a2 2 0 0 0 -2 2v6a2 2 0 0 0 2 2h1" />
  <path d="M12 8l-2 4h3l-2 4" />
</svg>

As explained before, we don't need the <svg> tags just what is inside, as we will place them in <symbol> tags. So the code we will place in the icon-sprite.svg will look like this:

<symbol id="battery-charging" viewBox="0 0 24 24">
  <path stroke="none" d="M0 0h24v24H0z" fill="none" />
  <path
    d="M16 7h1a2 2 0 0 1 2 2v.5a0.5 .5 0 0 0 .5 .5a0.5 .5 0 0 1 .5 .5v3a0.5 .5 0 0 1 -.5 .5a0.5 .5 0 0 0 -.5 .5v.5a2 2 0 0 1 -2 2h-2"
  />
  <path d="M8 7h-2a2 2 0 0 0 -2 2v6a2 2 0 0 0 2 2h1" />
  <path d="M12 8l-2 4h3l-2 4" />
</symbol>

It's important that the id is uniques and there is no other <symbol> with the same id. After copy-pasting this into the icon-sprite.svg and saving it, we can use the new icon in the theme, like this:

{{>icon name="battery-charging" size="md"}}

Wherever you put this code, will render the icon.

Syntax highlighting

Nikko comes with built-in syntax highlight functionality, provided by Prism.js. To optimize this integration and not load the script and style all the time, you can activate it using an internal tag.

If needed the integration can be changed or extended to other languages or prism tools(default.hbs):

{{!-- Syntax highlighting plugin - can be activated using #syntax-highlight internal tag --}}
{{#post}}
  {{#has tag="#syntax-highlight"}}
    {{!-- Preloading --}}
    <link rel="preload" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/themes/prism.min.css" as="style">
    <link rel="preload" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/prism.min.js" as="script">

    {{!-- Script and style --}}
    <link rel="preload stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/themes/prism.min.css"
      as="style" onload="this.onload=null;this.rel='stylesheet'" crossorigin/>
    <script async defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/prism.min.js"></script>
  {{/has}}
{{/post}}

Theme development

If you want to make more advanced changes to the theme, or you want to develop your components, the theme comes with a developer-friendly setup. You can take advantage of the Gulp tasks that are set up for compiling Javascript and PostCSS.

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

Follow the official guide for installing Ghost locally. After you have installed Ghost and put the theme directory inside the content/themes/ directory, run the following commands in the theme directory:

npm install

This will install all the dependencies for the theme

Then run:

gulp

This will compile PostCSS and javascript and will watch for changes. So when you edit a .hbs, .css or .js file the change will trigger the gulp watch task and this will compile the assets whenever you change a file.

If you want to compile just CSS:

gulp css

If you want to compile just JS:

gulp js