{"id":18471667,"url":"https://github.com/portabletext/portable-text-to-liquid","last_synced_at":"2025-10-17T20:03:02.484Z","repository":{"id":66183856,"uuid":"587688220","full_name":"portabletext/portable-text-to-liquid","owner":"portabletext","description":"Render Portable Text on a Shopify storefront using Liquid","archived":false,"fork":false,"pushed_at":"2023-09-28T15:46:20.000Z","size":7,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-16T18:47:03.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Liquid","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/portabletext.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-11T10:50:07.000Z","updated_at":"2024-09-12T23:12:17.000Z","dependencies_parsed_at":"2024-11-06T10:17:43.477Z","dependency_job_id":"1482f6bf-2a5d-4613-8b77-a9e0323e98d4","html_url":"https://github.com/portabletext/portable-text-to-liquid","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portabletext%2Fportable-text-to-liquid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portabletext%2Fportable-text-to-liquid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portabletext%2Fportable-text-to-liquid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portabletext%2Fportable-text-to-liquid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/portabletext","download_url":"https://codeload.github.com/portabletext/portable-text-to-liquid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253750477,"owners_count":21958307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T10:17:39.386Z","updated_at":"2025-10-17T20:02:57.437Z","avatar_url":"https://github.com/portabletext.png","language":"Liquid","funding_links":[],"categories":[],"sub_categories":[],"readme":"# portable-text-to-liquid\n\nRender [Portable Text](https://portabletext.org/) on a Shopify storefront using Liquid.\n\n## Installation\n\nAdd the contents of the `snippets` folder in this repo to the `snippets` folder of your Shopify theme. You can then customise the output according to your requirements.\n\n## Basic usage\n\nPass the snippet a `portableText` variable containing the JSON value of the Portable Text you want to display:\n\n```liquid\n{% render 'portable-text', portableText: liquidVariable %}\n```\n\nFor example, you might have a Sanity document – synced to a product metafield in the namespace `app--6007307--sanity` and the key `published` – with a `body` field containing Portable Text. To render this, your Liquid code would be:\n\n```liquid\n{% render 'portable-text', portableText: product.metafields.app--6007307--sanity.published.value.body %}\n```\n\n## How it works\n\nThe key principle of this collection of snippets is that the `portable-text.liquid` snippet loops through the blocks in the Portable Text and outputs a different snippet based on the `_type` of the block.\n\nFor example, if the `_type` is `block`, then `portable-text-block.liquid` will be rendered. If the `_type` is `span`, then `portable-text-span.liquid` will be rendered.\n\nThis is done recursively, so blocks containing nested blocks or spans will render as appropriate.\n\nIf you have customised your Portable Text editor, you may need to [amend the provided snippets](#customizing-output) to recognise other `_type` values, span `mark` definitions or `listItem` types.\n\nWe have provided some examples of custom snippets in this repo.\n\n## Styling the output\n\nThe rendered HTML does not have any styling applied, so you may want to either render a parent container with a class name you can target in your CSS (for example in the Dawn theme, the `pte` class), or [customize the output](#customizing-output) of the Liquid snippets.\n\n## Customizing output\n\nSnippets are provided in this package which make a decision about what to render. The snippets use Liquid to process these into output. Default snippets are provided for all standard features of the Portable Text spec, with logical defaults.\n\nThe `portable-text.liquid` snippet essentially loops through the blocks and outputs a different snippet based on the `_type` of the block.\n\nIn order to change the output, simply update the appropriate snippet according to the type:\n\n### Types\n\nDifferent types of Portable Text block content are rendered by the top level `portable-text.liquid` snippet. If you have created any custom types, you'll need to add these here. Essentially, just add an additional `when` to the `case` statement, and create a new snippet to render the content as needed.\n\nThere are a couple of examples in this repo - `portable-text-accordion.liquid` and `portable-text-callout.liquid` designed to illustrate this.\n\nIf an unknown type is encountered, nothing will be output, and a messaged will be logged in the browser console.\n\n### Blocks\n\nA snippet which renders portable text blocks with different style properties - such as `blockquote`, `h1` and `h2` – as well as list items.\n\nYou can amend the default HTML rendered here by amending the `portable-text-block.liquid` snippet. If you've created additional block styles, these can be added to the case statement here as well.\n\nIf an unknown block style is encountered, nothing will be output, and a message will be logged in the browser console.\n\n#### List Items\n\nIn the Portable Text specification, list items are not nested in a list block type. We've therefore added additional logic to handle list types in order to understand when lists should be opened and closed.\n\nIf you need to add new list item types, you'll need to define opening and closing tags for these in `portable-text-block.liquid` where the `listOpen` variables are declared, as well as where the `lastListItem` variable is used to establish a list should be closed. Finally, this will also need to be defined in `portable-text.liquid` where the final output checks whether a list is unclosed by checking `lastListItem`.\n\nIf a list item type doesn't have it's own definition, we'll render this as a `\u003cul\u003e` by default, and log a message in the browser console.\n\n### Spans / Marks\n\nA span renders inline text content and has marks to indicate the type of inline content - such as `strong`, `em` or `code`. The output of these can be handled by `portable-text-span.liquid`.\n\nFor custom marks with mark definitions, you can create additional definitions which can access the properties of the mark definition. An example of this is provided concerning a `link` mark where an `href` property contains the URL for the link.\n\nIf an unknown mark is encountered, then the span text will still be output. A message will be logged in the browser console to indicate a missing mark type.\n\n## Disabling errors / handling unknown types\n\nWhen a block, mark or list item with a type that is not known is encountered, by default message will be logged to the browser console indicating an unknown type has been encountered.\n\nTo disable this behavior, you can pass `false` to an `errors` variable when rendering the snippet:\n\n```jsx\n{% render 'portable-text', portableText: liquidVariable, errors: false %}\n```\n\n## License\n\nMIT © [Sanity.io](https://www.sanity.io/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportabletext%2Fportable-text-to-liquid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fportabletext%2Fportable-text-to-liquid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportabletext%2Fportable-text-to-liquid/lists"}