Dashi 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 dashi.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:

Portal links

By default Dashi comes with individual pages in support of the member's feature, however, if you prefer the Portal for handling members, go to Settings > Design > Site-Wide, enable the Use portal links flag.

You will need to update where the signin, signup and account links point to. Edit the following files:

1. site-header.hbs

* change href="/signin/" to the sign in link from Portal settings ==> href="#/portal/signin" * change href="/signup/" to the sign up link from Portal settings ==> href="#/portal/signup"

1. site-user-menu.hbs

* change href="/account/" to the account link from Portal settings ==> href="#/portal/account" * change href="/signin/" to the sign in link from Portal settings ==> href="#/portal/signin" * change href="/signup/" to the sign up link from Portal settings ==> href="#/portal/signup"

1. page-membership.hbs

* change href="/signup/" to the sign up link from Portal settings ==> href="#/portal/signup/free" * look for data-members-plan="Monthly" and change href="javascript:void(0)" to the sign up link from Portal settings ==> href="#/portal/signup/monthly" * look for data-members-plan="Yearly" and change href="javascript:void(0)" to the sign up link from Portal settings ==> href="#/portal/signup/yearly"

Links are in the pricing-* partials: pricing/free.hbs, pricing/monthly.hbs,pricing/yearly.hbs.

1. content-cta.hbs

* change href="/signin/" to the sign in link from Portal settings ==> href="#/portal/signin" * change href="/signup/" to the sign up link from Portal settings ==> href="#/portal/signup"

1. welcome.hbs

* change href="/account/" to the account link from Portal settings ==> href="#/portal/account"

theme-config.hbs

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

• GHOST_URL - set your ghost URL here (will be used for the search)
• GHOST_KEY - set the Content API Key here from a custom integration (will be used for the search)
• GHOST_SEARCH_LIMIT - Search result limit
• DEFAULT_VIEW_TYPE - set the default view type (this refers to the post grid on the home page, author and tag pages). Two possible values:
  • grid - two or three-column layout
  • list - single column layout will be used
• DEFAULT_GRID_COLUMNS - - set the number of columns you would like to have on the (home page, author and tag pages). Two possible values:
  • 3 - default is 3 column layout
  • 2 - you can have two column layout as well
• DEFAULT_COLOR_SCHEME - set the default color scheme. Values depend on how many color schemes you define within the theme. By default the theme comes with 4, additional to the preference:
  • 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
  • whitesmoke - the white smoke theme will be the default until the user changes it
  • midnight - the midnight theme will be the default until the user changes it
• ENABLE_COLOR_SCHEME_PICKER - you can enable or disable the color scheme picker for the user, if you only have one theme, the color scheme picker will not be shown. Possible values:
  • true - enabled
  • false - disabled
• 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_SCROLL_TO_TOP - enable or disable the scroll to top function. Possible values:
  • true - scroll to the top will be enabled
  • false - scroll to the top will be disabled
• ENABLE_FILTER - enable or disable the filter on the home and tag page. Possible values:
  • true - enabled
  • false - disabled
• ENABLE_HYPHENS - enable or disable hyphens. Possible values:
  • true - enabled
  • false - 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
• ENABLE_STICKY_HEADER - enable or disable the sticky header. Possible values:
  • true - enabled, the header will remain on top as you scroll
  • false - disabled, the header will not be visible as you scroll
