Faro

1. Overview

Faro turns Ghost into a help center, knowledge base or product documentation site. Your docs live in the same Ghost install as your site: same login, same members, same domain.

Ghost has no nested pages or tag hierarchy. Faro adds both — sections and subsections — and lets you set the exact order of the navigation tree without tricks with dates or slugs.

2. Requirements

• Ghost 6.0 or later (Ghost(Pro) or self-hosted).
• No plugins, integrations or code edits are required.

3. Installation

1. In Ghost Admin go to Settings → Design & branding → Customize → Change theme.
2. Click Upload theme and select faro.zip. Do not unzip it.
3. Click Activate.

4. Demo content (optional)

To start from the same structure as the live demo (English · Spanish), import faro-demo-en.json or faro-demo-es.json (download links on your thank-you page) in Settings → Advanced → Import/Export → Import. It adds sections, subsections, sample articles (including member-only ones) and a changelog. Do this on a fresh site: imported content is added to what you already have.

5. How Faro organizes your docs

Sections = primary tags

Each section of your help center (e.g. Getting started, Billing) is a public tag. An article belongs to the section of its primary tag — the first tag in the post settings. A tag only becomes a section when it is the primary tag of at least one article, so extra labels (like the changelog types) never show up as sections.

The tag's description appears on the homepage card and the section page; its image becomes the section icon (see Section icons).

Subsections = internal tags

To group articles inside a section, add an internal tag whose name starts with #sub-, for example #sub-Installation. Faro groups those articles under a Installation heading in the tree and shows it in the breadcrumbs. Internal tags are invisible to readers. Articles without a #sub- tag stay directly under the section.

6. Navigation order

Choose the mode in Theme settings → Navigation mode.

Automatic (default)

Works as soon as you install. Sections and articles are sorted by title. To force an order, start titles with a number — 01. Installation, 02. Configuration. Faro hides the prefix everywhere it is displayed.

Menu (recommended for full control)

The tree is built from Ghost's secondary navigation (Settings → Navigation → Secondary). Each item is a link to a section (/tag/getting-started/) or an article (/create-your-account/). Start a label with a dash and a space to indent it one level:

Getting started        → /tag/getting-started/
- Create your account  → /create-your-account/
- Invite your team     → /invite-your-team/
Billing                → /tag/billing/
- Download invoices    → /download-invoices/

The order is exactly the order of the menu: drag and drop items in Ghost Admin to change it. In this mode the secondary navigation is used only for the tree, not in the footer.

In both modes, the highlighted article and Previous / Next follow the order of the tree and cross from one section to the next.

7. Homepage

• Hero in your brand color (Settings → Design & branding → Brand → Accent color), with the title from Hero title and your site description.
• Search uses Ghost's native search. Readers can also press / anywhere.
• Popular: mark articles as Featured to show them as chips under the search box, in the Popular articles block and as examples typed in the search box.
• Browse by topic: one card per section, with icon, description and article count.
• Latest updates: the four most recent changelog entries (hidden if there are none).
• Still need help?: shown when Contact URL is set.

8. Articles

• Navigation tree on the left (a drawer on phones), table of contents on the right built from H2/H3 headings, breadcrumbs, author, last update date and reading time.
• Every heading gets a link button to copy a direct link to that section.
• Code blocks get a Copy button.
• Ghost cards are styled for docs: callout (use the colors for note, tip, warning and danger), toggle (great for FAQs), bookmark, button and tables.
• Was this article helpful? at the end (can be turned off).
• Comments: if you turn on Ghost's native comments (Settings → Membership → Comments), they appear at the end of every article, in light or dark mode.

Static pages (terms, privacy…) use the same reading layout with a table of contents.

9. Section icons

Faro includes 30 icons in assets/icons/ of the theme zip (and in the package): bell, book, calendar, card, cart, chart, chat, cloud, code, compass, database, download, file, globe, heart, help, lightbulb, lock, mail, megaphone, mobile, plug, rocket, settings, shield, sparkles, user, users, video, wrench.

1. Unzip a copy of faro.zip on your computer and open assets/icons/.
2. In Ghost Admin open the tag and upload, for example, faro-icon-rocket.svg as the tag image.

Faro recognizes files named faro-icon-… and paints them with your accent color, in light and dark mode. Any other image (your own icon, a PNG) is shown as it is.

10. Changelog

Publish your product updates as posts with the tag changelog (or the slug set in Changelog tag). Its tag page becomes a chronological list, and the tag never appears as a section.

Add a second public tag such as New, Improvement or Fix to show it as a label on each entry.

11. Members & paid docs

Set an article's Post access to Members only or Paid-members only. Visitors see the public preview, if you add one (the Public preview divider in the editor), followed by a clear notice: create a free account, or see plans. Signed-in members read the full article. Sign-in, sign-up and account use Ghost's native Portal.

12. Analytics

If Google Analytics 4 is installed on your site (for example through Settings → Advanced → Code injection), every answer to Was this article helpful? sends an article_feedback event with the parameters helpful (yes / no) and page_path. Use it to find the articles that are not helping. Without GA4 the buttons still work; nothing is sent.

13. Theme settings

In Settings → Design & branding → Customize → Theme settings:

Colors come from your accent color; fonts from Brand → Typography. Light and dark mode follow the reader's system, and the sun/moon button switches and remembers the choice.

14. Translations

Faro ships in English and Spanish. Set the language in Settings → General → Publication language (en, es). To add another language, copy locales/en.json, translate the values, save it with the language code (e.g. pt.json), zip the theme again and upload it.

15. Customizing

For small changes, use Settings → Advanced → Code injection to add CSS without touching the theme, so updates don't overwrite your work. For deeper changes, edit the sources (assets/css/faro.css, assets/js/faro.js) and rebuild:

npm install
npm run zip   # creates dist/faro.zip

16. Updating

Download the latest version with the link in your purchase email and upload faro.zip again. Ghost replaces the theme and keeps your settings and content. If you edited the theme files, back them up first.

17. Support

Your purchase includes 6 months of support through the contact form. Online documentation: planethemes.com/faro/docs.