Nio Theme Documentation

Version 1.0.0
Nio Theme

Introduction

This guide explains how to install, set up, and customize the Nio theme for Ghost. It assumes basic familiarity with Ghost. For general Ghost help, check out the official Ghost documentation.

Installation & Updates

Installing the Theme

To get Nio up and running on your Ghost site:

  1. Log in to your Ghost Admin panel.
  2. Go to Settings > Design & branding > Customize.
  3. Click Change theme at the bottom right.
  4. Choose Upload theme and select the Nio theme zip file.
  5. Click Activate to apply the theme.

Removing the Theme

If you need to remove Nio:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Click Change theme at the bottom right.
  3. Find Nio in the theme list.
  4. Click the ... next to Activate.
  5. Select Delete and confirm.

Note: You can’t delete an active theme. Switch to another theme first if needed.

Updating the Theme

To keep Nio current with the latest features and fixes:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Click Change theme at the bottom right.
  3. Upload the new Nio zip file as described in the installation process.
  4. Activate the updated theme.

Important: Updating will overwrite any changes made directly to theme files. Back up your customizations before updating.

Basic Customization

Your logo is a key part of your site’s identity. Here’s how to set it up:

  1. In Ghost Admin, go to Settings > Design & branding.
  2. In the Brand tab, find Publication logo.
  3. Click Upload logo and choose your image.
  4. Click Save.

For dark mode support, you can set a separate logo:

  1. Go to Settings > Design & branding > Customize.
  2. Find Logo for dark color scheme.
  3. Upload your dark mode logo.
  4. Click Save.

Tip: Use logos with transparent backgrounds for best results.

Copyright Text

Customize the copyright notice in your footer:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Copyright text.
  3. Enter your desired text.
  4. Click Save.

If left empty, the default text will be: ”© [Current Year] Published with Ghost”

Color Scheme

Light Color Scheme
Light Color Scheme
Dark Color Scheme
Dark Color Scheme

Nio offers a simple and elegant color scheme system:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Expand the Site-wide section.
  3. Find the Color scheme dropdown.
  4. Choose from:
    • Light: Always use light mode
    • Dark: Always use dark mode
    • System: Automatically match the user’s system preferences
  5. Click Save.

If you’ve selected dark mode or system mode, you can optionally set a different logo for dark mode:

  1. Find the Logo for dark color scheme setting
  2. Upload your dark mode logo
  3. Click Save

Fonts

Nio supports two ways to customize your site’s typography:

  1. Ghost Native Fonts (Recommended)

    • Available in Ghost 5.104.0 and later
    • Ghost’s built-in typography system offers a carefully curated set of fonts that work well across themes
    • To use native fonts:
      1. Go to Settings > Design & branding
      2. Under the Brand section, scroll to Typography
      3. Choose your desired fonts
    • Native font settings will automatically override the theme’s font settings
    • This is the recommended approach as it provides better consistency and control over your brand

  2. Theme Font Settings

    • If you’re not using Ghost’s native fonts, you can use Nio’s built-in font options:
      1. Go to Settings > Design & branding > Customize
      2. Expand the Site-wide section
      3. Find the Heading font family and Body font family dropdowns
      4. Choose from the available options
      5. Click Save

Note: To ensure you have access to Ghost’s native font feature, make sure you’re using the latest version of the Nio theme. You can update your theme by following the instructions in the “Updating the Theme” section.

Available theme fonts:

Heading FontsBody Fonts
CardoFira Mono
Chakra PetchFira Sans
Fira MonoIBM Plex Serif
Fira SansInter
IBM Plex SerifJetBrains Mono
InterLora
JetBrains MonoManrope
Libre BaskervilleMerriweather
LoraNoto Sans
ManropeNoto Serif
MerriweatherNunito
Noto SansPoppins
Noto SerifRoboto
NunitoSpace Mono
Old Standard TT
Poppins
Roboto
Rufina
Space Grotesk
Space Mono
Tenor Sans

Social Media

