From 11eb8e9439ced39b8818a1b471e8f8f7e8499446 Mon Sep 17 00:00:00 2001
From: Vladimir Agafonkin <agafonkin@gmail.com>
Date: Thu, 14 May 2020 23:55:38 +0300
Subject: [PATCH] improve readme

---
 README.md | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index ca25c35..0fc8c4e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,11 @@
 # yeahjs
 
-A tiny, modern, fast implementation of EJS (Embedded JavaScript Templates). A nearly drop-in replacement for [ejs](https://ejs.co/) with a few [opinionated limitations](#compared-to-ejs).
+A tiny, modern, fast implementation of EJS (Embedded JavaScript Templates). A nearly drop-in replacement for [`ejs`](https://ejs.co/) with a few [intentional limitations](#compared-to-ejs).
+
+[![Build Status](https://github.com/mourner/yeahjs/workflows/Node/badge.svg?branch=master)](https://github.com/mourner/yeahjs/actions)
+[![Install Size](https://packagephobia.now.sh/badge?p=yeahjs)](https://packagephobia.now.sh/result?p=yeahjs)
+[![Min-zipped Size](https://badgen.net/bundlephobia/minzip/yeahjs)](https://bundlephobia.com/result?p=yeahjs)
+[![Simply Awesome](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects)
 
 ## Example
 
@@ -13,7 +18,7 @@ A tiny, modern, fast implementation of EJS (Embedded JavaScript Templates). A ne
 ```
 
 ```js
-const template = yejs.compile(ejs);
+const template = yeahjs.compile(ejs);
 const output = template({items: ['flour', 'water', 'salt']});
 ```
 
@@ -27,10 +32,29 @@ const output = template({items: ['flour', 'water', 'salt']});
 
 ## Compared to `ejs`
 
-- Strict mode only (no `with` keyword in compiled functions).
-- Only static-resolution includes (`include('header.ejs')`, but not `include(dir + file)`).
-- File handling not included, but you can provide it with `read` and `resolve` options (see example below).
-- `cache` option accepts a simple object (`{}`).
+There are a few key differences that allow `yeahjs` to be so small and fast:
+
+- **Strict mode** only (no `with` keyword in compiled functions).
+- Only **static path includes** (`include('header.ejs')`, but not `include(dir + file)`).
+- Pluggable file handling — it's not included, but you can provide it with `read` and `resolve` options (see [example](#file-handling)).
+
+Otherwise `yeahjs` identical output to `ejs`, passing all compilation and rendering tests.
+
+## Options
+
+```js
+const template = yeahjs.compile(ejs, options);
+````
+
+- `localsName`: the namespace to use for accessing template data (`locals` by default).
+- `locals`: an array of variables to make accessible directly (e.g. `['foo']` will allow `<%= foo %>` instead of `<%= locals.foo %>`).
+- `context`: an object to use as `this` in templates (`null` by default).
+- `escape`: a custom escaping function for values inside `<%= ... %>` (escapes XML by default).
+- `async`: if `true`, generates an async function to make it possible to use `await` inside templates (`false` by default)
+- `filename`: the file name of the template if present (used for resolving includes).
+- `read`: a function of the form `(filename) => content` for reading includes (e.g. from file system in Node).
+- `resolve`: a function of the form `(parentPath, includePath)` for resolving include paths (e.g. use `path.join(path.dirname(parent), filename)` in Node).
+- `cache`: an object to cache compiled includes in for faster compilation; reuse between `compile` runs for best performance (`{}` by default).
 
 ## File handling