Siwa Ghost Theme Documentation

Table of Contents

Theme Installation

1. Log in to your Ghost website admin (example.com/ghost).
2. Click the settings icon ( ) at the bottom of the left-hand side.
3. Go to Site > Theme.
4. Click Change theme.
5. Click Upload theme.
6. Select the siwa.zip theme file.
7. When the upload finishes, click Activate.

Upload the routes.yaml File (⚑ Required)

After you upload the theme ZIP, upload the routes file:

1. Unzip the siwa.zip theme file.
2. In your Ghost admin, click the settings icon ( ) at the bottom of the left-hand side.
3. Go to Labs.
4. From the Routes section, click the Upload routes YAML button.
5. Upload the routes.yaml file from the extracted theme folder.

Design Settings

Site Identity and Logo

Set the site title and description in Settings → General.

To add a logo, go to Settings → Site → Design & branding → Customize → Brand, upload the logo, and click Save.

Color Scheme

Go to Settings → Site → Design & branding → Customize → Theme → Site wide and choose a Color scheme.

Siwa includes:

1. Default Colors
2. Custom Colors
3. Cloud Dancer
4. Kombu Green
5. Port Royale
6. Sodalite Blue

If you choose Custom Colors, use the Background color and Text color settings to set your own palette.

Accent Color

Set the site accent color in Settings → Site → Design & branding → Customize → Brand → Accent color.

Siwa uses accent color for buttons and links.

Ghost Custom Fonts

Siwa supports Ghost Custom Fonts.

To change fonts, open Settings → Site → Design & branding → Customize and use the typography controls in Ghost Admin.

Siwa uses Instrument Sans for headings and DM Sans for body text and menus by default.

Section and Post Card Colors

Use internal color tags to change the background of the introduction, testimonials, newsletter section, or post cards.

These tags start with # and are hidden from readers. Siwa sets the text color automatically to keep it readable.

Upload the Supplied Tags

Unzip siwa.zip to find theme-tags.json, which contains Siwa’s feature tags and color presets.

1. Open Settings → Advanced → Import/Export in Ghost Admin.
2. Under Export, click Export content to save a backup of your content.
3. Under Import, click Universal import.
4. Select theme-tags.json from the unzipped theme folder.
5. When the import finishes, open Tags → Internal tags to see the imported tags.

Use a Color

1. Open the post or page in Ghost Admin.
2. Under Post settings → Tags or Page settings → Tags, select a color tag, such as #color-lime.
3. Publish or update the post or page.

Use one color tag per post or page.

Add a New Color

1. Open Tags → New tag in Ghost Admin.
2. Enter a name such as #color-sage.
3. Choose an Accent color.
4. Click Save.

Follow Use a Color to apply the new tag to a post or page.

Edit a Color

1. Open the color tag under Tags → Internal tags.
2. Change its Accent color.
3. Click Save.

The new color applies to every post or page using that tag.

Drop Caps

Siwa includes two drop-cap utility classes for post content:

u-drop-cap-small
u-drop-cap-large

To use one, add an HTML card in the Ghost editor and apply the class to the paragraph.

Example:

<p class="u-drop-cap-large">Your opening paragraph...</p>

Homepage

Siwa shows sections in this order: introduction, testimonials, Featured, and Latest Stories. A newsletter section can appear before the footer.

Introduction

Create a page to control the text and media at the top of your homepage.

1. Open Pages in Ghost Admin.
2. Create a new page.
3. Enter your introduction heading as the page title.
4. Add paragraphs, buttons, or other content in the editor.
5. Open Page settings.
6. Set Page URL to home.
7. Add an optional Excerpt.
8. Add an optional feature image.
9. Publish the page.

Open your homepage to see the introduction.

To change the introduction background, add an internal color tag to the page.

If the introduction is missing, check the following:

• Confirm that the page is published.
• Check that Page URL is home.
• Confirm that Siwa’s routes file is uploaded.

Introduction Video

1. Open your home page.
2. Add a Video card, YouTube embed, or Vimeo embed in the editor.
3. Open Page settings → Template.
4. Select Post Video.
5. Publish or update the page.

The first video appears beside your introduction. Add a feature image to choose the image shown before playback.

Select Play on the homepage to watch the video with sound.

If the video stays in the text column, check that Post Video is selected.

Testimonials

Create one page for each reader quote you want to show.

1. Create a page in Pages.
2. Enter the person’s name as the title.
3. Write the quote in the page body.
4. Open Page settings.
5. If needed, add the person’s role or company in Excerpt.
6. Add the internal tag #testimonial.
7. Publish the page.