Connect with your audience by adding social media icons to your footer. Social icons can be added in two ways:

  1. Via Ghost Admin (for Facebook and Twitter/X):

    • Facebook: Add your Facebook page URL in Settings > General > Social accounts
    • Twitter/X: Add your Twitter/X username in Settings > General > Social accounts

  2. Via Code Injection (for all other platforms):

    1. Go to Settings > Code injection
    2. In the Site Header section, add your social links:
    window.social = {
    instagram: 'https://instagram.com/username',
    linkedin: 'https://linkedin.com/in/username',
    // Add more platforms as needed
};

Supported platforms:

BehanceFacebookPinterest
BlueskyFlickrReddit
DeezerInstagramSnapchat
DiasporaKickstarterSpotify
DiscordLineTelegram
DribbbleLinkedInThreads
MastodonTikTokWeibo
OKTwitchWhatsApp
PatreonVimeoX
XingYouTubeYelp
Zhihu

Primary Navigation

Effective navigation helps readers explore your content easily. Nio supports primary (header) and secondary (footer) navigation, including dropdown submenus in the header navigation.

Primary Navigation (Header)

  1. In Ghost Admin, go to Settings > Navigation.
  2. Edit the “Primary navigation” section.
  3. To create a submenu:
    • Add a parent menu item (e.g., “Resources”)
    • Add submenu items by prefixing them with a dash - (e.g., “-Documentation”, “-Tutorials”)
    • The items will automatically be grouped under the parent menu item
  4. Click Save.

Note: On mobile and smaller screens, menu items that don’t fit in the header will automatically collapse into a “More” dropdown menu.

Secondary Navigation

Secondary Navigation (Footer)

  1. In Ghost Admin, go to Settings > Navigation.
  2. Edit the “Secondary navigation” section.
  3. Add your navigation items.
  4. To customize the column layout:
    • Go to Settings > Design & branding > Customize
    • Find Footer navigation columns
    • Choose from 2, 3, 4, or 5 columns
    • The navigation items will be distributed across the columns
  5. Click Save.

Pagination

Nio uses a “Load More” style pagination that seamlessly loads additional content as readers browse your site:

  1. At the bottom of post listings, a “Load More” button is displayed
  2. Clicking the button loads the next page of posts
  3. Posts are appended to the existing list without a page refresh
  4. When all posts are loaded, an “End of content” message is shown

This approach provides a smooth, modern browsing experience while giving readers control over when to load more content.

Progressive Web App

App Mode allows your site to be installed on Android and iOS devices as a Progressive Web App (PWA). This can improve user experience and engagement by providing a more app-like interface on mobile devices.

To enable App Mode:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find the “Enable app mode” option under the “Site-wide” settings.
  3. Toggle the switch to enable App Mode.
  4. Click “Save” to apply the changes.

When enabled, visitors using compatible mobile browsers will be prompted to add your site to their home screen, creating an app-like shortcut for easy access.

Homepage Features

Highlight your best content by displaying featured posts on your homepage:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Homepage, find Show Featured Posts Section.
  3. Toggle the switch on or off.
  4. Click Save.

To feature a post:

  1. In Ghost Admin, go to Posts.
  2. Select a post.
  3. In the sidebar, find Feature this post.
  4. Toggle the switch on.
  5. Click Update.

For advanced users who want to remove featured posts from the main collection:

  1. In Ghost Admin, go to Settings > Labs.
  2. Click on the Beta features tab.
  3. Find the Routes section.
  4. Upload a routes.yaml file with the following content:
routes:
  collections:
    /:
      permalink: /{slug}/
      filter: featured:false
      template: index
    /featured/:
      permalink: /featured/{slug}/
      filter: featured:true
      template: index

  taxonomies:
    tag: /tag/{slug}/
    author: /author/{slug}/

This configuration creates a separate /featured/ URL for all featured posts and removes them from the main collection. After applying these changes, featured posts will only appear in the dedicated featured section and not in the main post listings.

Highlighted Tag Section

Highlighted Tag Section

You can showcase posts from a specific tag in a beautifully designed section on your homepage:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Highlighted tag under the homepage settings.
  3. Enter the tag slug you want to highlight (e.g., “tutorials”, “featured”, etc.).
  4. Click Save.

The highlighted tag section will display:

  • A large header with the tag’s name and description
  • The tag’s feature image as a background
  • The tag’s accent color for styling
  • Up to 3 latest posts from this tag

