Astra

v1.0.0

Setup and customization guide for the Astra Ghost theme.

Live demo Get the theme

Welcome to the Astra documentation. This guide covers everything you need to install, configure, and customize Astra — a Ghost theme built for publishers who value clarity, elegance, and a calm reading experience.

Astra assumes a basic understanding of the Ghost platform. If you’re new to Ghost, we recommend the official Ghost Help Center before continuing.

Installation

You can install Astra directly from the Ghost admin panel.

  1. Download the Astra theme .zip file from your Pixel Themes purchase email.
  2. In your Ghost admin, go to Settings → Design & branding.
  3. Click the Change theme button.
  4. Click Upload theme and select the Astra .zip file you downloaded.
  5. Once uploaded, click Activate to enable Astra on your site.

You do not need to unzip the file — Ghost handles that automatically. The theme is now live.

Routes

Astra works with the default Ghost routing. No custom routes.yaml file is required. All standard Ghost routes are supported out of the box:

  • Home — /
  • Post — /{slug}/
  • Tag — /tag/{slug}/
  • Author — /author/{slug}/
  • Page — /{slug}/

If you customize routes, you can upload your own routes.yaml under Settings → Labs → Routes.

Astra uses Ghost’s built-in navigation, with two menus: Primary and Secondary.

Primary navigation

The primary menu appears in the header at the top of your site. Configure it in Settings → Navigation → Primary.

Add links in the order you want them shown. Each link accepts:

  • Label — the visible link text (e.g., Essays, About, Features)
  • URL — a full URL or a path like /about/

Secondary navigation

Astra treats the secondary menu differently — it powers your footer columns. Add items with a [Column Name] prefix and Astra automatically groups them into columns under that heading.

For example, adding these entries in Secondary navigation:

  • [Journal] About → /about/
  • [Journal] Contact → /contact/
  • [Legal] Terms → /terms/
  • [Legal] Privacy → /privacy/

produces a footer with two columns: Journal (with About and Contact links) and Legal (with Terms and Privacy links). You can add as many columns as you like — each new prefix creates a new column.

Items without a [Prefix] are rendered as standalone links in the footer.

Basic settings

Announcement bar

You can display a site-wide announcement at the very top of every page — useful for launches, sales, or important notices. Configure it under Settings → Announcement bar:

  • Enter your announcement text
  • Choose which pages to display it on (Home, Post pages, etc.)
  • Choose which visitors see it (visitors, free members, paid members)

Astra integrates Ghost’s native search. The magnifying-glass icon in the header opens the search overlay, and readers can search across all posts, pages, tags, and authors.

Search is enabled by default and requires no configuration.

Dark mode toggle

The moon/sun icon in the header lets readers manually override their system color preference. Astra remembers the choice for future visits.

Astra supports a wide range of social platforms. Add your profile URLs under Settings → Design & branding → Social accounts:

  • Facebook
  • Twitter / X
  • Instagram
  • Pinterest
  • Threads
  • TikTok
  • Bluesky
  • Mastodon
  • VK
  • YouTube

Any social field left empty is automatically hidden from your site. The icons appear in the header, footer, and — depending on the theme setting — in the post metadata section.

Customization

Open Settings → Design & branding to access all customization options. Astra’s options are grouped under two tabs: Brand and Theme.

Accent color

Set your accent color under Brand → Accent color. This color is used for links, buttons, hover states, and other interactive elements throughout your site.

Astra supports two separate accent colors — one for light mode and one for dark mode — so your brand stays legible in both.

Astra displays your publication title in a script wordmark by default. If you upload a publication logo, it replaces the script title in the header and footer.

Upload your logo under Brand → Publication logo. Astra also supports a dark mode logo — upload a second version to be shown when a reader switches to dark mode.

For best results:

  • Provide an SVG or a transparent PNG.
  • Recommended height: 40–60 px at 2× resolution.

Icon

Your publication icon (the favicon) is configured under Brand → Publication icon. Ghost automatically generates the various favicon sizes needed by modern browsers.

Recommended: 512×512 px PNG.

Typography

Astra ships with a curated typography stack designed for readability. No fonts need to be uploaded — the theme handles font loading efficiently.

If you want to change fonts, see the Edit theme section for information on customizing the theme source.

Site wide

The following options apply across your entire site.

Dark mode

Dark mode is enabled by default and adapts to your reader’s system preferences. To customize it:

  • Accent color for dark mode — Set a lighter or more saturated version of your accent color so it remains legible on a dark background.
  • Logo for dark mode — Upload a light-colored version of your logo so it’s visible against the dark background.

Subscribe modal

Astra can display a subscription modal to encourage new visitors to sign up for your newsletter.

  • Enable subscribe modal — toggle the modal on or off.
  • Subscribe modal image — upload a decorative image shown alongside the subscription form.
  • Subscribe dismiss days — number of days before the modal reappears to a visitor who dismissed it. Recommended: 3–7 days.

