Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jan 30, 2023
1 parent 383c486 commit e9f3a86
Show file tree
Hide file tree
Showing 2 changed files with 152 additions and 32 deletions.
13 changes: 11 additions & 2 deletions lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,19 @@ import {track} from 'mdast-util-to-markdown/lib/util/track.js'

// To do: next major: replace `containerFlow`, `containerPhrasing`, `track`
// with `state` methods.
// To do: next major: expose functions.

const own = {}.hasOwnProperty

const shortcut = /^[^\t\n\r "#'.<=>`}]+$/

handleDirective.peek = peekDirective

/** @type {FromMarkdownExtension} */
/**
* Extension for `mdast-util-from-markdown` to enable directives.
*
* @type {FromMarkdownExtension}
*/
export const directiveFromMarkdown = {
canContainEols: ['textDirective'],
enter: {
Expand Down Expand Up @@ -77,7 +82,11 @@ export const directiveFromMarkdown = {
}
}

/** @type {ToMarkdownExtension} */
/**
* Extension for `mdast-util-to-markdown` to enable directives.
*
* @type {ToMarkdownExtension}
*/
export const directiveToMarkdown = {
unsafe: [
{
Expand Down
171 changes: 141 additions & 30 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,15 @@ such).
* [API](#api)
* [`directiveFromMarkdown`](#directivefrommarkdown)
* [`directiveToMarkdown`](#directivetomarkdown)
* [`ContainerDirective`](#containerdirective)
* [`Directive`](#directive)
* [`LeafDirective`](#leafdirective)
* [`TextDirective`](#textdirective)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Nodes](#nodes)
* [Mixin](#mixin)
* [`Directive`](#directive)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
Expand All @@ -33,23 +38,18 @@ such).

## What is this?

This package contains extensions that add support for generic directives to
[`mdast-util-from-markdown`][mdast-util-from-markdown] and
[`mdast-util-to-markdown`][mdast-util-to-markdown].

This package handles the syntax tree.
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.
[Traverse the tree][traversal] to change directives to whatever you please.
This package contains two extensions that add support for directive syntax in
markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
directives in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
directives in syntax trees to markdown).

## When to use this

These tools are all rather low-level.
In most cases, you’d want to use [`remark-directive`][remark-directive] with
remark instead.

Directives are one of the four ways to extend markdown: an arbitrary extension
syntax (see [Extending markdown][extending-mmarkdown] in micromark’s docs for
syntax (see [Extending markdown][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.
Expand All @@ -60,17 +60,29 @@ 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.

When working with `mdast-util-from-markdown`, you must combine this package with
[`micromark-extension-directive`][extension].
You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-directive`][extension].

This utility does not handle how directives are turned to HTML.
You must [traverse the tree][traversal] to change directives to whatever you
please.
When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-directive`.

All these packages are used [`remark-directive`][remark-directive], which
focusses on making it easier to transform content by abstracting these
internals away.

This package only handles the syntax tree.
For example, it does not handle how markdown is turned to HTML.
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.
[Traverse the tree][traversal] to change directives to whatever you please.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
In Node.js (version 14.14+ and 16.0+), install with [npm][]:

```sh
npm install mdast-util-directive
Expand Down Expand Up @@ -150,21 +162,99 @@ A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.

## API

This package exports the identifiers `directiveFromMarkdown` and
`directiveToMarkdown`.
This package exports the identifiers
[`directiveFromMarkdown`][api-directivefrommarkdown] and
[`directiveToMarkdown`][api-directivetomarkdown].
There is no default export.

### `directiveFromMarkdown`

Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown].
Extension for [`mdast-util-from-markdown`][mdast-util-from-markdown] to enable
directives ([`FromMarkdownExtension`][frommarkdownextension]).

### `directiveToMarkdown`

Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].
Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to enable
directives ([`ToMarkdownExtension`][tomarkdownextension]).

There are no options, but passing [`options.quote`][quote] to
`mdast-util-to-markdown` is honored for attributes.

### `ContainerDirective`

Directive in flow content (such as in the root document, or block quotes),
which contains further flow content (TypeScript type).

###### Type

```ts
import type {BlockContent, DefinitionContent, Parent} from 'mdast'

interface ContainerDirective extends Parent {
type: 'containerDirective'
name: string
attributes?: Record<string, string | null | undefined> | null | undefined
children: Array<BlockContent | DefinitionContent>
}
```

### `Directive`

The different directive nodes (TypeScript type).

###### Type

```ts
type Directive = ContainerDirective | LeafDirective | TextDirective
```
### `LeafDirective`
Directive in flow content (such as in the root document, or block quotes),
which contains nothing (TypeScript type).
###### Type
```ts
import type {PhrasingContent, Parent} from 'mdast'

interface LeafDirective extends Parent {
type: 'leafDirective'
name: string
attributes?: Record<string, string | null | undefined> | null | undefined
children: Array<PhrasingContent>
}
```

### `TextDirective`

Directive in phrasing content (such as in paragraphs, headings) (TypeScript
type).

###### Type

```ts
import type {PhrasingContent, Parent} from 'mdast'

interface TextDirective extends Parent {
type: 'textDirective'
name: string
attributes?: Record<string, string | null | undefined> | null | undefined
children: Array<PhrasingContent>
}
```

## HTML

This utility does not handle how markdown is turned to HTML.
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.
[Traverse the tree][traversal] to change directives to whatever you please.

## Syntax

See [Syntax in `micromark-extension-directive`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.
Expand Down Expand Up @@ -287,7 +377,7 @@ Yields:

### Mixin

### `Directive`
#### `Directive`

```idl
interface mixin Directive {
Expand Down Expand Up @@ -319,8 +409,9 @@ or hast).
## Types

This package is fully typed with [TypeScript][].
It exports the additional types `ContainerDirective`, `LeafDirective`,
`TextDirective`, and `Directive`.
It exports the additional types [`ContainerDirective`][api-containerdirective],
[`Directive`][api-directive], [`LeafDirective`][api-leafdirective], and
[`TextDirective`][api-textdirective].

It also registers the node types with `@types/mdast`.
If you’re working with the syntax tree, make sure to import this utility
Expand All @@ -345,7 +436,7 @@ visit(tree, (node) => {

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+.
As of now, that is Node.js 14.14+ and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with `mdast-util-from-markdown` version 1+ and
Expand Down Expand Up @@ -428,11 +519,15 @@ abide by its terms.

[quote]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsquote

[micromark]: https://github.com/micromark/micromark

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

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

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

[extending-mmarkdown]: https://github.com/micromark/micromark#extending-markdown
[extending-markdown]: https://github.com/micromark/micromark#extending-markdown

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

Expand All @@ -444,4 +539,20 @@ abide by its terms.

[dfn-phrasing-content]: https://github.com/syntax-tree/mdast#phrasingcontent

[dfn-mxn-directive]: #directive
[frommarkdownextension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[tomarkdownextension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[api-directivefrommarkdown]: #directivefrommarkdown

[api-directivetomarkdown]: #directivetomarkdown

[api-containerdirective]: #containerdirective

[api-directive]: #directive

[api-leafdirective]: #leafdirective

[api-textdirective]: #textdirective

[dfn-mxn-directive]: #directive-1

0 comments on commit e9f3a86

Please sign in to comment.