From 4e31549faa343c0dcd0941ed58ae633773ba091c Mon Sep 17 00:00:00 2001 From: Yang Jun Date: Sat, 20 Jun 2026 00:03:31 +0800 Subject: [PATCH] docs(readme): lead with quick start and scannable structure Restructure the README to match common OSS conventions: tagline and badges above the fold, copy-paste Quick start, Features list, and a compact Used by section. Remove the star plea, centered logo, and per-project marketing blurbs that pushed useful content down. Co-authored-by: Cursor --- README.md | 121 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 70 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index eb4d616b6..d7b98f319 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,61 @@ -# liquidjs +# LiquidJS + +> A simple, expressive and safe [Shopify Liquid][shopify/liquid] template engine for JavaScript — compatible with Jekyll, GitHub Pages, and Shopify themes. + [![npm version](https://img.shields.io/npm/v/liquidjs.svg?logo=npm&style=flat-square)](https://www.npmjs.org/package/liquidjs) [![npm downloads](https://img.shields.io/npm/dm/liquidjs.svg?style=flat-square)](https://www.npmjs.org/package/liquidjs) -[![Coverage](https://img.shields.io/coveralls/harttle/liquidjs.svg?style=flat-square)](https://coveralls.io/github/harttle/liquidjs?branch=master) [![Build Status](https://img.shields.io/github/actions/workflow/status/harttle/liquidjs/ci-build.yml?branch=master&style=flat-square)](https://github.com/harttle/liquidjs/actions/workflows/ci-build.yml?query=branch%3Amaster) -[![DUB license](https://img.shields.io/dub/l/vibe-d.svg?style=flat-square)](https://github.com/harttle/liquidjs/blob/master/LICENSE) -[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/harttle/liquidjs) +[![Coverage](https://img.shields.io/coveralls/harttle/liquidjs.svg?style=flat-square)](https://coveralls.io/github/harttle/liquidjs?branch=master) +[![License: MIT](https://img.shields.io/github/license/harttle/liquidjs?style=flat-square)](https://github.com/harttle/liquidjs/blob/master/LICENSE) -A simple, expressive and safe [Shopify][shopify/liquid] / GitHub Pages compatible template engine in pure JavaScript. -**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community so that [Jekyll sites](https://jekyllrb.com), [GitHub Pages](https://pages.github.com/) and [Shopify templates](https://themes.shopify.com/) can be ported to Node.js without pain. +[Documentation][doc] · [Playground](https://liquidjs.com/playground.html) · [Setup guide][setup] · [Contributing][contribution] -* [Documentation][doc] -* Please star [LiquidJS on GitHub][github]! -* Financial support via [GitHub Sponsors](https://github.com/sponsors/harttle). +## Quick start -

logo

