Skip to content

Commit

Permalink
Refactor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Sep 20, 2023
1 parent 57b2aaf commit 0d4bef1
Showing 1 changed file with 75 additions and 62 deletions.
137 changes: 75 additions & 62 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,9 @@
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(remarkImages[, options])`](#unifieduseremarkimages-options)
* [`defaultImageExtensions`](#defaultimageextensions)
* [`unified().use(remarkImages[, options])`](#unifieduseremarkimages-options)
* [`Options`](#options)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
Expand All @@ -32,28 +33,22 @@

This package is a [unified][] ([remark][]) plugin to add a simpler image syntax.

**unified** is a project that transforms content with abstract syntax trees
(ASTs).
**remark** adds support for markdown to unified.
**mdast** is the markdown AST that remark uses.
This is a remark plugin that transforms mdast.

## When should I use this?

Images are [notoriously unintuitive][tweet] in markdown.
This projects adds a different way to include images: by pasting in a URL or
path to them (such as `./image.jpg`).
The behavior added by this plugin is nice when you’re authoring your own
markdown and are sure that you’re explaining what happens in images in
surrounding prose.
surrounding prose (as you can’t add alt text with this).

Another plugin, [`remark-unwrap-images`][remark-unwrap-images], could be useful
to unwrap images on their own in a paragraph.

## Install

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

```sh
npm install remark-images
Expand All @@ -78,67 +73,71 @@ In browsers with [`esm.sh`][esmsh]:
Say we have the following file `example.md`:

```markdown
Below will render an image:
Original plates from Clyde Tombaugh’s discovery of Pluto:

https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg
https://upload.wikimedia.org/wikipedia/en/c/c6/Pluto_discovery_plates.png
```

And our module `example.js` looks as follows:
…and a module `example.js`:

```js
import {read} from 'to-vfile'
import {remark} from 'remark'
import remarkImages from 'remark-images'
import {read} from 'to-vfile'

main()

async function main() {
const file = await remark()
.use(remarkImages)
.process(await read('example.md'))
const file = await remark()
.use(remarkImages)
.process(await read('example.md'))

console.log(String(file))
}
console.log(String(file))
```

Now, running `node example` yields:
…then running `node example.js` yields:

```markdown
Below will render an image:
Original plates from Clyde Tombaugh’s discovery of Pluto:

[![](https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg)](https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg)
[![](https://upload.wikimedia.org/wikipedia/en/c/c6/Pluto_discovery_plates.png)](https://upload.wikimedia.org/wikipedia/en/c/c6/Pluto_discovery_plates.png)
```

## API

This package exports the identifier `defaultImageExtensions`.
The default export is `remarkImages`.
This package exports the identifier
[`defaultImageExtensions`][api-default-image-extensions].
The default export is [`remarkImages`][api-remark-images].

### `defaultImageExtensions`

Extensions recognized as images by default (`Array<string>`).
Currently `['avif', 'gif', 'jpeg', 'jpg', 'png', 'svg', 'webp']`.

### `unified().use(remarkImages[, options])`

Plugin to add a simpler image syntax.
Transform URLs in text that reference images (see `defaultImageExtensions`) to
images.
Add a simpler image syntax.

##### `options`
###### Parameters

Configuration (optional).
* `options` ([`Options`][api-options], optional)
— configuration

###### `options.imageExtensions`
###### Returns

List of file extensions recognized as images (`Array<string>?`, default
[`defaultImageExtensions`](#defaultimageextensions)).
Transform ([`Transformer`][unified-transformer]).

### `defaultImageExtensions`
### `Options`

Configuration (TypeScript type).

List of file extensions recognized as an image by default (constant
`['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']`).
Note: extension does not include `.`, only the extension name.
###### Fields

* `imageExtensions` (`Array<string>`, default:
[`defaultImageExtensions`][api-default-image-extensions])
— file extensions (without dot) to treat as images

## Syntax

This plugin looks for URLs and paths, on their own, that end in an image
extension (see `defaultImageExtensions`).
extension.
If they occur inside a link already, then only an image is created.
If they instead do not occur in a link, the image is also linked.

Expand All @@ -151,22 +150,25 @@ Some examples of URLs and paths are:

## Syntax tree

This plugin adds mdast [`Image`][image] and [`Link`][link] nodes to the syntax
tree.
This plugin adds mdast [`Image`][mdast-image] and [`Link`][mdast-link] nodes to
the syntax tree.
These are the same nodes that represent images through `![](url)` and links
through `[text](url)` syntax.

## Types

This package is fully typed with [TypeScript][].
There are no extra exported types.
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
Projects maintained by the unified collective are compatible with 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.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-images@^3`,
compatible with Node.js 12.

This plugin works with `unified` version 3+ and `remark` version 4+.

Expand All @@ -175,16 +177,17 @@ This plugin works with `unified` version 3+ and `remark` version 4+.
Although this plugin should be safe to use, always be careful with user input.
For example, it’s possible to hide JavaScript inside images (such as GIFs,
WebPs, and SVGs).
User provided images open you up to a [cross-site scripting (XSS)][xss] attack.
User provided images open you up to a [cross-site scripting (XSS)][wiki-xss]
attack.

This may become a problem if the markdown later transformed to
**[rehype][]** (**[hast][]**) or opened in an unsafe markdown viewer.

## Related

* [`remarkjs/remark-unwrap-images`][remark-unwrap-images]
* [`remark-unwrap-images`][remark-unwrap-images]
— remove the wrapping paragraph for images
* [`remarkjs/remark-embed-images`](https://github.com/remarkjs/remark-embed-images)
* [`remark-embed-images`](https://github.com/remarkjs/remark-embed-images)
— embed local images as data URIs

## Contribute
Expand Down Expand Up @@ -215,9 +218,9 @@ abide by its terms.

[downloads]: https://www.npmjs.com/package/remark-images

[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-images.svg
[size-badge]: https://img.shields.io/bundlejs/size/remark-images

[size]: https://bundlephobia.com/result?p=remark-images
[size]: https://bundlejs.com/?q=remark-images

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

Expand All @@ -231,36 +234,46 @@ abide by its terms.

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

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

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

[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://johno.com

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

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

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

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

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

[unified]: https://github.com/unifiedjs/unified
[remark-unwrap-images]: https://github.com/remarkjs/remark-unwrap-images

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[tweet]: https://twitter.com/gruber/status/1246489863932821512

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

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

[hast]: https://github.com/syntax-tree/hast
[unified-transformer]: https://github.com/unifiedjs/unified#transformer

[tweet]: https://twitter.com/gruber/status/1246489863932821512
[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[remark-unwrap-images]: https://github.com/remarkjs/remark-unwrap-images
[api-default-image-extensions]: #defaultimageextensions

[image]: https://github.com/syntax-tree/mdast#image
[api-options]: #options

[link]: https://github.com/syntax-tree/mdast#link
[api-remark-images]: #unifieduseremarkimages-options

0 comments on commit 0d4bef1

Please sign in to comment.