Image Library configuration

One Algolia application for both tools

The Image Library keeps its index in the same Algolia application as Advanced Search: one more index, called images, and no second account. Its credentials come from the Search page, where the Application ID, the search-only key and the write key all have to be saved before the Library's Setup tab will do anything. If you haven't set up Advanced Search, the next section lists exactly which of its steps the Library needs.

Every search and filter in the Library is an Algolia request against your own allowance. Algolia's Grow plan includes 10,000 requests a month, which covers modest use, and currently bills overage at $1 per 1,000 beyond that; your Algolia dashboard shows the running count.

Image Library without the SWS Toolbox Advanced Search

You can run the Library on a site that keeps Ghost's own search or uses a different search provider. Advanced Search only touches your site when you paste its snippet into Code injection, and the Library never needs that, so nothing changes for your readers.

1. On the Search page, enter the Application ID, the Write API Key and the Search API Key from your Algolia account (Settings, then API Keys; the Grow plan, not Build) and Save. Leave Search enabled unticked and ignore the rest of that page.
2. In the Image Library's Setup tab, do every step below. Set up image index registers the Ghost webhooks itself, so nothing on the Search page needs pressing.

New to Algolia? The Advanced Search walkthrough shows the account and key setup start to finish; stop once the keys are saved.

The Setup tab

1. Image Library enabled, then Save. From now on the Ghost webhooks also update the image index whenever a post or page is published, edited, unpublished or deleted.
2. Set up image index. Creates the images index with its settings, registers the Ghost webhooks if they aren't there yet, and ticks Image Library enabled for you. Safe to press again; it never removes anything, and re-applies the current index settings.
3. Reindex posts, then Reindex pages. Each walks every published item of that kind (email-only posts included) and records the images it finds. Run both. Safe to repeat. A reindex refreshes where each image is used and what's missing alt text; it never touches the photographer, folder, notes or alt text you've entered.

There's no Clear button, on purpose. The notes you type live only in this index, so emptying it would destroy them with no way back.

What the index records

One entry per unique image. Ghost's resized copies (/size/w600/ and friends) collapse into the original, so a photo run at three widths is one entry. Each entry carries:

• the filename, and every caption and alt text the image has been given anywhere;
• every published post and page it appears in, with a link to each. The feature image, image cards, galleries, HTML and Markdown cards, and the image inside product, call-to-action, header and signup cards all count;
• whether each of those uses can carry alt text, which is what the Missing alt badge is based on;
• the fields you add yourself: photographer, folder, notes, and an alt text for the image. These exist only in the library until you send the alt text to Ghost.

Drafts are never scanned, and neither is anything tagged #no-index. Entries are never deleted: an image that stops being used stays, marked Unused, so it's still there to find and reuse. Nothing here moves or copies your image files; they stay on your Ghost site.

The Library tab

The search box matches captions, alt text and filenames, and the folder dropdown narrows to one folder. Three modes at the top decide what each card shows and what you can do with it.

Find & use

• Copy for Ghost puts a complete Ghost image card (full-size image, caption, alt text) on your clipboard; paste it into the editor and it lands as a native card. The chevron beside it copies the image as a product, call-to-action, header or signup card instead, with the text fields left empty for you to fill.
• Start a post opens a new draft in Ghost with the image as its feature image, alt text and caption carried over, and lands you in the editor.
• Two small icons over the preview copy the caption or the alt text as plain text. Where an image has several captions, the dropdown picks the one to paste.

Alt text

• Missing alt text filters to images that lack it somewhere. Write the alt text on the card and Save and write alt text to Ghost puts it into every post and page where that image has none, feature images included. Alt text a post already has is never overwritten.
• Fill from existing alt does the same across every loaded card at once, copying the alt text a post already has into the other posts that use the same image.
• Product, call-to-action, header and signup cards have nowhere to put alt text in Ghost, so for an image used only in those the button saves to the library record and says so.

Organize

• Photographer, Folder and Notes, kept with Save metadata. Folders are free text; the dropdown lists whatever you've typed.
• Upload image sends a file to Ghost and adds it to the library straight away, with a dialog for its details.
• Four lenses: Unused only (nothing uses it), Replaced only (swapped out everywhere and kept for reference), Likely duplicates (the same filename uploaded more than once, ready to merge) and Show hidden (only the never-show images, so one can be brought back).
• Tick two or more cards and Merge… to treat copies as one image, choosing which copy is the main one. A merged card lists everywhere every copy ran, and its edits reach all of them; Ungroup splits it again.
• Never show drops an image and its merged copies from every view; Show again, under Show hidden, restores it. Your posts aren't touched.
• Replace image… is described below.

Open details on any card shows the full card: every section of all three modes at once, and the complete list of where the image has run.

Badges on a card

The two things that change your Ghost content

Everything above lives in the library. Exactly two actions edit posts and pages in Ghost, and both say so before they run:

• Writing alt text to Ghost, from a card or the Fill from existing alt sweep, fills alt text only where a use has none.
• Replace image… swaps the image for another in every post, page and feature image it appears in, product and signup cards included. Give it a new alt text or caption and those are updated in the same pass; leave them blank and each post keeps its own. The old entry stays in the library marked Replaced.

Merging, hiding, notes, folders and photographer credits never reach Ghost, and no image file is ever deleted.

Contributor access

If you give a contributor an Image Library grant (Site settings → Users), use covers searching, copying, starting a post and editing a card's details; manage adds the Setup tab and everything that changes Ghost or the library's structure: alt text to Ghost, Replace, merging, uploads and Never show.