Your quotes appear below the introduction, newest first.

Add an internal color tag to change a quote’s background.

Featured Posts

Siwa shows up to three featured posts.

Posts using the Post Video template can show a muted autoplay preview in this section.

To add a post to the Featured section:

1. Open a post in Ghost Admin.
2. Open Post settings.
3. Turn on Feature this post.
4. Click Update or Publish.

Use an internal color tag to set a card background.

Latest Stories

Latest Stories automatically shows up to six recent posts that are not already shown in Featured.

Click the Latest Stories heading to go to the Latest page.

Site Newsletter

The site-wide newsletter section appears before the footer for signed-out visitors when Ghost Members is enabled.

To create it:

1. Create a new page in Ghost Admin.
2. Use the page title as the newsletter heading.
3. Add a custom excerpt for the short description.
4. Add a feature image if you want a split image layout.
5. Add the internal tag #newsletters.
6. Publish the page.

The newsletter choices come from Ghost newsletters. Manage them in Ghost Admin under Settings → Membership → Newsletters.

Add an internal color tag to change the section background.

If the newsletter section is missing, check that memberships are enabled and the #newsletters page is published. The section is hidden for signed-in members.

Navigation

You can add, edit, delete, and reorder the primary navigation menu in Ghost Admin from Settings → Site → Navigation.

To add a page:

1. Type the label as it should appear.
2. Click the item’s URL field.
3. Add the page slug after the final / and click Save.

Dropdown Menus and Navigation Previews

Siwa supports desktop dropdown menus from Ghost Primary navigation.

Add a parent navigation item, then add child items below it by starting the child label with a hyphen and a space.

Example:

Archive Pages
- Tag Page
- Tags Directory
- Author Page
- All Stories

The child links are grouped under the closest parent item above them.

If the parent item is only a group label, use # as its URL. If the parent should open a real page, use that page URL.

On desktop, internal dropdown links can show a preview image. Siwa uses:

1. Post and page feature images.
2. Tag feature images.
3. Author profile images, with author cover images as a fallback.

External links and internal links without images still work as normal text links. The preview is an enhancement, not a required setup step.

Video Previews in Navigation

Navigation previews can also show muted video previews for links to posts using the Post Video template.

For best results:

1. Use the Post Video template on the linked post.
2. Add a native Ghost video card, YouTube embed, or Vimeo embed to the post.
3. Add a feature image if you want to choose the static preview shown while the video loads.

If the video preview cannot play, Siwa keeps the link usable and shows a static preview when possible.

Secondary Navigation / Footer

Like Header Navigation, you can add the footer navigation links from the Ghost admin Settings → Site → Navigation.

Pages

Siwa includes index-style pages for recent posts, older stories, and tags.

Latest and Archive are created by the theme routes.yaml file. Tags Directory is a Ghost page that uses a custom template.

Latest Page

The Latest page lives at /latest/. It is created by routes.yaml, so you do not need to create a Ghost page for it.

Readers see recent posts in the standard post grid. Load more appears when there are more posts than the page limit.

To add it to navigation:

1. Go to Settings → Site → Navigation.
2. Add a label such as Latest or Latest Stories.
3. Use /latest/ as the URL.
4. Click Save.

Archive Page

The Archive page lives at /archive/. It is created by routes.yaml, so you do not need to create a Ghost page for it.

Readers see a date-led list of posts. On desktop, each row can show the post feature image on hover.

To add it to navigation:

1. Go to Settings → Site → Navigation.
2. Add a label such as Archive or All Stories.
3. Use /archive/ as the URL.
4. Click Save.

Tags Directory

The Tags Directory page shows up to 100 public tags.

To create it:

1. Create a new page in Ghost Admin.
2. Use a title like Tags.
3. Add a custom excerpt if you want intro text below the title.
4. Add a feature image if you want a media hero.
5. Open Page settings.
6. Select the Tags Directory template.
7. Publish the page.

Siwa shows the page title, custom excerpt, feature image, and public tags ordered by name.

Tag and Author Pages

Ghost automatically creates native tag pages at /tag/tag-slug/. Siwa uses each tag’s name, description, feature image, and accent color.

Ghost automatically creates native author pages at /author/author-slug/. Siwa uses the author’s name, bio, profile image, cover image, location, website, and social links when available.

Post Layouts

Siwa includes the default post layout plus four custom post templates.

To choose a layout:

1. Open a post in Ghost Admin.
2. Open Post settings.
3. Choose a template from the Template dropdown.
4. Click Update or Publish.

