From 083297733db30c90a5fd0210271137b34ce7b443 Mon Sep 17 00:00:00 2001
From: Jason Miller <developit@users.noreply.github.com>
Date: Fri, 22 May 2020 12:29:59 -0400
Subject: [PATCH] Readme Tweaks (#628)

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 57 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 1070b9c0..53bf90bd 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,18 @@
 
 ---
 
-## ✨ Features:
+<p align="center">
+  <strong>Guide → </strong>
+  <a href="#setup">Setup</a> ✯
+  <a href="#formats">Formats</a> ✯
+  <a href="#modern">Modern Mode</a> ✯
+  <a href="#usage">Usage &amp; Configuration</a> ✯
+  <a href="#options">All Options</a>
+</p>
+
+---
+
+## ✨ Features <a name="features"></a>
 
 - **One dependency** to bundle your library using only a `package.json`
 - Support for ESnext & async/await _(via [Babel] & [async-to-promises])_
@@ -19,37 +30,40 @@
 - 0 configuration TypeScript support
 - Built-in Terser compression & gzipped bundle size tracking
 
-## 🔧 Installation
+## 🔧 Installation & Setup <a name="setup"></a> <a name="installation"></a>
 
-### Download
+1️⃣ **Install** by running: `npm i -D microbundle`
 
-`npm i -D microbundle`
-
-### Set up your `package.json`
+2️⃣ **Set up** your `package.json`:
 
 ```js
 {
-  "source": "src/foo.js",          // Your source file (same as 1st arg to microbundle)
-  "main": "dist/foo.js",           // output path for CommonJS/Node
-  "module": "dist/foo.module.js",  // output path for JS Modules
-  "unpkg": "dist/foo.umd.js",      // optional, for unpkg.com
+  "name": "foo",                   // your package name
+  "source": "src/foo.js",          // your source code
+  "main": "dist/foo.js",           // where to generate the CommonJS/Node bundle
+  "module": "dist/foo.module.js",  // where to generate the ESM bundle
+  "unpkg": "dist/foo.umd.js",      // where to generate the UMD bundle (also aliased as "umd:main")
   "scripts": {
-    "build": "microbundle",        // uses "source" and "main" as input and output paths by default
-    "dev": "microbundle watch"
+    "build": "microbundle",        // compiles "source" to "main"/"module"/"unpkg"
+    "dev": "microbundle watch"     // re-build when source files change
   }
 }
 ```
 
-## 🤖 Modern Output
+3️⃣ **Try it out** by running `npm run build`.
+
+## 💽 Output Formats <a name="formats"></a>
+
+Microbundle produces <code title="ECMAScript Modules (import / export)">esm</code>, <code title="CommonJS (Node-style module.exports)">cjs</code>, <code title="Universal Module Definition (works everywhere)">umd</code> bundles with your code compiled to syntax that works pretty much everywhere. While it's possible to customize the browser or Node versions you wish to support using a [browserslist configuration](https://github.com/browserslist/browserslist#browserslist-), the default setting is optimal and strongly recommended.
 
-Microbundle's `esm`, `cjs`, `umd` and `iife` output formats all compile your code to syntax that works pretty much everywhere. You can customize which browser or Node versions you wish to support by [adding a browserslist configuration](https://github.com/browserslist/browserslist#browserslist-), however the default setting is recommended for most cases since it supports as many browsers as possible.
+## 🤖 Modern Mode <a name="modern"></a>
 
 In addition to the above formats, Microbundle also outputs a `modern` bundle specially designed to work in _all modern browsers_. This bundle preserves most modern JS features when compiling your code, but ensures the result runs in 90% of web browsers without needing to be transpiled. Specifically, it uses [preset-modules](https://github.com/babel/preset-modules) to target the set of browsers that support `<script type="module">` - that allows syntax like async/await, tagged templates, arrow functions, destructured and rest parameters, etc. The result is generally smaller and faster to execute than the `esm` bundle:
 
 ```js
 // Our source, "src/make-dom.js":
 export default async function makeDom(tag, props, children) {
-  const el = document.createElement(tag);
+  let el = document.createElement(tag);
   el.append(...(await children));
   return Object.assign(el, props);
 }
@@ -66,7 +80,7 @@ Compiling the above using Microbundle produces the following `modern` and `esm`
 
 ```js
 export default async function(e, t, a) {
-  var n = document.createElement(e);
+  let n = document.createElement(e);
   n.append(...await a);
   return Object.assign(n, t);
 }
@@ -86,7 +100,9 @@ export default function(e, t, r) { try {
 
 </td></tbody></table>
 
-This is enabled by default - all you have to do is add the field to your `package.json`. While the best way to point to modern source from a package.json is [still being discussed](https://twitter.com/_developit/status/1263174528974364675), you might choose to use the "module" field:
+This is enabled by default - all you have to do is add the field to your `package.json`.
+
+<details><summary>💁‍♂️ <em>How to point to modern code in a package.json is <a href="https://twitter.com/_developit/status/1263174528974364675">being discussed</a>. You might use the "module" field.</em></summary>
 
 ```js
 {
@@ -98,15 +114,27 @@ This is enabled by default - all you have to do is add the field to your `packag
 }
 ```
 
-## 📦 Usage
+</details>
+
+## 📦 Usage & Configuration <a name="usage"></a>
 
 Microbundle includes two commands - `build` (the default) and `watch`. Neither require any options, but you can tailor things to suit your needs a bit if you like.
 
 ### `microbundle` / `microbundle build`
 
-Unless overridden via the command line, microbundle uses the `source` property in your `package.json` to locate the input file, and the `main` property for the output.
+Unless overridden via the command line, microbundle uses the `source` property in your `package.json` to locate the input file, and the `main` property for the output:
+
+```js
+{
+  "source": "src/index.js",      // input
+  "main": "dist/my-library.js",  // output
+  "scripts": {
+    "build": "microbundle"
+  }
+}
+```
 
-For UMD builds, microbundle will use a snake case version of the `name` field in your `package.json` as export name. This can be overridden either by providing an `amdName` key in your `package.json` or via the `--name` flag in the cli.
+For UMD builds, microbundle will use a snake_case version of the `name` field in your `package.json` as export name. This can be customized using an `"amdName"` key in your `package.json` or the `--name` command line argument.
 
 ### `microbundle watch`
 
@@ -138,14 +166,16 @@ imports will be scoped.
 
 ### Specifying builds in `package.json`
 
-You can specify output builds in a `package.json` as follows:
+Microbundle uses the fields from your `package.json` to figure out where it should place each generated bundle:
 
 ```
-"main": "dist/foo.js",          // CJS bundle
-"umd:main": "dist/foo.umd.js",  // UMD bundle
-"module": "dist/foo.m.js",       // ES Modules bundle
-"source": "src/foo.js",         // custom entry module (same as 1st arg to microbundle)
-"types": "dist/foo.d.ts",       // TypeScript typings
+{
+  "main": "dist/foo.js",            // CommonJS bundle
+  "umd:main": "dist/foo.umd.js",    // UMD bundle
+  "module": "dist/foo.m.js",        // ES Modules bundle
+  "esmodule": "dist/foo.modern.js", // Modern bundle
+  "types": "dist/foo.d.ts"          // TypeScript typings
+}
 ```
 
 ### Mangling Properties
@@ -162,7 +192,7 @@ To achieve the smallest possible bundle size, libraries often wish to rename int
 
 It's also possible to configure repeatable short names for each mangled property, so that every build of your library has the same output. **See the wiki for a [complete guide to property mangling in Microbundle](https://github.com/developit/microbundle/wiki/mangle.json).**
 
-### All CLI Options
+### All CLI Options <a name="options"></a>
 
 ```
 Usage