Publication description (Bio)

The publication description is the intro paragraph shown at the top of your homepage next to the author avatar. This is your first impression — describe what your publication is about, how often you publish, and what readers can expect.

Configure it under Settings → General → Publication description.

The same text is also used for meta descriptions and structured data across your site, so keep it to 2–3 clean sentences.

Set the copyright line shown at the bottom of every page. You can use plain text or basic HTML — for example:

Published with <a href="https://ghost.org/" target="_blank">Ghost</a>

The default is your publication title and the current year, but a custom line is recommended for branding.

Homepage

Astra’s homepage has three distinct areas: a header intro, an optional featured post, and a recent posts list.

Header intro

The top of the homepage displays your publication identity alongside a description and the inline subscribe form:

  • Author avatar — pulled from the profile photo of your publication’s primary author. Set it under Ghost admin → Staff → your profile → Profile picture.
  • Publication title — displayed in Astra’s script wordmark by default. If you upload a publication logo, it replaces the script title.
  • Publication description — the short bio next to the title. See Publication description.
  • Social icons — pulled from your configured social accounts.

Inline subscribe form

An inline newsletter form appears in the header area, with your publication’s newsletter signup and a link to your Terms of Service.

Featured post

If you mark any post as Featured in the Ghost editor (via the star icon on the post), Astra displays it prominently at the top of the homepage with a Featured Post pill, larger typography, and its feature image on the right.

Only the most recent featured post is displayed in this hero slot; any additional featured posts are still marked in the list below.

Recent posts list

Below the featured post, Astra shows recent posts in a three-column list layout: post metadata on the left (tag, date, read time), title and excerpt in the center, and the feature image on the right.

Locked (members-only or paid) posts display a lock icon overlay on the feature image with a blurred preview, encouraging readers to sign up.

Post

Template

By default, Astra uses a clean, readable single-column post template. Individual posts can override this by adding a custom template — see the Ghost documentation on custom templates if you want per-post variations.

Metadata

Toggle the post’s metadata (author, date, and estimated read time) under Theme → Post → Metadata. Read time is calculated automatically from the post’s word count and cannot be manually overridden.

Share

Astra can display share buttons at the end of each post — X/Twitter, Facebook, LinkedIn, and Copy Link.

Show related posts at the bottom of each article to keep readers engaged. Astra picks related posts by matching tags.

Astra’s footer combines several configurable pieces.

Brand block

The left column shows your publication logo, description, and social icons. All three are pulled from the same sources as the homepage — no separate configuration is needed.

Explore column (post tags)

Astra automatically generates an Explore column listing your primary tags. This helps readers navigate your publication by topic.

  • Tags are pulled from your published posts.
  • To exclude a tag from the footer, add a # prefix to the tag slug in Ghost (internal tags are automatically hidden).
  • The column heading “Explore” can be renamed via translation files — see Translate.

Custom columns (secondary navigation)

Add custom footer columns using the Secondary navigation menu with [Column Name] prefixes. See the Navigation section for details.

The bottom bar shows your copyright line on the left and a Sign up link on the right that opens the Portal signup flow. Both are always visible.

Membership

Astra integrates fully with Ghost’s built-in membership system.

Portal

Portal is Ghost’s native sign-in and subscription flow. Astra is fully compatible — configure sign-up options under Settings → Membership → Portal settings.

Astra uses your Portal button label and accent color throughout the theme for a consistent look.

Comments

Ghost’s native comments are supported on all post pages. Enable comments under Settings → Membership → Comments and choose whether comments are open to all members or only paid members.

Advanced

Edit theme

You can modify the theme source directly.

  1. Download the current Astra .zip from your account or from Settings → Design & branding → Change theme → Downloaded themes.
  2. Unzip and edit the source files. The assets/ folder contains CSS and JavaScript; templates use the Handlebars format (.hbs).
  3. Re-zip the folder and upload it back to Ghost as a new theme.

Only advanced users should modify the theme source. Custom edits are not covered by our support.

Translate

Astra is translation-ready. To translate the theme:

  1. Set your publication’s language under Settings → General → Language.
  2. Astra loads a matching locale file if one is available in locales/.
  3. To add a new language, create a .json file inside locales/ (e.g., es.json) with translations for each key found in locales/en.json.

Update theme

When a new version of Astra is released, you’ll receive an email with a download link. To update:

  1. Download the new .zip file.
  2. Upload it via Settings → Design & branding → Change theme → Upload theme. Ghost will replace the older version.
  3. Your customizations (logos, colors, navigation) are preserved.

Feedback

Have a suggestion or want to report a bug? Contact us — we read every message.

Changelog

1.0.0 — 2026-01-15

  • Initial release