Add improved docs on what this project is

[BeLi4L]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

Go from this:

to this:

[codecov-commenter]

Codecov Report

Merging #1147 (8d2933e) into main (1e488d0) will not change coverage.
The diff coverage is n/a.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1147   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          906       906           
=========================================
  Hits           906       906           

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1e488d0...8d2933e. Read the comment docs.

[remcohaszing]

Thanks!

[wooorm]

Hmm, this is intentional. Treating them as sentences in an existing paragraph, I think is arguably more correct, but also makes things smaller.

Why do you think the current actual behavior is wrong? And yours is better?

[BeLi4L]

When I first landed on this page, I didn't see the inline In:, so I was confused that the output block had a title, but the input block didn't have any, until I realized it was inline.

It feels more logical to me to have In/Out titles like this, it gives a proper structure to the example, it's more consistent and thus make more sense to me.

If you think that it breaks the flow of the sentence, a solution could be to simply add a colon at the end, like:

You can use plugins to turn markdown into HTML:

**In**:

...

**Out**:

...

What do you think?

[wooorm]

Maybe it’s better to just use actual words, sentences, and not make them “labels”:

• **In**: -> This markdown:
• **Plugin**: -> …with this plugin:
• **Out**: -> …yields the following HTML:

[BeLi4L]

I integrated your suggestions, tell me what you think ;)

I'm not a huge fan of the intro sentence:

What is this?

You can use plugins to turn markdown into HTML.

Since directly after that, we show an example and then say:

You can use plugins to change markdown.

Shouldn't it be something like:

This library turns markdown into HTML.

instead? Without any mentions to "plugins" since it's not in the following example 🤔

[wooorm]

Hmm, agreed that it isn’t great yet.

This library turns markdown into HTML.

Without any mentions to "plugins" since it's not in the following example

The plugin is needed (remark-html), otherwise there is no HTML.

---

This section is to very quickly show what this project can do, what plugins can do.
This is already explained in words earlier.
And concrete examples are given later.
Plugins can do millions of things.
The goal here is: two very short examples of input/output to illustrate that.

Perhaps that’s just impossible to do. How about we make the examples shorter, but add optional detailed info?

What about:

## What is this?

With this project and a plugin, you can turn this markdown:

```markdown
# Hello, *Mercury*!
```

…into the following HTML:

```html
<h1>Hello, <em>Mercury</em>!</h1>
```

<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!
```

…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) => {
    visit(tree, (node) => {
      if (node.type === 'heading') {
        node.depth++
      }
    })
  }
}
```

</details>

This renders like:

---

What is this?

With this project and a plugin, you can turn this markdown:

# Hello, *Mercury*!

…into the following HTML:

<h1>Hello, <em>Mercury</em>!</h1>

Show example code

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>'

With another plugin, you can turn this markdown:

# Hi, Saturn!

…into the following markdown:

## Hi, Saturn!

Show example code

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) => {
    visit(tree, (node) => {
      if (node.type === 'heading') {
        node.depth++
      }
    })
  }
}

[BeLi4L]

Wow much better, I'll do that! 👍

[BeLi4L]

Done ;)

[wooorm]

Oh, one small thing! The tests are failing, because by default they don’t want HTML in markdown.
You can solve this by changing package.json:

  "remarkConfig": {
    "plugins": [
-     "preset-wooorm"
+     "remark-preset-wooorm",
+     [
+       "remark-lint-no-html",
+       false
+     ]
    ]
  },

[BeLi4L]

Done, thank you :D

[BeLi4L]

@wooorm I tried your suggested changes, and also with "preset-wooorm" instead of "remark-preset-wooorm", but I have another error now 😅

[wooorm]

That error was unrelated, a broken release by a build tool, which was fixed!

[wooorm]

Thank you!