Default Post

Use the default layout for standard articles. It shows the post title, excerpt, metadata, optional feature image, reading tools, content, authors, comments, and related posts.

Post Hero

Use Post Hero for image-led stories that need a large media hero with the title over the image.

Add a feature image for the hero. Without a feature image, the post opens with a simple centered header.

Post Fullscreen

Use Post Fullscreen for stories where the opening image should fill the first viewport.

Add a feature image for the fullscreen hero. Without a feature image, the post opens with a simple centered header.

Post Split

Use Post Split for stories that need a split opening: image on one side, title and metadata on the other.

Add a feature image for the split media. Without a feature image, the post opens with a simple centered header.

Post Video

Use Post Video for stories where video is the lead media.

The first eligible video in the post content is promoted into the top video area. The article body remains readable below it.

Video Stories and Previews

Siwa supports video in three places: video story pages, post cards, and navigation previews.

Create a Video Story

1. Open a post in Ghost Admin.
2. Add a native Ghost video card, YouTube embed, or Vimeo embed to the post content.
3. Open Post settings.
4. Choose the Post Video template.
5. Add a feature image to use as the video poster before playback.
6. Publish or update the post.

Siwa uses the first eligible video in the post content as the top video. The original video card is removed from the visible article flow so the video does not appear twice.

For Vimeo, copy the complete share link.

Video Previews

Posts using the Post Video template can show muted previews in post cards, the Featured section, and navigation previews.

Video previews are an enhancement. Readers can still open the post normally if a preview cannot play.

Supported Video Sources

For the video story layout and previews, use:

1. Native Ghost video cards.
2. YouTube embeds.
3. Vimeo embeds.

Other embeds may still appear in post content, but they are not treated as Siwa video preview sources.

Membership and Newsletters

Siwa uses Ghost Memberships, Portal, paid content, comments, and newsletters directly.

When Members is enabled:

1. Signed-out visitors see a Subscribe link in the header.
2. Signed-in members see an Account link.
3. Member-only posts show an upgrade or subscribe prompt when needed.
4. The site newsletter section can appear before the footer when a newsletter page exists.

Disable Membership Components

To remove membership links, forms, and paid-content prompts from the theme, disable membership access in Ghost Admin.

1. Go to Settings → Membership → Access.
2. Select Nobody.
3. Click Save.

Check Signup

Open your site in a private window. Subscribe with your email address. Follow the confirmation email to complete signup.

Remove Ghost Portal / The Bottom Right Button

This is the Ghost Portal button. You can disable it in Ghost Admin. Learn more in Portal Look and feel.

For more information about Members, connecting Stripe, and setting the package price, check the official Ghost documentation.

Search

Siwa uses the Ghost Native Search.

Ghost search uses post titles and excerpts from the 10,000 most recent posts. It does not search the full body of every post.

Comments

The theme comes with Ghost Native Comments integration. You can turn the comments on from your Ghost admin Settings → Membership → Access.

Learn more about Ghost comments.

Ghost developer documentation for comments.

Reader Tools

Siwa includes quiet article tools for long-form reading.

Table of Contents

The table of contents appears automatically on posts and pages with H2 or H3 headings. It stays hidden when there are no headings.

Click the arrow beside Table of Contents to collapse or expand the list.

To turn it off site-wide, go to Settings → Site → Design & branding → Customize → Theme → Post and turn off Show table of contents.

To control it on an individual post or page, open Post settings → Tags or Page settings → Tags:

• Add #table-of-contents-off to hide it, even when the theme setting is on.
• Add #table-of-contents to show it when the theme setting is off.

Publish or update the post or page.

Reading Progress

Post pages show a reading progress bar at the top of the page.

Voice Reader

The Listen button reads the post aloud.

The voice reader works by default. The voice comes from the reader’s device speech settings.

No theme setting is required.

To change the voice:

• On macOS, open System Settings → Accessibility → Read & Speak, then set System speech language and System voice.
• On Windows, open Settings → Accessibility → Narrator, then choose a voice under Narrator’s voice.

On iPhone, turn off Silent Mode if you cannot hear the voice reader.

Text Size

The text-size controls let readers adjust the article reading size while staying on the page. Siwa remembers the choice in the reader’s browser.

Comments Drawer

When Ghost comments are enabled, Siwa opens comments in a side drawer from the post action bar.

Sharing

The Share action opens Ghost’s native share modal.

Image Lightbox

Unlinked post images, gallery images, and supported feature images can open in Siwa’s image viewer. Linked images keep their normal link behavior.

