From 12446684249b6823f5a0a04a440e56d6693caf11 Mon Sep 17 00:00:00 2001 From: Hannah Wolfe Date: Wed, 13 May 2026 11:14:01 +0100 Subject: [PATCH 1/2] Document {{#social_accounts}} block helper MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New block iterator helper added in TryGhost/Ghost#27834. It yields each connected social account on a given source object (@site or author), replacing repetitive {{#if twitter}}…{{#if facebook}}… chains in themes. Per-iteration it exposes {type, href, username, name} so themes keep full control of markup. Adds the new page under Data helpers, links it from the index table, and slots it into the docs.json nav next to {{social_url}}. --- docs.json | 1 + themes/helpers/data.mdx | 1 + themes/helpers/data/social_accounts.mdx | 77 +++++++++++++++++++++++++ themes/helpers/data/social_url.mdx | 2 + 4 files changed, 81 insertions(+) create mode 100644 themes/helpers/data/social_accounts.mdx diff --git a/docs.json b/docs.json index 160b354..cda39ea 100644 --- a/docs.json +++ b/docs.json @@ -117,6 +117,7 @@ "/themes/helpers/data/content", "/themes/helpers/data/date", "/themes/helpers/data/excerpt", + "/themes/helpers/data/social_accounts", "/themes/helpers/data/social_url", "/themes/helpers/data/img_url", "/themes/helpers/data/link", diff --git a/themes/helpers/data.mdx b/themes/helpers/data.mdx index 5754589..3627cad 100644 --- a/themes/helpers/data.mdx +++ b/themes/helpers/data.mdx @@ -16,6 +16,7 @@ description: Data helpers are used to output data from your site. Use this refer | [content](/themes/helpers/data/content/) | Outputs the full post content as HTML | | [date](/themes/helpers/data/date/) | Outputs the date in a format of your choosing | | [excerpt](/themes/helpers/data/excerpt/) | Outputs the custom excerpt, or the post content with HTML stripped | +| [social\_accounts](/themes/helpers/data/social_accounts/) | Iterates the connected social accounts on a site or author | | [social\_url](/themes/helpers/data/social_url/) | Outputs the full URL to a social profile | | [img\_url](/themes/helpers/data/img_url/) | Outputs the correctly calculated URL for the provided image property | | [link](/themes/helpers/data/link/) | Creates links with dynamic classes | diff --git a/themes/helpers/data/social_accounts.mdx b/themes/helpers/data/social_accounts.mdx new file mode 100644 index 0000000..e9a4e7d --- /dev/null +++ b/themes/helpers/data/social_accounts.mdx @@ -0,0 +1,77 @@ +--- +title: "social_accounts" +description: 'Usage: `{{#social_accounts @site}}{{/social_accounts}}`' +--- + +*** + +`{{#social_accounts}}` is a block helper that iterates over the connected social accounts on a given source object — usually `@site` or an author. The source must be passed as a positional argument. + +### Simple Example + +Render a row of icons for the social accounts configured under Settings > General > Social accounts: + +```handlebars +{{#social_accounts @site}} + + {{> (concat "icons/" type)}} + +{{/social_accounts}} +``` + +## Data Variables + +When inside a `{{#social_accounts}}` block, the following properties are available for each account: + +* **type** (string) - the storage key (e.g. `twitter`, `bluesky`) +* **href** (string) - the full URL to the profile +* **username** (string) - the raw stored handle or URL fragment +* **name** (string) - the human-readable platform label (e.g. `X`, `Facebook`) + +The standard iteration variables are also available: + +* **@index** (number) - the 0-based index of the current iteration +* **@number** (number) - the 1-based index of the current iteration +* **@first** (boolean) - true if this is the first iteration +* **@last** (boolean) - true if this is the last iteration +* **@odd** (boolean) - true if the @index is odd +* **@even** (boolean) - true if the @index is even + +## Usage + +### Per-author accounts + +When used inside `{{#foreach authors}}`, pass `this` to iterate the current author’s accounts: + +```handlebars +{{#foreach authors}} +

{{name}}

+{{#social_accounts this}} + {{> (concat "icons/" type)}} +{{/social_accounts}} +{{/foreach}} +``` + +On an author page, the author is named `author`: + +```handlebars +{{#social_accounts author}} +{{> (concat "icons/" type)}} +{{/social_accounts}} +``` + +### \{\{else}} and negation + +Like all block helpers, `{{#social_accounts}}` supports an `{{else}}` block, which is executed when there are no connected accounts: + +```handlebars +{{#social_accounts @site}} +{{name}} +{{else}} +

No social accounts connected yet.

+{{/social_accounts}} +``` + +## Supported platforms + +`twitter`, `facebook`, `linkedin`, `bluesky`, `threads`, `mastodon`, `tiktok`, `youtube`, `instagram`. Platforms without a value set on the source are skipped. diff --git a/themes/helpers/data/social_url.mdx b/themes/helpers/data/social_url.mdx index 1fb0701..0ff90a4 100644 --- a/themes/helpers/data/social_url.mdx +++ b/themes/helpers/data/social_url.mdx @@ -12,6 +12,8 @@ When called inside an author scope (e.g. `{{#author}}` or `{{#foreach authors}}` Supported platforms: `facebook`, `twitter`, `linkedin`, `threads`, `bluesky`, `mastodon`, `tiktok`, `youtube`, `instagram`. All nine are configurable both per-author (Staff > [user]) and sitewide (Settings > General > Social accounts). +To render a row of icons for every connected platform on a single object, see [`{{#social_accounts}}`](/themes/helpers/data/social_accounts/). + ### Examples Output the author’s Threads URL, using an `author` block: From dd5209b7e7e202bc79fa1499e28dcffe9ebe64cb Mon Sep 17 00:00:00 2001 From: Hannah Wolfe Date: Wed, 13 May 2026 18:17:17 +0100 Subject: [PATCH 2/2] Use the modern X key in the supported-platforms list The helper emits {{type}}: "x" for the X/Twitter platform (matching the admin UI label and theme partial conventions); the docs were referencing the legacy storage key. See TryGhost/Ghost#27871. --- themes/helpers/data/social_accounts.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/themes/helpers/data/social_accounts.mdx b/themes/helpers/data/social_accounts.mdx index e9a4e7d..8277e46 100644 --- a/themes/helpers/data/social_accounts.mdx +++ b/themes/helpers/data/social_accounts.mdx @@ -23,7 +23,7 @@ Render a row of icons for the social accounts configured under Settings > Genera When inside a `{{#social_accounts}}` block, the following properties are available for each account: -* **type** (string) - the storage key (e.g. `twitter`, `bluesky`) +* **type** (string) - the platform key (e.g. `x`, `bluesky`) * **href** (string) - the full URL to the profile * **username** (string) - the raw stored handle or URL fragment * **name** (string) - the human-readable platform label (e.g. `X`, `Facebook`) @@ -74,4 +74,4 @@ Like all block helpers, `{{#social_accounts}}` supports an `{{else}}` block, whi ## Supported platforms -`twitter`, `facebook`, `linkedin`, `bluesky`, `threads`, `mastodon`, `tiktok`, `youtube`, `instagram`. Platforms without a value set on the source are skipped. +`x`, `facebook`, `linkedin`, `bluesky`, `threads`, `mastodon`, `tiktok`, `youtube`, `instagram`. Platforms without a value set on the source are skipped.