• DISQUS_SHORTNAME - set your own disqus_shortname here
• COVE_ID - if you are using Cove, set your cove id here
• OPEN_LINKS_IN_NEW_TAB - when set to true the external links in posts will be opened in a new tab
• COLOR_SCHEMES - is an array of JSON, with a specific layout, you can add more or modify the existing ones. Example of one color scheme layout:

	{
      "id": "light",
      "name": "Light",
      "colors": {
        "primary": "hsl(253,91%,64%)",
        "primary_dark": "hsl(253,91%,67%)",
        "primary_light": "hsl(253,91%,61%)",
        "secondary": "hsl(20, 92%, 60%)",
        "secondary_dark": "hsl(20, 92%, 63%)",
        "secondary_light": "hsl(20, 92%, 57%)",
        "text": "hsl(0, 0%, 10%)",
        "text_acc_1": "hsl(0, 0%, 20%)",
        "text_acc_2": "hsl(0, 0%, 30%)",
        "text_acc_3": "hsl(0, 0%, 40%)",
        "text_reverse": "hsl(0, 0%, 90%)",
        "bg": "hsl(0, 100%, 100%)",
        "bg_body": "hsl(219,23%,97%)",
        "bg_acc_1": "hsl(0, 0%, 98%)",
        "bg_acc_2": "hsl(0, 0%, 96%)",
        "bg_acc_3": "hsl(0, 0%, 94%)",
        "bg_reverse": "hsl(0, 0%, 10%)",
        "neutral": "hsl(0, 0%, 50%)",
        "border": "hsl(0, 0%, 95%)"
      }
    },

If you add a new one, modify the id, name, and all the colors according to your liking (it can be RGB, hex, or HSL).

Global CSS properties:

<style>
  body {
    --global-max-width: 1280px;
    --global-radius: 2px;
    --global-radius-round: 50%;
    --global-header-position: initial;
    --global-hyphens: none; /* none / auto */
    --global-menu-icons: none;
    --global-menu-alignement: flex-start; /* flex-start / center / flex-end */
    --global-breadcrumb: none; /* none / block */
    --global-menu-cta: flex; /* none / flex */
  }
</style>

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.DEFAULT_COLOR_SCHEME = 'dark'; CONFIG.GRID_COLUMNS = '3';
  CONFIG.SCROLL_TOP = false; CONFIG.IMAGE_LIGHTBOX = false;
</script>

Similarly, you can overwrite all the config values, this has the advantage that even if you download another version of the theme your settings will persist.

Post Templates

Dashi comes with 3 different post templates:

• post.hbs - default
• custom-with-sidebar.hbs - post with sidebar
• custom-with-table-of-contents.hbs - post with table of contents

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.

Fonts

Dashi comes with Google Fonts integrated, using the 'Jost' font. To change the fonts you have to change the default.hbs file.

<link
  rel='preload'
  href='https://fonts.googleapis.com/css2?family=Jost:wght@300;400;500;600;700;800&display=swap'
  as='font'
  onload="this.onload=null;this.rel='stylesheet'"
/>

{{! No Js }}
<noscript>
  <link
    href='https://fonts.googleapis.com/css2?family=Jost:wght@300;400;500;600;700;800&display=swap'
    rel='stylesheet'
  />
</noscript>

Go to Google Fonts and choose the font and styles you would like. Then click Embed and copy the link provided and replace the current one in default.hbs.

Then you have to overwrite the settings in CSS, here you have two options:

1. Code injection

Overwrite the font setting in Ghost Admin. Go to Code Injection then in the Site Header section add these lines:

<style> body { --font-sans: 'your font name'; }</style>

1. Modify the CSS file

Open settings.css file located in assets/css/settings folder. Replace the font setting with your new font:

body { --font-sans: 'Jost', Tahoma, Arial, sans-serif; }

Build the assets (check theme development) and everything should be ready.

Check out this tutorial for a more detailed guide about Google Fonts with Ghost.

Home Page

You have the possibility to customize the Home page, for this, you will have to change the index.hbs file.

If you want to have the sidebar on the homepage as well, just copy the code from index2.hbs to index.hbs.

To change from the 3 column layout to a 2 column layout, simply change the theme-config.hbs file DEFAULT_GRID_COLUMNS to 2.

To change the default view from grid to list open the theme-config.hbs file, change the property DEFAULT_VIEW_TYPE from grid to list.

To do not display post images in the postcard change the show_img=true to show_img=false.

Dashi comes with 3 different home pages:

• index.hbs - 3 column post layout
• index2.hbs - 2 column post layout + sidebar
• index3.hbs - featured section + 2 column post layout + sidebar

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

Home page Hero

The Home page Hero contains a welcome section, which can have different content based on the @member status.

• regular user: call to action to "Subscribe", with a button pointing to the "Sign Up" page.
• signed in, free member: call to action to "Upgrade" pointing to the "Account" page.
• signed in, paying member: simple welcome message, and info about subscription, and link to the "Account" page.

Starting with version 2.1.0 it's possible to set the @site.cover_image background of this hero section. It's also possible to show/hide the stats sections, which show the number of posts in each category (Public, Members, Paid) and the Total posts.

{{> welcome cover-is-bg=true show_stats=true}}

The hero section can also be removed from the index.hbs file. Look for the following text and delete the line:

{{> welcome}}

After you have deleted it upload the modified theme in your Admin section.

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)
• tag cloud
• latest posts - sorted by published date (on posts only)
• authors (on the homepage only)

Custom Pages

Dashi comes with several custom pages by default:

• Contact Page
• Tags Page
• Membership Page
• Archive Page
• Bookmarks Page

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

Contact Page

To create the Contact page, do as follows:

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

There is a contact form included, which requires you to create a formspree account and after you have created your form, copy the endpoint and add it to the action attribute. The link should look like this:

https://formspree.io/f/moqppoep

Open page-contact.hbs in the root folder of the theme and replace the action value with your form spree link.

<form
  action="https://formspree.io/f/moqppoep"
  id="contact-form"
  class="contact-form"
  method="post"
></form>

You can also replace the form with your own if you have one.

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.

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.

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.

Bookmarks Page

The bookmarks page will list all the bookmarked posts by a user. To create the Bookmarks page, do as follows:

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

Announcements

The announcement feature was added with the version 1.2.0 and you can use it to highlight some of your posts which will appear when the user presses the bell icon in the header section.

The bell icon will appear if you have posts with the internal tag #announcement. When the user presses the icon the posts will be shown and it's possible to navigate to that post to read the complete content. By default, the limit is set to 3 but it can be changed in the partials/announcement.hbs file.

Menu status

By default, the menu is closed, but placing a little script in the Code Injection Footer, it's possible to set the side menu open by default for desktop devices.

Here is the script for it:

<script>
  const menuMq = window.matchMedia('(min-width: 767px)');
  const menu = document.querySelector('.js-menu');
  const menuToggle = document.querySelector('.js-menu-toggle');
  const body = document.querySelector('body');
  if (menuMq.matches && menu && body) {
    menu.setAttribute('data-menu-active', '');
    body.classList.add('menu-open');
    menuToggle.classList.add('is-active');
  }
</script>

The menu will be open if the width of the site is at least 767px, but this can be changed to any value.

To disable the animation for the menu you can add the following in the Code Injection Header:

<style>.menu, .main { transition: none!important; }</style>

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.

Menu Icons

Starting with version 2.1.0 you can also have icons for the menu items. Icons for the menu are sourced from assets/icons/menu-icons.svg file. There is a menu-icon.hbs partial to help to add menu icons.

It is expected that in the menu-icons.svg there is section with id of the navigation items` slug containing the SVG code for that icon:

<symbol id="archive" viewBox="0 0 24 24">
  <polyline points="21 8 21 21 3 21 3 8"></polyline>
  <rect x="1" y="3" width="22" height="5"></rect>
  <line x1="10" y1="12" x2="14" y2="12"></line>
</symbol>

If you want to add new icons, you can go to tabler icons, select the icon you want to add copy the code and open the menu-icons.svg. Create a new <symbol> with the relevant id and inside add the code (without the <svg> and </svg> lines).

The icon name has to correspond with the slug property of the menu item. Examples:

The {{slug}} property of the navigation items is generated from the name (label) with dash(-) instead of spaces and without special characters.

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