+```js +import { Liquid } from 'liquidjs' -## What's it like? +const engine = new Liquid() +const html = await engine.parseAndRender( + 'Hello, {{ name | capitalize }}!', + { name: 'liquid' } +) +//=> 'Hello, Liquid!' +``` -Basically there're two types of Liquid syntax: tags enclosed by `{% %}` and outputs enclosed by `{{ }}`. A Liquid template looks like: +## Features + +- **Compatible** — Shopify Liquid, Jekyll, and GitHub Pages dialects +- **Safe by default** — `ownPropertyOnly`, `memoryLimit`, and `renderLimit` help sandbox untrusted templates +- **Runs everywhere** — Node.js, browser (UMD/ESM), and CLI via `npx liquidjs` +- **Extensible** — custom tags, filters, and [plugins][plugins] +- **Typed** — TypeScript definitions included + +## Installation + +**Node.js** + +```bash +npm install liquidjs +``` + +**Browser** (jsDelivr UMD bundle) + +```html + +``` + +**CLI** + +```bash +npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Liquid"}' +``` + +See the [setup guide][setup] for partials, layouts, caching, and other options. + +## Example + +Liquid templates use tags (`{% %}`) and outputs (`{{ }}`): ```liquid {% if username %} @@ -25,48 +63,25 @@ Basically there're two types of Liquid syntax: tags enclosed by `{% %}` and outp {% endif %} ``` -[A live demo](https://liquidjs.com/playground.html) is also available and here's a [quick tutorial](https://liquidjs.com/tutorials/intro-to-liquid.html) for Liquid syntax. +Try it in the [playground](https://liquidjs.com/playground.html) or read the [Liquid syntax tutorial](https://liquidjs.com/tutorials/intro-to-liquid.html). +## Used by -## Installation +- [Eleventy](https://www.11ty.dev/) +- [GitHub Docs](https://github.com/github/docs) +- [Kibana](https://github.com/elastic/kibana) +- [Microsoft Power Pages](https://learn.microsoft.com/en-us/power-pages/introduction) +- [Azure API Management developer portal](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal) +- [Directus](https://docs.directus.io/) +- [Builder.io](https://www.builder.io/m/developers) +- [Mitosis](https://github.com/BuilderIO/mitosis) +- [Pattern Lab](https://patternlab.io/) +- [Opensense](https://www.opensense.com/) +- [Rock RMS](https://www.rockrms.com/) +- [WISMOlabs](https://wismolabs.com/) +- [Freshet](https://chromewebstore.google.com/detail/freshet/mpclplhdencffbilobpcapccnihpelcg) -Install from npm in Node.js: - -```bash -npm install liquidjs -``` - -Or use the UMD bundle from jsDelivr: - -```html - -``` - -Or render directly from CLI using npx: - -```bash -npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Snake"}' -``` - -For more details, refer to the [Setup Guide][setup]. - -## Who's Using LiquidJS? - -- [Eleventy](https://www.11ty.dev/): Eleventy, a simpler static site generator. -- [Github Docs](https://github.com/github/docs): The open-source repo for docs.github.com. -- [Kibana](https://github.com/elastic/kibana): Elastic's analytics and visualization platform for Elasticsearch; workflow features use LiquidJS for Liquid templates. -- [Opensense](https://www.opensense.com/): The smarter way to send email. -- [Directus](https://docs.directus.io/): an instant REST+GraphQL API and intuitive no-code data collaboration app for any SQL database. -- [Rock](https://www.rockrms.com/): An open source CMS, Relationship Management System (RMS) and Church Management System (ChMS) all rolled into one. -- [Mitosis](https://github.com/BuilderIO/mitosis): Write components once, run everywhere. Compiles to React, Vue, Qwik, Solid, Angular, Svelte, and more. -- [Pattern Lab](https://patternlab.io/): a frontend workshop environment that helps you build, view, test, and showcase your design system's UI components. -- [Builder.io](https://www.builder.io/m/developers): the first and only headless CMS with a visual editor that lets you drag and drop with your components, directly within your current site or app. Completely API-driven, for cleaner code and simpler workflows. -- [Microsoft Power Pages](https://learn.microsoft.com/en-us/power-pages/introduction): a secure, enterprise-grade, low-code software as a service (SaaS) platform for creating, hosting, and administering modern external-facing business websites. -- [Azure API Management developer portal](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal): an automatically generated, fully customizable website with the documentation of your APIs. -- [WISMOlabs](https://wismolabs.com/): Post Purchase Experience platform for eCommerce retailers enhancing customer satisfaction by using LiquidJS to provide customizable post-purchase experiences through programmable email, SMS, order tracking pages, and webhooks. -- [Freshet](https://chromewebstore.google.com/detail/freshet/mpclplhdencffbilobpcapccnihpelcg): *JSON in, page out* — a Chrome extension that uses LiquidJS templates per URL pattern, so the JSON becomes a rendered, useful page. - -Feel free to create a PR or contact me to add your use case into this list! +Using LiquidJS in production? [Open a PR](https://github.com/harttle/liquidjs/edit/master/README.md) to add your project. ## Financial Support @@ -234,6 +249,10 @@ Want to contribute? see [Contribution Guidelines][contribution]. Thanks goes to +## License + +[MIT](LICENSE) © [Jun Yang](https://github.com/harttle) + [shopify/liquid]: https://shopify.github.io/liquid/ [plugins]: https://liquidjs.com/tutorials/plugins.html#Plugin-List [setup]: https://liquidjs.com/tutorials/setup.html