To enhance the section’s appearance:

  1. Go to Tags in Ghost Admin
  2. Select the tag you’re highlighting
  3. Add a feature image (used as section background)
  4. Add a description (displayed in the section)
  5. Set an accent color (used for section styling)

Authors List

An Authors page showcases all your site’s contributors. Each author section includes:

  • Author name and bio
  • Profile image
  • Social media links (website, Twitter/X, Facebook)
  • Post count
  • Latest 4 posts by that author

To create an Authors page:

  1. In Ghost Admin, create a new page.
  2. Give it a title (e.g., “Authors” or “Team”).
  3. Open the page settings.
  4. In the Template dropdown, select Authors.
  5. Publish the page.

To enhance author sections:

  1. Go to Staff in Ghost Admin
  2. Select an author to edit
  3. Add a profile image
  4. Add a bio
  5. Add social media links
  6. Click Save

Post Features

Post Layouts

Nio offers 4 different post layouts to customize how your featured image and content are displayed. These layouts are available in the post settings when editing a post.

Image Left: Featured image appears on the left side of the post header

Post Layout Image Left

Image Right: Featured image appears on the right side of the post header

Post Layout Image Right

Full Width Image: Featured image spans the full width above the content

Post Layout Full Width Image

Text First: Content appears before the featured image

Post Layout Text First

To change a post’s layout:

  1. Edit the post in Ghost Admin
  2. Click the gear icon to open post settings
  3. Under Template, choose your desired layout
  4. Update the post

Scroll Indicator

Help readers track their progress through your posts with a scroll indicator:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Enable Scroll Indicator.
  3. Toggle the switch on or off.
  4. Click Save.

Post Suggestions

Help readers discover more content by showing post suggestions:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Show post suggestions under the post settings.
  3. Toggle the switch on or off.
  4. Click Save.

When enabled, related posts will be displayed at the bottom of each post, encouraging readers to explore more of your content.

Comments

Engage with your readers through Ghost’s built-in commenting system:

  1. In Ghost Admin, go to Settings > Membership.
  2. Click Edit in Access.
  3. Choose who can comment: Nobody, Paid members, or All members.
  4. Click Save.

Syntax Highlighting

Make your code snippets more readable with syntax highlighting:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. In Post, find Enable Syntax Highlighting.
  3. Toggle the switch on or off.
  4. Click Save.

Custom Pages

Authors Page

An Authors page showcases all your site’s contributors. Each author section includes:

  • Author name and bio
  • Profile image
  • Social media links (website, Twitter/X, Facebook)
  • Post count
  • Latest 4 posts by that author
Authors Page

To create an Authors page:

  1. In Ghost Admin, create a new page.
  2. Give it a title (e.g., “Authors” or “Team”).
  3. Open the page settings.
  4. In the Template dropdown, select Authors.
  5. Publish the page.

To enhance author sections:

  1. Go to Staff in Ghost Admin
  2. Select an author to edit
  3. Add a profile image
  4. Add a bio
  5. Add social media links
  6. Click Save

Tags Page

A Tags page helps readers discover content by presenting all tags used on your site. Each tag section includes:

  • Tag name and description
  • Feature image (if set)
  • Post count
  • Latest 4 posts from that tag
Tags Page

To create a Tags page:

  1. In Ghost Admin, create a new page.
  2. Give it a title (e.g., “Tags” or “Topics”).
  3. Open the page settings (gear icon in the top right).
  4. In the Template dropdown, select Tags.
  5. Publish the page.

To enhance tag sections:

  1. Go to Tags in Ghost Admin
  2. Select a tag to edit
  3. Add a feature image
  4. Add a description
  5. Click Save

Remember to add your Tags page to your site’s navigation menu for easy access.

Contact Page

The Contact page allows visitors to send messages directly through your site. It uses Formspree or Getform for form submissions.

Contact Page

To create a Contact page:

  1. In Ghost Admin, go to Settings > Design & branding > Customize.
  2. Find Contact form url and enter your Formspree or Getform URL.
  3. Create a new page and select Contact from the Template dropdown.
  4. Publish the page.

