Apple News configuration

Before you start: the invitation, and three values from Apple

Apple News channels are invitation-only. Getting approved is the slowest part of the whole exercise, and this tool can't hurry it: it moves your posts from Ghost to a channel you already have. If you sign in at icloud.com and don't see News Publisher, your account hasn't been invited yet.

Once you're in, the tool needs three values from News Publisher: a channel ID, an API key ID and an API key secret. In News Publisher, open Settings, then Connect CMS, then the API Key section; Apple's own instructions walk through it. If the secret isn't shown, Replace API Key issues a new one, which breaks any other integration using the old key until you update it. Keep that tab open for the next step.

On the Ghost side, the site needs an Admin API key from a custom integration (Ghost → Settings → Integrations → Add custom integration), saved in Site settings on the dashboard. The tool uses it to register a webhook and to read each post.

The Install tab

1. Credentials. Paste the Channel ID, the API Key ID and the API Key Secret, and press Save changes. The secret is stored encrypted and never shown again; the field says "A secret is configured" once one is saved, and typing a new value replaces it.
2. Validate credentials. Makes a test call to Apple with the saved values, so a typo shows up here rather than on your first post.
3. Set up integration. Creates a post.published webhook on your Ghost site and fills the Design tab's accent colour and logo from your Ghost settings as defaults. It reports the webhook's status and target URL. If the automatic install fails, add the webhook yourself in Ghost (Settings → Integrations → your custom integration → Add webhook), with the event Post published, the target URL shown, and the secret from the reveal control below the button.

The webhook fires when a post is published. Editing a post after that doesn't send the edit to Apple News; use Resync on the Activity tab for that.

The Syndication tab

