…
+``` + +And we’d like to turn that into: + +```html +…
+``` + +In the next step we’ll write the code to use our plugin. + +### Setting up + +Let’s set up a project. +Create a folder, `example`, enter it, and initialize a new project: + +```sh +mkdir example +cd example +npm init -y +``` + +Then make sure the project is a module, so that `import` and `export` work, +by changing `package.json`: + +```diff +--- a/package.json ++++ b/package.json +@@ -1,6 +1,7 @@ + { + "name": "example", + "version": "1.0.0", ++ "type": "module", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" +``` + +Make sure `input.html` exists with: + +```html +…
+``` + +Now, let’s create an `example.js` file that will process our file and report +any found problems. + +```js twoslash +// @filename: plugin.d.ts +import type {Root} from 'hast' +export default function rehypeSlug(): (tree: Root) => undefined; +// @filename: example.js +///…
+``` + +That’s it! +For a complete version of this plugin, +see [`rehype-slug`][rehype-slug]. + +If you haven’t already, check out the other articles in the +[learn section][learn]! + + + +[support]: https://github.com/unifiedjs/.github/blob/main/support.md + +[hast-util-to-string]: https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-to-string + +[github-slugger]: https://github.com/Flet/github-slugger + +[visit]: https://github.com/syntax-tree/unist-util-visit + +[rehype-slug]: https://github.com/rehypejs/rehype-slug + +[learn]: /learn/ + +[use]: /learn/guide/using-unified/ diff --git a/doc/learn/create-a-remark-plugin.md b/doc/learn/create-a-remark-plugin.md new file mode 100644 index 000000000000..6c8c29c89780 --- /dev/null +++ b/doc/learn/create-a-remark-plugin.md @@ -0,0 +1,280 @@ +--- +authorGithub: wooorm +author: Titus Wormer +description: Guide that shows how to create a remark plugin +group: guide +modified: 2024-08-13 +published: 2024-08-13 +tags: + - mdast + - plugin + - remark +title: Create a remark plugin +--- + +## Create a remark plugin + +This guide shows how to create a plugin for remark that turns emoji +shortcodes ([gemoji][], such as `:+1:`) into Unicode emoji (`👍`). +It looks for a regex in the text and replaces it. + +> Stuck? +> Have an idea for another guide? +> See [`support.md`][support]. + +### Contents + +* [Case](#case) +* [Setting up](#setting-up) +* [Plugin](#plugin) + +### Case + +Before we start, let’s first outline what we want to make. +Say we have the following file: + +```markdown +Look, the moon :new_moon_with_face: +``` + +And we’d like to turn that into: + +```markdown +Look, the moon 🌚 +``` + +In the next step we’ll write the code to use our plugin. + +### Setting up + +Let’s set up a project. +Create a folder, `example`, enter it, and initialize a new project: + +```sh +mkdir example +cd example +npm init -y +``` + +Then make sure the project is a module, so that `import` and `export` work, +by changing `package.json`: + +```diff +--- a/package.json ++++ b/package.json +@@ -1,6 +1,7 @@ + { + "name": "example", + "version": "1.0.0", ++ "type": "module", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" +``` + +Make sure `input.md` exists with: + +```markdown +Look, the moon :new_moon_with_face: +``` + +Now, let’s create an `example.js` file that will process our file and report +any found problems. + +```js twoslash +// @filename: plugin.d.ts +import type {Root} from 'mdast' +export default function remarkGemoji(): (tree: Root) => undefined; +// @filename: example.js +///