Customize the page content to include additional contact information or instructions as needed.

Empty Template

The Empty template provides a blank canvas without header or footer. Use it for landing pages or custom layouts where you need full control over the page content.

To use the Empty template:

  1. Create a new page in Ghost Admin.
  2. In page settings, select “Empty” from the Template dropdown.
  3. Add your content and publish.

This template is ideal for creating unique, standalone pages within your Ghost site.

Development

Nio is a modern, minimal Ghost theme built with:

  • Vite for build tooling
  • Tailwind CSS for styling
  • TypeScript for enhanced JavaScript functionality
  • PhotoSwipe for image galleries
  • Infinite scroll for content loading

Development Setup

To edit the theme files:

  1. Download the theme ZIP file from Ghost Admin.
  2. Unzip the file on your local machine.
  3. Open the theme folder in your preferred code editor.

The theme uses Tailwind CSS for styling and TypeScript for scripts. You’ll need to set up a development environment to work with these files.

Setting Up the Development Environment

  1. Ensure you have Node.js installed on your system.
  2. Open a terminal/command prompt in the theme folder.
  3. Run npm install to install the required dependencies.

Working with Tailwind and TypeScript

The theme uses Vite to bundle and compile Tailwind CSS and TypeScript files. To work with these files:

  1. Make your changes in the assets/css/*.css or assets/js/*.ts files.
  2. Run npm run dev to start Vite in watch mode. This will automatically compile your changes.
  3. To build for production, run npm run build.

Important Files and Folders

  • assets/css/: Contains CSS files
  • assets/js/: Contains TypeScript files
  • partials/: Contains reusable Handlebars template parts
  • tailwind.config.cjs: Tailwind configuration
  • vite.config.js: Vite build configuration

Remember to thoroughly test all changes across different devices and browsers before deploying to a live site.

Language Translations

This theme is translated into multiple languages. The translation files are located in the locales/ folder.

LanguageCode
🇿🇦 Afrikaansaf
🇦🇱 Albaniansq
🇧🇦 Bosnianbs
🇧🇬 Bulgarianbg
🇪🇸 Catalanca
🇨🇳 Chinesezh
🇹🇼 Chinese (Traditional)zh-Hant
🇭🇷 Croatianhr
🇨🇿 Czechcs
🇩🇰 Danishda
🇳🇱 Dutchnl
🇬🇧 Englishen
🌍 Esperantoeo
🇫🇮 Finnishfi
🇫🇷 Frenchfr
🇩🇪 Germande
🇨🇭 German (Swiss)de-CH
🇬🇷 Greekel
🇭🇺 Hungarianhu
🇮🇸 Icelandicis
🇮🇩 Indonesianid
🇮🇹 Italianit
🇯🇵 Japaneseja
🇰🇷 Koreanko
🇱🇹 Lithuanianlt
🇲🇰 Macedonianmk
🇲🇾 Malayms
🇲🇳 Mongolianmn
🇳🇴 Norwegianno
🇳🇴 Norwegian Nynorsknn
🇵🇱 Polishpl
🇵🇹 Portuguesept
🇧🇷 Portuguese (Brazil)pt-BR
🇷🇴 Romanianro
🏴󠁧󠁢󠁳󠁣󠁴󠁿 Scottish Gaelicgd
🇷🇸 Serbiansr
🇱🇰 Sinhalasi
🇸🇰 Slovaksk
🇸🇮 Sloveniansl
🇪🇸 Spanishes
🇸🇪 Swedishsv
🇹🇭 Thaith
🇹🇷 Turkishtr
🇺🇦 Ukrainianuk
🇺🇿 Uzbekuz
🇻🇳 Vietnamesevi

To use a different language:

  1. In Ghost Admin, go to Settings > General.
  2. Set the “Site language” to the desired language code (e.g., “es” for Spanish).

To modify translations:

  1. Open the corresponding language file in the locales/ folder (e.g., es.json for Spanish).
  2. Edit the translations as needed.
  3. Save the file and rebuild the theme.

Support

If you need additional help with the theme, please contact me at support@luxethemes.com.

Good luck with your site!

All the best,
Stefan from LuxeThemes