• Enable Apple News syndication. The master switch. Off, the webhook is ignored and nothing is sent.
• Which posts syndicate. All published posts; Only posts tagged with the opt-in tag (#apple-news unless you change it); or All posts except those tagged with the opt-out tag (#no-apple-news unless you change it). Both tags are internal, so readers never see them.
• Publish mode. Preview sends each article to your channel's review queue, visible only to its preview audience, so you can check how posts look before anyone else does; it's the recommended setting while you're getting started. Live publishes to the public immediately.
• Members-only content and Paid / tier content each get one of three treatments, so a free-signup post and a paid post can be handled differently:
  • Don't syndicate these posts.
  • Public preview only: the article stops at the post's preview line, and a post with no preview line isn't published at all. The article ends with the "Continue reading" text and a button linking back to the full story on your site; both are editable here, and default to "Read the full story on our website." and "Read the full story".
  • Full content: the whole post goes to Apple News, preview line ignored.

The Design tab

• Branding. Your publication logo and channel icon are channel-level settings in Apple News Publisher, not here; Apple stamps them on every article. What this tab has is the accent colour, used for buttons and links inside the article, and the logo URL shown in the "continue reading" footer of preview articles. Both are filled in from your Ghost site by Set up integration and can be changed.
• Fonts. Apple News renders a fixed set of system fonts, so the body and heading pickers list those. Code blocks always use Courier.
• Article header. Standard puts the feature image on top with the title and byline (By Author · Date) below it. Overlay puts the title and byline over the feature image on a dark scrim, falling back to Standard for a post with no feature image. Show the post excerpt as a subheading adds it under the title.
• Wider content on tablets. Fills more of the screen on iPad and desktop and slightly enlarges body text and headings. Phones are unchanged either way.

Extra content: three Ghost pages

Standing content that goes into every article comes from Ghost pages you write, chosen by page from a list; the setting keeps the page's slug, so renaming or deleting the page shows as "(missing: slug)" here until you pick another. Only the page's body is used, never its title or feature image, and a draft page works, so the content never has to appear on your website. Edits to the page in Ghost reach the next article you syndicate, or an existing one when you Resync it.

• Before the article. Appears under the headline and byline, above the first paragraph. A series note, for instance.
• After the article. Appears at the end of the story: a support pitch, a pointer to your newsletter. It's skipped on paywalled previews, which already end with the "continue reading" button.
• Instead of signup cards. Apple News can't collect email addresses, so Ghost signup cards are left out of articles. Pick a page to stand in for each one; a "subscribe on our site" pitch with a link button works well. Leave it at None and signup cards are simply dropped.

The Activity tab

Processing takes a minute or two after you publish, and then Apple may take several additional minutes to publish the article to your channel. Be patient: a post that hasn't shown up yet is usually still on its way. Once processed it appears in the Activity list. Each row shows the title, when it was sent, whether it's a Preview or Live, a link to edit the post in Ghost, and an open link to the article itself, which only works on an iPhone, iPad or Mac. You can use those links, or the channel link from News Publisher, before the channel is approved for the public; once a few articles look right, that's the moment to ask Apple to make the channel public, by whatever route came with your invitation.

Three actions per article:

• Make live promotes a preview article to the public.
• Resync rebuilds the article from the post as it is now in Ghost and the current Design settings. It's how an edited post, a changed font, or a new "before the article" page reaches an article that's already there.
• Delete removes the article from Apple News and from this list, so the post can be sent again later.

Publish a post manually pushes any published post to Apple News now, bypassing the tag filter; it's how you send the back catalogue, since publishing a post in Ghost is the only automatic trigger. A post that's already been synced is skipped, and so is one your Syndication settings rule out. The reasons it gives:

What travels, and what doesn't

Each Ghost card is rebuilt as a real Apple News component rather than a web page in a frame: paragraphs, headings, lists, images, galleries, callouts, headers, calls to action, quotes, asides, buttons, product cards, bookmarks, audio, video, YouTube and Vimeo embeds, dividers, code blocks and file cards. A YouTube or Vimeo embed plays in Apple's own video player; any other embed card becomes a short note linking readers to the article in their browser. A toggle card arrives open and stays open, since Apple News has no toggling. Signup cards are replaced by the page you picked above, or dropped.

Two card types don't make the trip: Markdown cards, and with them any table they contain, and HTML cards, with ten exceptions the tool recognises by their markup, nine of them from Email-Friendly Embeds:

• Small image and caption becomes a photo with its caption beside it.
• Writer headshot becomes the photo beside the name, role, bio and link, with the border if the card has one. It travels only when you ticked the web or the social web for it; an email-only card stays out of Apple News, like every email-only card.
• Image with text wrap becomes a real wrap: on iPad and Mac the paragraphs between the start and end cards flow around the photo, on iPhone the photo sits above them at full width, as it does in the email.
• Instagram becomes Apple News's own Instagram card, showing the post itself. The email card that goes with it is left out, as it is on your site.
• Datawrapper becomes a picture of the chart as published, at the width you chose for the card, with "Open the interactive chart" under it linking to Datawrapper. Republishing the chart doesn't update the picture; Resync the article for that. The email card is left out.
• Flourish becomes a picture of the visualization or story, at the width you chose for the card, with "Open the interactive visualization" under it linking to Flourish. This works for embed code pasted straight from Flourish too. Republishing the piece doesn't update the picture; Resync the article for that. The email card is left out.
• Bluesky becomes a card in Bluesky's own style: the author, the post, its photos, link card, video poster or quoted post, the counts and the date, with "View on Bluesky" under it. The post is fetched from Bluesky when the article is sent, so it works for embed code pasted straight from Bluesky too; a post that has since been deleted or made private leaves just the link. The email card is left out.
• LinkedIn becomes a card in LinkedIn's style: the author, the post, its photos, link card, video poster or document, the counts and the date, with "View on LinkedIn" under it. The post is fetched when the article is sent, so LinkedIn's own embed code pasted by hand works too, and a cut you set for email applies here as well.
• Spotify becomes the bar: the cover, title and subtitle in the item's own colours, with "Listen on Spotify" under them. Apple News can't play the player, so the email card is the one that travels here, and the player is left out. Spotify's own embed code, pasted without the bar, becomes a "Listen on Spotify" line.
• Bandcamp becomes a card in the player's look: the cover, the title and artist in the colours you chose, with "Listen on Bandcamp" under them. The player is left out, as Apple News can't play it; Bandcamp's own embed code pasted without the card becomes a "Listen on Bandcamp" line.
• SoundCloud becomes a card in the player's look: the artwork, the artist and title, and the length and play count, with "Listen on SoundCloud" under them. The player is left out, as Apple News can't play it; SoundCloud's own embed code pasted without the card becomes a "Listen on SoundCloud" line.
• PDF becomes the first page as a picture, with "Download the PDF", its size and page count under it, linking to the file on your site. There is no page-through viewer in Apple News.
• A drop-cap paragraph.

Any other HTML card is left out of the Apple News version, so a post that depends on one is worth checking in preview before you make it live. One more thing to know about the Datawrapper, Flourish, Bluesky, LinkedIn, Spotify, Bandcamp and SoundCloud pictures: Apple refuses a whole article if it can't fetch one of its images, so before sending, the tool checks each of those pictures and leaves out any it can't reach, keeping the link under it. A chart unpublished since the post went out still syndicates, minus its picture.

Drop caps

Apple News has drop caps of its own, and the tool turns one kind of HTML card into one. In the Ghost editor, add an HTML card and give the paragraph the class drop-cap-paragraph:

<p class="drop-cap-paragraph">It was a bright cold day in April, and the clocks were striking thirteen.</p>

In the Apple News article that paragraph is body text with its first letter dropped about three lines deep, in your heading font. Apple decides the exact depth for each device, so it can come out a line shorter on a phone. Links, bold and italic inside the paragraph come through; any other paragraphs in the same card arrive as ordinary body text, and anything in the card that isn't a paragraph is left out. The class can sit alongside others.

The card only marks the paragraph; your website needs a line of CSS to draw the drop cap there. Add something like this under Code injection → Site header in Ghost, and adjust to taste:

<style>
.drop-cap-paragraph::first-letter {
  float: left;
  font-size: 3.4em;
  line-height: .8;
  padding: .06em .08em 0 0;
  font-weight: 700;
}
</style>

Email clients mostly ignore that rule, so the newsletter shows the same paragraph without the drop cap.

Using a leaky paywall?

If you're using a JavaScript-based solution like Outpost or PayGlue's "leaky" paywalls, which leave the post's access set to Public, be warned that Apple News will receive the full text of that content. Only Ghost's Public preview line, with a non-public access setting, protects content.

Contributor access

If you give a contributor an Apple News grant (Site settings → Users), use covers the Activity tab, including publishing a post manually, Resync, Make live and Delete; manage adds the Install, Syndication and Design tabs.