Add improved docs on what this project is

Closes GH-1147.

Reviewed-by: Remco Haszing <[email protected]>
Reviewed-by: Titus Wormer <[email protected]>

Author: BeLi4L

package.json

@@ -55,7 +55,11 @@
   },
   "remarkConfig": {
     "plugins": [
-      "preset-wooorm"
+      "preset-wooorm",
+      [
+        "remark-lint-no-html",
+        false
+      ]
     ]
   },
   "typeCoverage": {

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
 {