Inline stocks

Show the latest available stock quotes inside posts and pages. Inline symbols display the stock symbol, USD price, percentage change, and a company logo when available.

Get a Finnhub API key

1. Create or log in to your Finnhub account.
2. Open the Finnhub dashboard.
3. Copy your API key.

Finnhub is a separate data service. Check its current plans and API limits, then choose one setup option below.

Direct setup

This is the quickest option. Your Finnhub key will be visible in your site’s code and browser requests.

1. In Ghost, go to Settings → Advanced → Code Injection.
2. Paste this snippet into Site Header.
3. Replace YOUR_FINNHUB_KEY with your Finnhub API key.
4. Select Save.

<script>
  window.finnhubApiKey = 'YOUR_FINNHUB_KEY';
</script>

Cloudflare setup (recommended)

This option keeps your Finnhub key in your Cloudflare account. You need a Cloudflare account and your Finnhub API key.

1. Open the stock ticker setup.
2. Connect your Cloudflare account.
3. Enter your Siwa website address and Finnhub API key.
4. Copy the snippet provided by the setup.
5. In Ghost, paste it into Settings → Advanced → Code Injection → Site Header.
6. Select Save.

If you switch from direct setup, remove the direct-key snippet. Siwa uses the gateway when both snippets are present.

To connect another site, run setup again using the same Cloudflare account. Existing sites remain connected, and all sites use the Finnhub key you enter.

Add stock symbols

Write an uppercase symbol such as $AAPL or $MSFT in a normal paragraph, then preview your post or page. For example:

This week, I am following $AAPL and $MSFT.

Siwa supports US stock symbols with one to five letters. Finnhub availability depends on the symbol and your plan.

If quotes do not appear

Siwa keeps the original symbol readable when a quote cannot load. Check the saved snippet, symbol format, and Finnhub key first.

For Cloudflare setup, check that you entered the same website address readers visit. If you reach a provider limit, wait a minute and refresh.

If the problem continues, contact Aspire Themes with your website address and the symbol you used. Keep your API key private.

Social Links

Siwa uses Ghost social accounts.

Go to Settings → General → Social accounts and add the URLs you want to show.

Social links can appear in:

1. The homepage introduction.
2. The footer.

Languages

Siwa includes the following translations. You can also add your own.

Theme Translation

To change your site language:

1. Go to Settings → General → Publication language.
2. Enter the language code in Publication Language, such as fr for French.
3. Click Save settings.

The following translations are included:

• da Danish
• de German
• en English (default)
• es Spanish
• fi Finnish
• fr French
• he Hebrew
• it Italian
• nl Dutch
• pt Portuguese
• pt-BR Brazilian Portuguese
• tr Turkish

Add a New Language Translation

If the theme does not have a translation for your language, follow these steps to add a new language translation.

1. Create a new file using a code editor in the theme’s locales folder with the ISO Language Codes code. For example, if the new language is Japanese, the ISO code will be ja and the file name will be ja.json.
2. In the same locales folder, open the en.json file and copy its content into your new language file.
3. Start translating, as shown in the following Edit Translation section.

Once you finish, zip the theme files, and upload the final zip file to your Ghost website.

Now, go to your Ghost admin Settings → General → Publication language and enter your language ISO code into the Publication Language field. For example, ja.

Click Save settings.

You may want to restart Ghost or deactivate and activate the theme again to make the new changes effective.

Edit Translation

To edit a translation, open the language file using a code editor in the theme’s locales folder:

locales/
├── da.json
├── de.json
├── en.json
├── es.json
├── fi.json
├── fr.json
├── he.json
├── it.json
├── nl.json
├── pt.json
├── pt-BR.json
└── tr.json

For example, part of the German translation file (de.json) looks like this:

{
  "Loading": "Wird geladen",
  "Load More": "Mehr laden",
  "Comments": "Kommentare",
  "Subscribe": "Abonnieren",
  "Published with {ghostLink} & {themeLink}": "Veröffentlicht mit {ghostLink} & {themeLink}"
}

Each line consists of a left key ("Loading") and a right value ("Wird geladen").

The key is plain English that exists in all translation files and should not be changed. Change only the value.

Keep placeholders such as {ghostLink} and {themeLink} unchanged.

Once you finish, zip the theme files, and upload the final zip file to your Ghost website.

If you have suggestions to improve a current translation or add a new language, please contact me.

Zip Theme Files

You can compress it as a standard folder like any other folder on your computer. If you are on Mac, right-click on the theme folder to view the context menu. Then, click the Compress option.