Navigation
Break builds all of its navigation from the two menus Ghost already gives you. The first characters of a label decide what an item becomes: a plain link, a row in a dropdown, a caption, a rule, a mega menu block or a language link.
Nothing here needs a theme setting. You type labels and URLs in Ghost, and the theme reads them.
Managing Navigation Items#
- Go to ⛭ Settings → Navigation
- Click Customize
- Add, remove or reorder items on the Primary and Secondary tabs
- Click Save
Where Each Menu Appears#
| Place | Primary navigation | Secondary navigation |
|---|---|---|
| Top bar (desktop) | Every item, with dropdowns and mega menus | Not shown |
Menu panel (the menu button, or the m key) | Every item as a large row. Dropdowns open in place | Every item except = items, as smaller rows |
| Footer, Menu column | The top-level items only, as plain links | Not shown |
| Rail and footer, Languages column | Not shown | The = items only |
On phones and narrow windows the top bar hides the navigation, and readers open the menu panel instead. See Top Bar.
Label Prefixes#
The prefix is an instruction. The theme removes it before readers see the label.
| Label starts with | What it becomes |
|---|---|
| nothing | A top-level item |
- (dash and a space) | A row in the dropdown of the top-level item above it |
# (hash and a space) | A caption in that dropdown |
--- (three dashes alone) | A rule in that dropdown |
@ (at sign and a space) | A mega menu block in that dropdown. Its URL picks the block |
= (equals sign and a space) | A language link. Use it in the secondary navigation |
The space matters. -About is a top-level item with an odd name. - About is a dropdown row.
Dropdowns#
A top-level item opens a dropdown as soon as the item below it has a prefix. Every prefixed item after it joins the dropdown, until the next item without a prefix starts a new top-level item.
Newsroom → /authors/
- Writers → /authors/
- About → /about/
- Contact → /contact/
In the top bar the dropdown opens when the pointer rests on the item, and the item itself stays a link. The rows are numbered 01, 02, 03 down the panel.
In the menu panel an item with a dropdown works differently. A tap opens and closes its list, and the item does not follow its own link. Repeat the link as the first row of the dropdown, as Writers does above, so readers on a phone can reach it.
Captions#
A # row puts a caption in the dropdown, above the rows that follow it.
- With the URL
#the caption is plain text. - With a real URL the caption itself becomes a link, with a small triangle after it.
Latest → /blog/
# Desks → #
- Shipping → /tag/shipping/
- Energy → /tag/energy/
---
# Formats → #
- Live → /live/
- Long reads → /tag/longreads/
Rules#
A label of exactly --- draws a line across the dropdown. Use it to split a long list into groups.
Mega Menu Blocks#
An @ row does not draw a link. It fills the dropdown with content, and its URL decides which content.
URL of the @ row | What fills the block |
|---|---|
/tag/<slug>/ | The four newest posts with that tag, as small cards |
/tags/ | Your 12 most-used public tags. The first four as picture cards with their post count, the rest as a list |
/authors/ | The four authors with the most posts, with portrait, name and post count |
/projects/ | The four newest posts tagged #project. See Projects |
/recommendations/ | Up to four sites from ⛭ Settings → Growth → Recommendations |
/subscribe/ or /membership/ | A subscribe card with a sign-up form, your newsletters and your plans (see below) |
| anything else | A plain row, linking to the URL |
The row's label, without the @ , becomes the block's caption. A View All link beside the caption leads to the same URL. The subscribe block is the exception and shows no caption.
As soon as a dropdown holds a block, it opens as a wide panel across the window under the top bar. The rows stay in a column on the left and the block fills the space beside them.
- Two or three blocks in one dropdown stand side by side, one column each.
- A block on its own, with no rows, takes the whole panel.
/tags/ leaves out tags whose slug starts with issue-, so editions do not crowd out your sections. See Issues.
The Subscribe Block#
The block for /subscribe/ or /membership/ shows:
- the feature image of your newest post tagged
#newsletter, or your site's cover image when there is none - a headline with your site title, your site description and the sign-up form
- your number of readers, under the form
- beside the card, your newsletters with their descriptions and up to three public plans with their monthly price
Members already signed in, and every visitor when members are turned off, see a plain link row instead.
Mega menu blocks read the URL as a path on your site. On a Ghost installed in a
subfolder, such as example.com/news/, the paths do not match and every @ row
falls back to a plain link.
In the menu panel there is no room for blocks, so every @ row shows as a plain link with its label.
The More Item#
When the top-level items do not fit the top bar, the ones at the end move into a more item, a button with three dots. Its dropdown lists them as plain links. A wider window brings them back into the bar.
Keep the labels short and the most important sections first. They are the ones that stay in the bar.
Worked Example#
This is a primary navigation for a news site, entered in ⛭ Settings → Navigation one item per line, label on the left and URL on the right:
Latest → /blog/
# Desks → #
- Shipping → /tag/shipping/
- Energy → /tag/energy/
- Money → /tag/money/
---
# Formats → #
- Live → /live/
- Long reads → /tag/longreads/
- Issues → /issues/
@ Latest in shipping → /tag/shipping/
Markets → /markets/
- Bitcoin → /tag/market-btc/
- EUR/USD → /tag/market-eur-usd/
@ Topics → /tags/
Newsroom → /authors/
- Writers → /authors/
- About → /about/
@ Writers → /authors/
Members → /membership/
- Plans → /membership/
- Sign in → /signin/
---
@ We recommend → /recommendations/
@ Join → /subscribe/
What readers get:
- Latest opens a wide panel. Two captioned groups of links sit on the left, split by a rule, and the four newest shipping stories fill the space beside them.
- Markets lists two markets and, beside them, your most-used tags.
- Newsroom links to the writers and the about page, with the four most active authors beside the links.
- Members has two links and two blocks side by side: recommended sites and the subscribe card.
- The footer's Menu column lists Latest, Markets, Newsroom and Members.
Language Switcher#
Items in the secondary navigation whose label starts with = become a language switcher. Each one links to your site in that language.
= EN → https://example.com/
= DE → https://de.example.com/
= FR → https://fr.example.com/
The switcher appears at the foot of the rail and in the Languages column of the footer. The item that points at the site being read is marked as the current language. The = items never appear in the menus themselves.
The switcher only links between addresses you enter. Add the same = items to every language version of the site so readers can switch back.
Support Us Link#
The Donate url setting adds a Support us row to the menu panel, under the secondary navigation. It opens in a new tab.
- Go to ⛭ Settings → Design
- Click Customize
- Open the Theme tab
- Paste a link into Donate url, for example your Ko-fi or PayPal page
- Click Save
Leave the field empty to hide the row. To use Ghost's own tips instead, turn on tips and donations in ⛭ Settings → Growth and paste #/portal/support.
Notes#
- A prefixed item needs a top-level item above it. A menu that starts with
-,#,@or---skips that first item. - Only one level of nesting exists.
-- Labelis not a deeper level. It is a top-level item whose name starts with a dash. - The footer leaves out every prefixed item, so it stays a short list of your main sections.
- Every mega block loads its content when a page is built, on every page, even if no one opens the menu. Keep them to the menus that need them.