Add improved docs

doc/getting-started.md

@@ -1,227 +1,6 @@
-![remark][logo]
-
 # Getting started
 
-**remark** transforms markdown.
-It’s an ecosystem of [plugins][].
-If you get stuck, [issues][] and [Discussions][] are good places to get help.
-
-It’s built on [unified][], make sure to read it and its [website][] too.
-
-## Contents
-
-*   [Intro](#intro)
-*   [Command line](#command-line)
-*   [Using remark in a project](#using-remark-in-a-project)
-*   [Programmatic usage](#programmatic-usage)
-
-## Intro
-
-Out of the box, **remark** transforms markdown: markdown is given, reformatted,
-and written:
-
-```md
-# Alpha #
-Bravo charlie **delta** __echo__.
-- Foxtrot
-```
-
-Yields:
-
-```md
-# Alpha
-
-Bravo charlie **delta** **echo**.
-
-*   Foxtrot
-```
-
-But, much more can be done, [through plugins][plugins].
-
-## Command line
-
-**remark**’s CLI is a simple way to process markdown files from the
-command line.  Its interface is provided by [**unified-args**][unified-args].
-
-Install [`remark-cli`][cli] and dependencies (in this case a [linting
-preset][preset] and [`remark-html`][html]) with [npm][]:
-
-```sh
-npm install --global remark-cli remark-html remark-preset-lint-markdown-style-guide
-```
-
-`readme.md` contains:
-
-```md
-_Hello_.
-```
-
-Now, to process `readme.md`, run the following:
-
-```sh
-remark readme.md --use html --use preset-lint-markdown-style-guide
-```
-
-Yields:
-
-```txt
-<p><em>Hello</em>.</p>
-readme.md.md
-  1:1-1:8  warning  Emphasis should use `*` as a marker  emphasis-marker  remark-lint
-
-⚠ 1 warning
-```
-
-## Using remark in a project
-
-In the previous example, `remark-cli` was installed globally.
-That’s generally a bad idea.
-Here we’re going to use the CLI to lint an npm package.
-
-Say we have the following `package.json`:
-
-```json
-{
-  "name": "my-package",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test": "node test.js"
-  }
-}
-```
-
-And install `remark-cli`, `remark-html`, and
-`remark-preset-lint-markdown-style-guide` into it as a dev-dependencies:
-
-```sh
-npm install --save-dev remark-cli remark-html remark-preset-lint-markdown-style-guide
-```
-
-The `--save-dev` option stores the dependencies in our `package.json`:
-
-```diff
- {
-   "name": "my-package",
-   "version": "1.0.0",
-   "type": "module",
-+  "devDependencies": {
-+    "remark-cli": "^10.0.0",
-+    "remark-html": "^14.0.0",
-+    "remark-preset-lint-markdown-style-guide": "^5.0.0"
-+  },
-   "scripts": {
-     "test": "node test.js"
-   }
- }
-```
-
-Then, we change our `test` script to include remark, and add
-configuration:
-
-```diff
- {
-   "name": "my-package",
-   "version": "1.0.0",
-   "type": "module",
-   "devDependencies": {
-     "remark-cli": "^10.0.0",
-     "remark-html": "^14.0.0",
-     "remark-preset-lint-markdown-style-guide": "^5.0.0"
-   },
-   "scripts": {
--    "test": "node test.js"
-+    "test": "remark . --quiet --frail && node test.js"
-+  },
-+  "remarkConfig": {
-+    "plugins": [
-+      "preset-lint-markdown-style-guide",
-+      "html"
-+    ]
-   }
- }
-```
-
-Now from the command line we can run:
-
-```sh
-npm test
-```
-
-This will lint all markdown files when we test the project.
-[`--frail`][frail] ensures the command fails if a code-style violation
-is found, and [`--quiet`][quiet] hides successful files from the report.
-
-## Programmatic usage
-
-The programmatic interface of **remark** is provided by
-[**unified**][unified].
-In fact, [`remark`][api] is two plugins: [`remark-parse`][parse] and
-[`remark-stringify`][stringify].
-
-Install [`remark`][api] and dependencies with [npm][]:
-
-```sh
-npm install vfile-reporter remark remark-html remark-preset-lint-markdown-style-guide
-```
-
-`index.js` contains:
-
-```js
-import {reporter} from 'vfile-reporter'
-import {remark} from 'remark'
-import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'
-import remarkHtml from 'remark-html'
-
-remark()
-  .use(remarkPresetLintMarkdownStyleGuide)
-  .use(remarkHtml)
-  .process('_Hello_.')
-  .then((file) => {
-    console.error(reporter(file))
-    console.log(String(file))
-  })
-```
-
-`node index.js` yields:
-
-```txt
-  1:1-1:8  warning  Emphasis should use `*` as a marker  emphasis-marker  remark-lint
-
-⚠ 1 warning
-<p><em>Hello</em>.</p>
-```
-
-<!-- Definitions -->
-
-[logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
-
-[issues]: https://github.com/remarkjs/remark/issues
-
-[discussions]: https://github.com/remarkjs/remark/discussions
-
-[npm]: https://docs.npmjs.com/cli/install
-
-[api]: https://github.com/remarkjs/remark/tree/main/packages/remark
-
-[cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
-
-[plugins]: https://github.com/remarkjs/remark/tree/main/doc/plugins.md
-
-[unified]: https://github.com/unifiedjs/unified
-
-[website]: https://unifiedjs.com
-
-[unified-args]: https://github.com/unifiedjs/unified-args
-
-[frail]: https://github.com/unifiedjs/unified-args#--frail
-
-[quiet]: https://github.com/unifiedjs/unified-args#--quiet
-
-[parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
-
-[stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
-
-[preset]: https://github.com/remarkjs/remark-lint/tree/HEAD/packages/remark-preset-lint-markdown-style-guide
+See [the monorepo readme][remark] for what the remark ecosystem is and examples
+of how to get started.
 
-[html]: https://github.com/remarkjs/remark-html
+[remark]: https://github.com/remarkjs/remark

doc/plugins.md

@@ -2,33 +2,33 @@
 
 # Plugins
 
-**remark** is a markdown processor powered by plugins part of the [unified][]
-[collective][].
+**remark** is a tool that transforms markdown with plugins.
+See [the monorepo readme][remark] for info on what the remark ecosystem is.
+This page lists existing plugins.
 
 ## Contents
 
 *   [List of plugins](#list-of-plugins)
 *   [List of presets](#list-of-presets)
 *   [List of utilities](#list-of-utilities)
-*   [Using plugins](#using-plugins)
-*   [Creating plugins](#creating-plugins)
+*   [Use plugins](#use-plugins)
+*   [Create plugins](#create-plugins)
 
 ## List of plugins
 
-See [awesome remark][awesome] for the most awesome projects in the ecosystem.
+See [`awesome-remark`][awesome-remark] for the most awesome projects in the
+ecosystem.
 More plugins can be found on GitHub tagged with the
 [`remark-plugin` topic][topic].
 
-Have a good idea for a new plugin?
-See [Creating plugins][create] below.
+> 👉 **Note**: some plugins don’t work with recent versions of remark due to
+> changes in its underlying parser (micromark).
+> Plugins that are up to date or unaffected are marked with `🟢` while plugins
+> that are **currently broken** are marked with `⚠️`.
 
-Some plugins are affected by the recent switch in the underlying parser of
-remark.
-Their status is encoded below as:
-
-*   🟢 This plugin **was not affected** or **a new version is already released**
-*   ⚠️ This plugin is affected: it’s **currently broken** and maintainers
-    have been notified
+> 💡 **Tip**: remark plugins work with markdown and **rehype** plugins work with
+> HTML.
+> See rehype’s [List of plugins][rehype-plugins] for more plugins.
 
 The list of plugins:
 
@@ -272,48 +272,56 @@ The list of plugins:
 
 ## List of presets
 
-See [npm search][npm-preset-search] or [github search][github-preset-search]
-for available and often inspirational presets.
+Use [GitHub search][github-preset-search] to find available and often
+inspirational presets.
 
 ## List of utilities
 
-See [**mdast**][mdast-util] for a list of utilities for working with the syntax
+See [mdast][mdast-util] for a list of utilities that work with the syntax
 tree.
-See [`unist`][unist-util] for other utilities which work with **mdast**
-nodes, too.
-Finally, see [**vfile**][vfile-util] for a list of utilities working with
-virtual files.
+See [unist][unist-util] for other utilities which work with **mdast** and other
+syntax trees too.
+Finally, see [vfile][vfile-util] for a list of utilities working with virtual
+files.
 
-## Using plugins
+## Use plugins
 
 To use a plugin programmatically, call the [`use()`][unified-use] function.
 
 To use plugin with `remark-cli`, pass a [`--use` flag][unified-args-use] or
 specify it in a [configuration file][config-file-use].
 
-## Creating plugins
-
-Have an idea for a plugin?
-Post it in [ideas][] and make it happen!
+## Create plugins
 
 To create a plugin, first read up on the [concept of plugins][unified-plugins].
 Then, read the [guide on “Creating a plugin with unified”][guide].
 Finally, take one of existing plugins, which looks similar to what you’re about
 to make, and work from there.
-If you get stuck, [ideas][], [issues][], and [discussions][] are good places to
-get help.
-
-You should pick a name prefixed by `'remark-'`, such as `remark-lint`.
+If you get stuck, [discussions][] is a good place to get help.
 
+You should pick a name prefixed by `'remark-'` (such as `remark-lint`).
 **Do not use the `remark-` prefix** if the thing you create doesn’t work with
 `remark().use()`: it isn’t a “plugin” and will confuse users.
 If it works with mdast, use `'mdast-util-'`, if it works with any unist tree,
 use `unist-util-`, and if it works with virtual files, use `vfile-`.
 
+Use default exports to expose plugins from your packages, add `remark-plugin`
+keywords in `package.json`, and add a `remark-plugin` to your repo on GitHub.
+
 <!--Definitions:-->
 
 [logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
 
+[d]: https://github.com/remarkjs/remark-directive
+
+[remark]: https://github.com/remarkjs/remark
+
+[awesome-remark]: https://github.com/remarkjs/awesome-remark
+
+[topic]: https://github.com/topics/remark-plugin
+
+[github-preset-search]: https://github.com/topics/remark-preset
+
 [mdast-util]: https://github.com/syntax-tree/mdast#list-of-utilities
 
 [unist-util]: https://github.com/syntax-tree/unist#unist-utilities
@@ -328,26 +336,8 @@ use `unist-util-`, and if it works with virtual files, use `vfile-`.
 
 [unified-plugins]: https://github.com/unifiedjs/unified#plugin
 
-[issues]: https://github.com/remarkjs/remark/issues
-
-[discussions]: https://github.com/remarkjs/remark/discussions
-
 [guide]: https://unifiedjs.com/learn/guide/create-a-plugin/
 
-[npm-preset-search]: https://www.npmjs.com/search?q=remark-preset
-
-[github-preset-search]: https://github.com/topics/remark-preset
-
-[awesome]: https://github.com/remarkjs/awesome
-
-[ideas]: https://github.com/remarkjs/ideas
-
-[topic]: https://github.com/topics/remark-plugin
-
-[unified]: https://github.com/unifiedjs/unified
-
-[collective]: https://opencollective.com/unified
-
-[create]: #creating-plugins
+[discussions]: https://github.com/remarkjs/remark/discussions
 
-[d]: https://github.com/remarkjs/remark-directive
+[rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins