Skip to main content
The BeyondWords Ghost plugin allows you to automatically generate and embed audio and video versions of your posts.
Audio/video format, script templates, video templates, voices, and player settings are controlled by your BeyondWords project defaults unless you configure otherwise in the dashboard. You can also set up other distributions for your audio and video content, or configure the integration via the Ghost API.

​
How it works

Ghost is a server-side integration—unlike Magic Embed, content is pushed from Ghost to BeyondWords when posts change, not fetched from the visitor’s browser.
  1. You connect Ghost to BeyondWords by saving your Ghost Admin API Key and API URL in the dashboard. BeyondWords registers webhooks on your Ghost site for post.added and post.edited events.
  2. When you publish or update a post, Ghost sends the post payload to BeyondWords. The post’s title and html become the content item’s title and body; the Ghost post ID becomes source_id and the post URL becomes source_url.
  3. BeyondWords processes the HTML with auto_segment (applying content filters if configured) and generates audio/video.
  4. The player script in your theme’s Site footer loads on each post page, identifies the content by page URL, and embeds the player once generation is complete.
On first publish, the player may not appear until audio/video generation finishes—usually within a few minutes.

​
Connect Ghost to BeyondWords

1

Create a custom integration in Ghost

In Ghost Admin, go to Settings → Integrations.Click Add custom integration, name it BeyondWords, then click Add.Copy the Admin API Key and API URL—you’ll need both in the next step.
2

Save credentials in BeyondWords

Go to Settings → Integrations → Ghost in your BeyondWords project dashboard.Paste the API URL and Admin API Key from Ghost, then click Save changes.BeyondWords validates the credentials and registers webhooks on your Ghost site automatically. You should see a success message confirming the connection.
3

Copy the embed code

In the Embed code dropdown on the same page, select the format you want on post pages:
OptionPlayer shows
Audio articleAudio version of the full article
Audio summaryAudio version of the script (if your project generates one)
Video articleVideo version of the full article
Video summaryVideo version of the script (if your project generates one)
Click the copy icon alongside the embed code.
4

Add the embed code to Ghost

In Ghost Admin, go to Settings → Code injection and open the editor.In the Site footer section, paste the embed code. Take care not to interfere with any existing scripts.Set target to the CSS selector where the player should appear in your theme—for example .post-full-content, article, article header, or .content. The dashboard embed defaults to .post-full-content, which works for most Ghost themes.Click Save.
5

Publish a post

Publish or update a post in Ghost as normal. The post appears in your BeyondWords dashboard and audio/video generation starts automatically.Once generation completes, the player loads on the post page.

​
What Ghost sends to BeyondWords

On each post.added or post.edited webhook, BeyondWords maps the Ghost post to a content item:
Ghost fieldBeyondWords field
Post idsource_id
Post urlsource_url
Post titleTitle
Post htmlBody (processed with auto_segment)
Post feature_imageFeature image
First author nameAuthor
published_at (or updated_at)Publish date
Draft posts are not published to the player. Posts tagged with #beyondwords-skip are treated as unpublished—see Skip generation for specific posts below.

​
Player placement

The embed code uses the JavaScript SDK (BeyondWords.Player). If you don’t pass a content identifier, the player matches content using the current page URL (window.location.href), which corresponds to the post’s source_url. Set target to a CSS selector for the element the player should inject into. The player is inserted as the first child of that element. If your theme uses a non-standard layout, inspect the post template and choose a selector that wraps the article header or body. You can also add a dedicated container in your theme: 
<div class="beyondwords-target"></div>
Then set target: '.beyondwords-target' in the embed code. For advanced theme integration, the @beyondwords/ghost-helper package can auto-detect the target element on Ghost post and page templates. The dashboard embed code uses the player SDK directly, which is the recommended approach for most sites. Customize player appearance in Distribution → Player in your dashboard, or pass additional player properties in the embed script.

​
Fine-tuning your integration

  • Content extraction: Content filters apply to post HTML sent via webhooks. Use filters to exclude newsletter blocks, related posts, or other recurring elements.
  • Data attributes: Add data-beyondwords-* attributes to your Ghost theme templates or post HTML for metadata and per-paragraph control.
  • Player settings: Configure widget style, colors, and behavior.
  • Generate scripts: Required if you use an Audio summary or Video summary embed code variant.

​
Skip generation for specific posts

To prevent a post from generating or updating audio/video:
  1. In the Ghost post editor, open the Post settings side panel
  2. In the Tags field, add the internal tag #beyondwords-skip
  3. Publish your post as usual
Effects:
  • New posts with this tag are not ingested for generation.
  • Existing posts with this tag are marked unpublished—the player will not load. Future post edits will not trigger regeneration.
  • Remove the tag and re-publish to resume normal sync.

​
FAQs

No. When you save your Ghost credentials in the BeyondWords dashboard, webhooks for post.added and post.edited are registered on your Ghost site automatically.
The embed script identifies content by the post page URL. BeyondWords stores each Ghost post’s canonical URL as source_url when the webhook fires. As long as the URL in the visitor’s browser matches, the player loads the correct audio or video.
Yes—choose Audio summary or Video summary in the embed code dropdown. Your project must generate scripts for content items (configure in Content → Preferences or per-item in the Editor). The Ghost integration only sends the post body; script generation happens on the BeyondWords side.
Editing in the Editor switches the content item to manual_segment processing and disables automatic CMS updates (auto_segment_updates_enabled). Ghost webhook updates for that post will be blocked until you re-enable automatic updates or send a new API update with type set to auto_segment. Prefer content filters over Editor edits if you want Ghost updates to keep syncing.
Dashboard content filters apply to the post HTML sent via webhooks, because Ghost content is processed with auto_segment. Configure filters in Settings → Extraction → Filters. See the content extraction guide.
Go to Distribution → Player in your BeyondWords project dashboard for widget style, colors, and default behavior.For per-site customization, edit the embed script in Ghost Code injection—any player property can be passed to BeyondWords.Player in the onload handler.
  • Confirm audio/video generation has completed in the BeyondWords dashboard
  • Check the post is published and does not have the #beyondwords-skip tag
  • Verify the embed code is in Site footer code injection and target matches an element in your theme
  • Open the browser console for JavaScript errors—a missing target element will prevent the player from loading

​
Getting help

If you encounter issues or have questions, contact support. Include your Ghost site URL, a sample post link, and whether the post appears in your BeyondWords dashboard.