Ghost reads your site's addresses from a file of its own, routes.yaml, not from the theme. Fantasma writes this file from the addresses in your project. Ghost needs the new file each time you change one of those addresses, or the new ones show an error page.
When Ghost needs a new file
A new project keeps Ghost's usual addresses, such as /tag/news/ for a tag page, and needs no file. You need one after you add or remove a collection, or change a collection's Path or Post permalink, or the address in the settings of the Tag or Author template. Create a part of your site with its own URL covers collections.
Fantasma reminds you:
In the Download or Publish menu, a Download routes.yaml line appears. Point at it, and a label says why.
When you click Download theme, a dialog named "Update routes in Ghost" offers the file first.
In Project settings › Ghost, which you open from the sliders icon in the icon rail, the Routes row says "Routes changed." and offers Download routes.yaml.
Project settings › Ghost names the key your project is connected with under Access. With a Staff access token of the Owner or an Administrator, publishing uploads the new file for you, right after the theme, and you can skip the steps below. If that upload fails, "Theme published, but routes.yaml wasn't uploaded" appears and a dialog offers the file. With an Admin API key, or without a connection, you upload it yourself.
Download the file
Open your project in Fantasma.
At the top of the right sidebar, click Download, or Publish if your project is connected. A menu opens.
Click the arrow on the Download theme button, or on the Publish button at the bottom of the menu. A small menu opens.
Select Download routes.yaml. The file downloads, and a dialog shows where it goes in Ghost.
You can download the file this way at any time, also when no reminder shows. Once you download it, Fantasma stops reminding you until your routes change again. It cannot see whether you uploaded the file, so upload it right away.
Upload it in Ghost
Upload the theme first when it changed too, so the pages at the new addresses have their design.
Important. Uploading replaces the whole routes.yaml in Ghost, and so does the upload when you publish with a Staff access token. If you or a developer added your own routes there, they are gone after the upload. Ghost lets you download its current file from the same place, so you can keep a copy first.
In Ghost Admin, go to Settings → Labs. In Ghost's settings, Labs is among the advanced settings.
Under Routes, upload the routes.yaml you downloaded.
Ghost uses the new addresses as soon as the upload finishes. If Ghost shows an error instead, check that you uploaded the file from Fantasma unchanged, then contact us with Ghost's message. Open a page at a new address, such as your collection, to check it. Links to the old addresses do not follow on their own; Set up redirects shows how to send them to the new ones.
Hide the reminder
If the file in Ghost already matches, for example because you uploaded it from another computer, click Don’t remind me until routes change again in the "Update routes in Ghost" dialog. It opens when you click Download theme, in the Download menu or under the arrow on Publish. The reminder comes back after your next change to the routes.
The theme ZIP holds a copy of routes.yaml too, but Ghost never reads that copy.
Ghost reads your site's addresses from a file of its own,
routes.yaml, not from the theme. Fantasma writes this file from the addresses in your project. Ghost needs the new file each time you change one of those addresses, or the new ones show an error page.When Ghost needs a new file
A new project keeps Ghost's usual addresses, such as
/tag/news/for a tag page, and needs no file. You need one after you add or remove a collection, or change a collection's Path or Post permalink, or the address in the settings of the Tag or Author template. Create a part of your site with its own URL covers collections.Fantasma reminds you:
Project settings › Ghost names the key your project is connected with under Access. With a Staff access token of the Owner or an Administrator, publishing uploads the new file for you, right after the theme, and you can skip the steps below. If that upload fails, "Theme published, but routes.yaml wasn't uploaded" appears and a dialog offers the file. With an Admin API key, or without a connection, you upload it yourself.
Download the file
You can download the file this way at any time, also when no reminder shows. Once you download it, Fantasma stops reminding you until your routes change again. It cannot see whether you uploaded the file, so upload it right away.
Upload it in Ghost
Upload the theme first when it changed too, so the pages at the new addresses have their design.
Important. Uploading replaces the whole
routes.yamlin Ghost, and so does the upload when you publish with a Staff access token. If you or a developer added your own routes there, they are gone after the upload. Ghost lets you download its current file from the same place, so you can keep a copy first.routes.yamlyou downloaded.Ghost uses the new addresses as soon as the upload finishes. If Ghost shows an error instead, check that you uploaded the file from Fantasma unchanged, then contact us with Ghost's message. Open a page at a new address, such as your collection, to check it. Links to the old addresses do not follow on their own; Set up redirects shows how to send them to the new ones.
Hide the reminder
If the file in Ghost already matches, for example because you uploaded it from another computer, click Don’t remind me until routes change again in the "Update routes in Ghost" dialog. It opens when you click Download theme, in the Download menu or under the arrow on Publish. The reminder comes back after your next change to the routes.
The theme ZIP holds a copy of
routes.yamltoo, but Ghost never reads that copy.