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..e7a28f8 --- /dev/null +++ b/themes/helpers/data/social_accounts.mdx @@ -0,0 +1,102 @@ +--- +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 links for the social accounts configured under Settings > General > Social accounts: + +```handlebars +{{#social_accounts @site}} + + {{name}} + +{{/social_accounts}} +``` + +## Data Variables + +When inside a `{{#social_accounts}}` block, the following properties are available for each account: + +* **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`) + +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}} + + {{name}} + +{{/social_accounts}} +{{/foreach}} +``` + +On an author page, the author is named `author`: + +```handlebars +{{#social_accounts author}} + + {{name}} + +{{/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}} +``` + +### Using partials + +Most themes ship a separate icon partial per platform — `partials/icons/x.hbs`, `partials/icons/facebook.hbs`, and so on — and want `{{#social_accounts}}` to pull in the right one based on `{{type}}`. + +This needs a **dynamic partial**, and the partial must be invoked using the **block form** (`{{#> …}}…{{/undefined}}`): + +```handlebars +{{#social_accounts @site}} + + {{#> (concat "icons/" type)}} + {{!-- Fallback rendered when no per-platform icon partial exists --}} + {{name}} + {{/undefined}} + +{{/social_accounts}} +``` + +The inline form (`{{> (concat "icons/" type)}}`) looks tempting, but it throws a page error if the named partial doesn't exist — for example, when a new platform ships before a theme adds the matching icon. gscan rejects the inline form on purpose for this reason. The block form falls back to the inner content instead, so the page keeps rendering. + +Note the closing tag must be `{{/undefined}}`. This looks unusual, but it's the only form Handlebars accepts when closing a dynamic partial block. + +## Supported platforms + +`x`, `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: