Feature: Blog Icon

In external sites, we want to be able to display an icon for each blog. This is effectively the same problem as in issue #4869 - we need a static URL at which an external service such as an RSS feed or ghost.org can access to fetch a representative URL.

This icon should be used as the favicon for the blog. It should also be used when any external service looks for an icon. Browsers always look for a /favicon.ico file, at the root of the current domain. This means the behaviour of this file will always be slightly different for blogs which use a subdirectory. When rendering HTML, browsers use

Ideally, we want to serve a .png file. I’m not 100% on what we can or can’t do here, and Googling didn’t turn up much. Most browsers support a /favicon.png , and it’ll be fine to use this for browsers & ghost.org, but to ensure we also capture the RSS issue, it may be worth 301-redirecting favicon.ico -> favicon.png for blogs which have an icon uploaded. This is an unknown, and will require a little bit of experimenting with. Any solution which works in feedburner should be considered acceptable for this task.

Image Requirements

• Only permit PNG images (client + server?)
• Enforce that the image must be square (server side only?)
• Dimensions between 32px and 1000px (server side only?)
• Size not larger than 100kb (server side only?)

Solution

Part A: Getting the icon uploaded:

The icon will be a 3rd image on the general settings screen in Ghost. The main difficulty here is implementing the image validation, to ensure the image meets our requirements. At least for now, this can most easily be done server side, I believe.

• Add a new general setting in Ghost for blog icon
• Add an additional image upload UI to the /settings screen - The icon should only allow uploads, not urls - so the url feature needs to be disabled
• Ensure that when uploaded the image is validated:
  • First check the filesize, and reject anything over 100kb, this means that further processing should at least be quick & easy!
  • Use our image-size utility to check that the size is square and within the right dimensions
  • If any check fails then fully detailed error messages should be returned explaining to the user exactly why an image is not suitable
• The client will need to display any validation errors returned from the server.
• This image will likely be small, we will need to ensure that the image upload modals in general/settings do show the trash icon!

Part B: Using the icon

Any blog that has an uploaded icon should use this instead of any theme favicons.

Note : the existing favicon implementation works as described in the asset helper documentation . It is odd & fiddly and needs overhauling. The existing implementation requires users to output their own meta tag, as Ghost 1.0 will need to output the meta tag itself, this will constitute a breaking change to the theme API.

Ghost will need an internal concept of what its “current favicon” is. This is possibly the 2nd MOST! tricky part of this whole implementation. In the case that a favicon has been uploaded, it’s super easy, but otherwise, it requires some work to detect favicons in the active theme (and this must be refreshed when a theme is activated or overridden).

The ideal order of precedence for the favicon for a blog, is:

• uploaded favicon
• activetheme/assets/favicon.png
• activetheme/assets/favicon.ico
• activetheme/favicon.png
• activetheme/favicon.ico
• Ghost’s favicon.png file (this is a new default, that needs to be added)
• Ghost’s favicon.ico file (not sure if we need this? maybe for older browsers)

Outputting the favicon in themes:

The {{ghost_head}} helper should be updated to output a new meta tag.

In the case that the “current favicon” is a .png file:

<link rel="shortcut icon" href="favicon.png" type="image/png" />

In the case that the “current favicon” is a .ico file:

<link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />

Note : It would be good to experiment here with what will happen for themes that already have this output above {{ghost_head}} i.e. Casper.

**Note: ** I don’t know if the {{amp_head}} should output something different?

As well as outputting the meta tag with {{ghost_head}} , we should also make sure that the icon url (e.g. favicon.png) is available as {{@blog.icon}} .

Outputting the icon on a URI

In order for the icon to work for external sites, we need to render the icon whenever it is accessed via a URI, e.g. /favicon.png

The existing favicon implementation uses a very odd piece of logic to serve any requests for /favicon.ico using our shared file helper , which is totally wrong for this usecase - this code should basically be deleted and forgotten about, and a new piece of middleware for favicons should be written.

The new middleware should live in the exact same place in the stack (e.g. after the two themeHandler middlewares) and the logic should be as follows:

• The middleware should be aware of what the “current favicon” is.
• If the “current favicon” is a .png file, ensure it is served from /favicon.png . Also, 301 redirect any request for /favicon.ico to /favicon.png (this may need testing with RSS readers to ensure it works).
• If the “current favicon” is a .ico file (i.e. No icon was uploaded), ensure it is served from /favicon.ico . In order for this case to work for external sites, we also need to either 301 redirect /favicon.png to /favicon.ico OR just serve the Ghost default icon.

In terms of implementation, this middleware should be small and super fast, it’s going to need to read the contents of the icon file, and then cache those contents.

Update: The existing favicon implementation assumes that it’s ok to read from the file system, totally ignoring our storage adapter layer. The new solution needs a read method added to the storage adapters (see #7687) so that if a file has been uploaded, we are able to access it. If no file has been uploaded, then for now it is ok to read from the file system, as currently we only support local file system storage for themes & the shared files.

We then need to manage ensuring that the cache is cleared at the right times, so that if a user uploads a new logo, or deletes a logo, we correctly display the right one without requiring a restart of Ghost. Handling the caching is the 1st MOST! tricky part of this.

The rules are, to the best of my knowledge, as follows:

• on first load, we need to figure out the “current favicon” and store a reference to it. That reference will need to include:
  • the path to the favicon file = where the file itself can be opened and read
  • a reference to the type, either upload, theme or default (default is when we serve Ghost’s favicon)
• For uploaded icons - the cache needs to be cleared when a new icon is uploaded, or the icon is deleted
• For theme icons - the cache needs to be cleared whenever the assetHash is cleared
• For default icons - the cache never needs to be cleared

Useful links

Some places to use for inspiration for how to write the file reading and caching logic are:

• Ghost’s shared file middleware
• The main express serve favicon middleware (note this only supports favicon.ico)
• Ghost’s logic for refreshing the theme cache
• Ghost’s weird theme settings cache
• Ghost’s theme handling middleware which deals with the assetHash and express’s undocumented view cache

[ErisDS]

@jloh yar very good point - I’m revisiting this in conjunction with #6922, #7958, #6864 and #7491 etc, trying to iron out the assets story across themes vs admin.

[JohnONolan]

Should use default Ghost icon always for admin

Also this issue should def not be closed till UX testing is complete. In fact any new features w/ UX testing needed probably best to assign to me for final pass design review rather than close?