Template and route editing workflow for engineers

Themes
1

I’m new to Ghost and am considering it as a replacement to our current blog/marketing solution (static site generation using middleman).

While I understand there will be tradeoffs, one thing that I’m struggling with is the development workflow. In middleman, if I want to do anything, update HTML, update JavaScript, add a new page, I simply update the code in a single GitHub repo, and let our deployment pipeline eventually deploy it to production by running a series of scripts.

From what I can tell, there’s no workflow like this in ghost. Routes are not part of themes. Themes and Routes need to be separately uploaded to a Web UI to be “deployed”. Is my understanding correct?

2

That’s correct. However, you can always use the API (which is how the Admin Panel makes any changes to your installation) to make changes. There’s supposed to be a new version of the API being released within the next week or so

3

Thanks. Is this the case even while developing locally? There’s no workflow without hitting a (local) admin API endpoint?

4

That’s correct. Routing and theming are 2 separate concepts in Ghost

5

All of the settings that you “upload” to Ghost are just files in the Ghost file system.

E.g. routes.yaml -> /content/settings/routes.yaml

The “upload” replaces the file and triggers an internal reload of whatever components are affected.

The development equivalent would be to edit the files locally and have the files watched for changes and trigger a full restart of Ghost.

For production, the API is a better option as it’ll allow you to do a less destructive action than a full restart. The new version of the API coming this week is read-only. The write API will follow soon after - we’re mainly building a new authentication method so that tooling is easier.

Once it’s ready, we’ll provide examples of how to use the API to upload themes and settings as part of build flows. So for now, I recommend using the manual approach for production knowing it’ll get easier very soon :slight_smile:

6

Thanks for the detail and explanation.

It would be great to have a document on site development with ghost. As far as I can tell, there isn’t anything quite like that right now. There’s theme development, editing configuration and editing routes, but they are either oriented towards isolated development (“creating a custom theme”) or changing production configuration (“uploading routes to production”). Specific concerns that come up include:

  • which repo(s) need to be cloned / forked to get started. Aka how does ghost recommend configuration, templates and routing be versioned for a single site

  • how should docker be set up for local filesystem editing (aka what should be mounted)

  • when restarts are required

Thanks for your help so far!