Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs for newcomers #6

Merged
merged 16 commits into from
Oct 26, 2021
Merged

Update docs for newcomers #6

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
fb2237e
Remove old warning
wooorm Oct 21, 2021
98a3ce5
Add `what is this?`
wooorm Oct 21, 2021
eb3a552
Add `when should I use this?
wooorm Oct 21, 2021
aaf771a
Add Contents
wooorm Oct 21, 2021
4960846
Add wip section on examples
wooorm Oct 21, 2021
aa9c022
Reword
wooorm Oct 24, 2021
db8f642
Add examples
wooorm Oct 24, 2021
f392cf5
Add deno, browsers to install
wooorm Oct 24, 2021
44ab0d2
Add example of when not to use directives
wooorm Oct 24, 2021
8ae69ab
Update list of related projects
wooorm Oct 24, 2021
46e9c26
Update what
wooorm Oct 24, 2021
9dad415
Add syntax, syntax tree sections
wooorm Oct 24, 2021
e6b5847
Add section on types
wooorm Oct 24, 2021
58b7a42
Improve docs
wooorm Oct 24, 2021
2919ab3
Add section on compatibility
wooorm Oct 24, 2021
29ddc60
Improve sentence
wooorm Oct 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
296 changes: 252 additions & 44 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,77 @@
(`:cite[smith04]`, `::youtube[Video of a cat in a box]{v=01ab2cd3efg}`, and
such).

## Important!

This plugin is made for the new parser in remark
([`micromark`](https://github.com/micromark/micromark),
see [`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)).
Use this plugin for remark 13+.
## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(remarkDirective)`](#unifieduseremarkdirective)
* [Examples](#examples)
* [Example: YouTube](#example-youtube)
* [Example: Styled blocks](#example-styled-blocks)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin to add support for directives:
one syntax for arbitrary extensions in markdown.
You can use this with some more code to match your specific needs, to allow for
anything from callouts, citations, styled blocks, forms, embeds, spoilers, etc.

unified is an AST (abstract syntax tree) based transform project.
**remark** is everything unified that relates to markdown.
The layer under remark is called mdast, which is only concerned with syntax
trees.
Another layer underneath is micromark, which is only concerned with parsing.
This package is a small wrapper to integrate all of these.

## When should I use this?

Directives are one of the four ways to extend markdown: an arbitrary extension
syntax (see [Extending markdown](https://github.com/micromark/micromark#extending-markdown)
in micromark’s docs for the alternatives and more info).
This mechanism works well when you control the content: who authors it, what
tools handle it, and where it’s displayed.
When authors can read a guide on how to embed a tweet but are not expected to
know the ins and outs of HTML or JavaScript.
Directives don’t work well if you don’t know who authors content, what tools
handle it, and where it ends up.
Example use cases are a docs website for a project or product, or blogging tools
and static site generators.

## Install

This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.

[npm][]:
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
In Node.js (12.20+, 14.14+, 16.0+), install with [npm][]:

```sh
npm install remark-directive
```

In Deno with [Skypack][]:

```js
import remarkDirective from 'https://cdn.skypack.dev/remark-directive@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
import remarkDirective from 'https://cdn.skypack.dev/remark-directive@2?min'
</script>
```

## Use

Say we have the following file, `example.md`:
Expand All @@ -50,8 +103,7 @@ A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.
And our module, `example.js`, looks as follows:

```js
import {readSync} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {read} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkDirective from 'remark-directive'
Expand All @@ -61,23 +113,26 @@ import rehypeStringify from 'rehype-stringify'
import {visit} from 'unist-util-visit'
import {h} from 'hastscript'

const file = readSync('example.md')

unified()
.use(remarkParse)
.use(remarkDirective)
.use(customPlugin)
.use(remarkRehype)
.use(rehypeFormat)
.use(rehypeStringify)
.process(file)
.then((file) => {
console.error(reporter(file))
console.log(String(file))
})

// This plugin is just an example! You can handle directives however you please!
function customPlugin() {
main()

async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkDirective)
.use(myRemarkPlugin)
.use(remarkRehype)
.use(rehypeFormat)
.use(rehypeStringify)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sometimes the order of plugins matters (transformers) and sometimes it doesn't (syntax extensions / custom parsers / compilers). I don't think it's necessary to document here, but it might be good to document for plugins that do depend on output of other plugins.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it ever weird though? As in, do people come in thinking the order doesn’t matter?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really. If anything it can be a bit surprising things work regardless of order, not the other way around.

.process(await read('example.md'))

console.log(String(file))
}

// This plugin is an example to let users write HTML with directives.
// It’s informative but rather useless.
// See below for others examples.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure it JSDoc based type annotations should be used in examples. It's not wrong, but IMO it adds a bit of visual noise and doesn't really help to clarify the example.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe. It doesn’t hurt JS users who copy/paste (maybe a bit, as you mention, if it’s noisy).
It does boost the idea to both JS and TS users that types can come in plain JavaScript.
And it might signal to TS users how things can be typed, as they sometimes have a hard time typing unified plugins/utilities (using a lot of anys or unist.Node)?
But it’s less noisy than both JS and TS code blocks but is still copy/pastable compared to just TS code blocks.

function myRemarkPlugin() {
return (tree) => {
visit(tree, (node) => {
if (
Expand All @@ -98,12 +153,7 @@ function customPlugin() {

Now, running `node example` yields:

```txt
example.md: no issues found
```

```html
example.md: no issues found
<main id="readme">
<p>Lorem<br>ipsum.</p>
<hr class="red">
Expand All @@ -121,8 +171,163 @@ The default export is `remarkDirective`.
Configures remark so that it can parse and serialize directives.
Doesn’t handle the directives: [create your own plugin][create-plugin] to do
that.
See the [micromark extension for the syntax][syntax] and the
[mdast utility for the syntax tree][syntax-tree].

## Examples

### Example: YouTube

This example shows how directives can be used for YouTube embeds.
It’s based on the example in Use above.
If `myRemarkPlugin` was replaced with this function:

```js
// This plugin is an example to turn `::youtube` into iframes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myRemarkPlugin() {
return (tree, file) => {
visit(tree, (node) => {
if (
node.type === 'textDirective' ||
node.type === 'leafDirective' ||
node.type === 'containerDirective'
) {
if (node.name !== 'youtube') return

const data = node.data || (node.data = {})
const attributes = node.attributes || {}
const id = attributes.id

if (node.type === 'textDirective') file.fail('Text directives for `youtube` not supported', node)
if (!id) file.fail('Missing video id', node)

data.hName = 'iframe'
data.hProperties = {
src: 'https://www.youtube.com/embed/' + id,
width: 200,
height: 200,
frameBorder: 0,
allow: 'picture-in-picture',
allowFullScreen: true
}
}
})
}
}
```

…and `example.md` contains:

```markdown
# Cat videos

::youtube[Video of a cat in a box]{#01ab2cd3efg}
```

…then running `node example` yields:

```html
<h1>Cat videos</h1>
<iframe src="https://www.youtube.com/embed/01ab2cd3efg" width="200" height="200" frameborder="0" allow="picture-in-picture" allowfullscreen>Video of a cat in a box</iframe>
```

### Example: Styled blocks

Note: This is sometimes called admonitions, callouts, etc.

This example shows how directives can be used to style blocks.
It’s based on the example in Use above.
If `myRemarkPlugin` was replaced with this function:

```js
// This plugin is an example to turn `::note` into divs, passing arbitrary
// attributes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myRemarkPlugin() {
return (tree) => {
visit(tree, (node) => {
if (
node.type === 'textDirective' ||
node.type === 'leafDirective' ||
node.type === 'containerDirective'
) {
if (node.name !== 'note') return

const data = node.data || (node.data = {})
const tagName = node.type === 'textDirective' ? 'span' : 'div'

data.hName = tagName
data.hProperties = h(tagName, node.attributes).properties
}
})
}
}
```

…and `example.md` contains:

```markdown
# How to use xxx

You can use xxx.

:::note{.warning}
if you chose xxx, you should also use yyy somewhere…
:::
```

…then running `node example` yields:

```html
<h1>How to use xxx</h1>
<p>You can use xxx.</p>
<div class="warning">
<p>if you chose xxx, you should also use yyy somewhere…</p>
</div>
```

## Syntax

This plugin applies a micromark extensions to parse the syntax.
See its readme for parse details:

* [`micromark-extension-directive`](https://github.com/micromark/micromark-extension-directive#syntax)

## Syntax tree

This plugin applies one mdast utility to build and serialize the AST.
See its readme for the node types supported in the tree:

* [`mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive#syntax-tree)

## Types

This package is fully typed with [TypeScript][].
If you’re working with the syntax tree, make sure to import this plugin
somewhere in your types, as that registers the new node types in the tree.

```js
/** @typedef {import('remark-directive')} */

import {visit} from 'unist-util-visit'

/** @type {import('unified').Plugin<[], import('mdast').Root>} */
export default function myRemarkPlugin() => {
return (tree) => {
visit(tree, (node) => {
// `node` can now be one of the nodes for directives.
})
}
}
```

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified 9+ and remark 14+.

## Security

Expand All @@ -133,13 +338,14 @@ scripting (XSS)][xss] attacks.
## Related

* [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
— GFM
— support GFM (autolink literals, strikethrough, tables, tasklists)
* [`remark-github`](https://github.com/remarkjs/remark-github)
— Autolink references like in GitHub issues, PRs, and comments
— link references to commits, issues, pull-requests, and users, like on
GitHub
* [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
— Frontmatter (YAML, TOML, and more)
— support frontmatter (YAML, TOML, and more)
* [`remark-math`](https://github.com/remarkjs/remark-math)
— Math
— support math

## Contribute

Expand Down Expand Up @@ -185,6 +391,8 @@ abide by its terms.

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
Expand All @@ -197,18 +405,18 @@ abide by its terms.

[author]: https://wooorm.com

[unified]: https://github.com/unifiedjs/unified

[remark]: https://github.com/remarkjs/remark

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[typescript]: https://www.typescriptlang.org

[rehype]: https://github.com/rehypejs/rehype

[hast]: https://github.com/syntax-tree/hast

[prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444

[create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/

[syntax]: https://github.com/micromark/micromark-extension-directive#syntax

[syntax-tree]: https://github.com/syntax-tree/mdast-util-directive#syntax-tree