From bb4c81434dc084a5e68d29d79641236f625689dd Mon Sep 17 00:00:00 2001
From: Valentin Vetter <BeLi4L@users.noreply.github.com>
Date: Tue, 9 May 2023 12:16:20 +0200
Subject: [PATCH] Add improved docs on what this project is

Closes GH-1147.

Reviewed-by: Remco Haszing <remcohaszing@gmail.com>
Reviewed-by: Titus Wormer <tituswormer@gmail.com>
---
 package.json |  6 +++++-
 readme.md    | 55 +++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 47 insertions(+), 14 deletions(-)

diff --git a/package.json b/package.json
index 438897267..535f777c6 100644
--- a/package.json
+++ b/package.json
@@ -55,7 +55,11 @@
   },
   "remarkConfig": {
     "plugins": [
-      "preset-wooorm"
+      "preset-wooorm",
+      [
+        "remark-lint-no-html",
+        false
+      ]
     ]
   },
   "typeCoverage": {
diff --git a/readme.md b/readme.md
index c5ccc9f40..6f67c7d2c 100644
--- a/readme.md
+++ b/readme.md
@@ -55,31 +55,63 @@ You can use the many existing plugins or you can make your own.
 
 ## What is this?
 
-You can use plugins to turn markdown into HTML.
-**In**:
+With this project and a plugin, you can turn this markdown:
 
 ```markdown
 # Hello, *Mercury*!
 ```
 
-**Out**:
+…into the following HTML:
 
 ```html
 <h1>Hello, <em>Mercury</em>!</h1>
 ```
 
-You can use plugins to change markdown.
-**In**:
+<details><summary>Show example code</summary>
+
+```js
+import {unified} from 'unified'
+import remarkParse from 'remark-parse'
+import remarkHtml from 'remark-html'
+
+const file = await unified()
+    .use(remarkParse)
+    .use(remarkHtml)
+    .process('# Hello, *Mercury*!')
+
+console.log(String(file)) // => '<h1>Hello, <em>Mercury</em>!</h1>'
+```
+
+</details>
+
+With another plugin, you can turn this markdown:
 
 ```markdown
 # Hi, Saturn!
 ```
 
-**Plugin**:
+…into the following markdown:
+
+```markdown
+## Hi, Saturn!
+```
+
+<details><summary>Show example code</summary>
 
 ```js
+import {unified} from 'unified'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
 import {visit} from 'unist-util-visit'
 
+const file = await unified()
+    .use(remarkParse)
+    .use(myRemarkPluginToIncreaseHeadings)
+    .use(remarkStringify)
+    .process('# Hi, Saturn!')
+
+console.log(String(file)) // => '## Hi, Saturn!'
+
 /** @type {import('unified').Plugin<[], import('mdast').Root>} */
 function myRemarkPluginToIncreaseHeadings() {
   return (tree) => {
@@ -92,11 +124,7 @@ function myRemarkPluginToIncreaseHeadings() {
 }
 ```
 
-**Out**:
-
-```markdown
-## Hi, Saturn!
-```
+</details>
 
 You can use remark for many different things.
 **[unified][]** is the core project that transforms content with ASTs.
@@ -349,13 +377,14 @@ extensions.
 
 The syntax tree format used in remark is [mdast][].
 It represents markdown constructs as JSON objects.
-**In**:
+
+This markdown:
 
 ```markdown
 ## Hello *Pluto*!
 ```
 
-**Out**:
+yields the following tree:
 
 ```js
 {