Skip to content

Commit

Permalink
Refactor prose
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jun 16, 2019
1 parent 12ceeb4 commit b7a9bcd
Showing 1 changed file with 66 additions and 53 deletions.
119 changes: 66 additions & 53 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,27 +3,28 @@
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Chat][chat-badge]][chat]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

Compile markdown to HTML with [**remark**][remark].
[**remark**][remark] plugin to compile Markdown to HTML.

> :warning: This package essentially packs [`remark-rehype`][remark2rehype] and
> ⚠️ This package essentially packs [`remark-rehype`][remark2rehype] and
> [`rehype-stringify`][rehype-stringify], and although it does support some
> customisation, it isn’t very pluggable. It’s probably smarter to use
> `remark-rehype` directly and benefit from the [**rehype**][rehype]
> ecosystem.
> customisation, it isn’t very pluggable.
> It’s probably smarter to use `remark-rehype` directly and benefit from the
> [**rehype**][rehype] ecosystem.
## Installation
## Install

[npm][]:

```bash
```sh
npm install remark-html
```

## Usage
## Use

Say we have the following file, `example.md`:

Expand All @@ -37,7 +38,7 @@ Say we have the following file, `example.md`:

And our script, `example.js`, looks as follows:

```javascript
```js
var fs = require('fs')
var unified = require('unified')
var markdown = require('remark-parse')
Expand Down Expand Up @@ -66,7 +67,9 @@ Now, running `node example` yields:

## API

### `remark.use(html[, options])`
### `remark().use(html[, options])`

Compile Markdown to HTML.

##### `options`

Expand All @@ -83,13 +86,13 @@ If `true` or an `object`, sanitation is done by [`hast-util-sanitize`][sanitize]
If an object is passed in, it’s given as a schema to `hast-util-sanitize`.
If `true`, input is sanitised according to [GitHub’s sanitation rules][github].

> Note that raw HTML in markdown cannot be sanitized, so it’s removed.
> Note that raw HTML in Markdown cannot be sanitized, so it’s removed.
> A schema can still be used to allow certain values from [integrations][]
> though.
> To support HTML in markdown, use [`rehype-raw`][raw].
> To support HTML in Markdown, use [`rehype-raw`][raw].
For example, to add strict sanitation but allowing `className`s, use
something like:
For example, to add strict sanitation but allowing `className`s, use something
like:

```js
// ...
Expand All @@ -105,13 +108,13 @@ remark()

## CommonMark

> You still need to set `commonmark: true` in
> [`remark-parse`s options][remark-options].
> You still need to set `commonmark: true` in [`remark-parse`s
> options][remark-options].
[CommonMark][] support is a goal but not (yet) a necessity. There are
some (roughly 115 of 550, relating to inline precedence, lists, emphasis
and importance) issues which I’d like to cover in the future. Note that
this sounds like a lot, but they have to do with obscure differences
[CommonMark][] support is a goal but not (yet) a necessity.
There are some (roughly 115 of 550, relating to inline precedence, lists,
emphasis and importance) issues which I’d like to cover in the future.
Note that this sounds like a lot, but they have to do with obscure differences
which do not often occur in the real world.

## Integrations
Expand All @@ -129,24 +132,24 @@ which do not often occur in the real world.
* [`remark-html-katex`](https://github.com/rokt33r/remark-math/blob/master/packages/remark-html-katex/readme.md)
— Transform math to HTML with KaTeX
* [`remark-math`](https://github.com/rokt33r/remark-math)
— Math support for markdown (inline and block)
— Math support for Markdown (inline and block)
* [`remark-midas`](https://github.com/ben-eb/remark-midas)
— Highlight CSS code with [midas](https://github.com/ben-eb/midas)
* [`remark-toc`](https://github.com/remarkjs/remark-toc)
— Generate a Tables of Contents
* ...and [more][remark-plugins]

All [**mdast** nodes][mdast] can be compiled to HTML. Unknown **MDAST**
nodes are compiled to `div` nodes if they have `children` or `text` nodes
if they have `value`.
All [**mdast** nodes][mdast] can be compiled to HTML.
Unknown **mdast** nodes are compiled to `div` nodes if they have `children` or
`text` nodes if they have `value`.

In addition, **remark-html** can be told how to compile nodes through
three `data` properties ([more information][to-hast]):

* `hName` — Tag-name to compile as
* `hChildren` — HTML content to add (instead of `children` and `value`),
in [`hast`][hast]
* `hProperties` — Map of attributes to add
* `hName` — Tag name to compile as
* `hChildren` — HTML content to add (instead of `children` and `value`), in
[`hast`][hast]
* `hProperties` — Map of properties to add

For example, the following node:

Expand All @@ -158,31 +161,33 @@ For example, the following node:
hProperties: {className: 'foo'},
hChildren: [{type: 'text', value: 'bar'}]
},
children: [{type: 'text', value: 'baz',}]
children: [{type: 'text', value: 'baz'}]
}
```

...would yield:
…would yield:

```markdown
<i class="foo">bar</i>
```

## Contribute

See [`contributing.md` in `remarkjs/remark`][contributing] for ways to get
started.
See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This organisation has a [Code of Conduct][coc]. By interacting with this
repository, organisation, or community you agree to abide by its terms.
This project has a [Code of Conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://img.shields.io/travis/remarkjs/remark-html.svg
[build-badge]: https://img.shields.io/travis/remarkjs/remark-html/master.svg

[build]: https://travis-ci.org/remarkjs/remark-html

Expand All @@ -194,52 +199,60 @@ repository, organisation, or community you agree to abide by its terms.

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

[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-html.svg

[chat]: https://spectrum.chat/unified/remark
[size]: https://bundlephobia.com/result?p=remark-html

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

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

[collective]: https://opencollective.com/unified

[license]: license
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg

[author]: https://wooorm.com
[chat]: https://spectrum.chat/unified/remark

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

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

[remark-options]: https://github.com/remarkjs/remark/tree/master/packages/remark-parse#options
[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md

[commonmark]: https://commonmark.org
[support]: https://github.com/remarkjs/.github/blob/master/support.md

[remark-plugins]: https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins
[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md

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

[to-html]: https://github.com/syntax-tree/hast-util-to-html
[author]: https://wooorm.com

[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
[remark]: https://github.com/remarkjs/remark

[github]: https://github.com/syntax-tree/hast-util-sanitize#schema
[remark-options]: https://github.com/remarkjs/remark/tree/master/packages/remark-parse#options

[to-hast]: https://github.com/syntax-tree/mdast-util-to-hast#note
[remark-plugins]: https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins

[remark2rehype]: https://github.com/remarkjs/remark-rehype

[rehype-stringify]: https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify

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

[rehype-stringify]: https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify

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

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

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

[contributing]: https://github.com/remarkjs/remark/blob/master/contributing.md
[to-html]: https://github.com/syntax-tree/hast-util-to-html

[coc]: https://github.com/remarkjs/remark/blob/master/code-of-conduct.md
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[github]: https://github.com/syntax-tree/hast-util-sanitize#schema

[to-hast]: https://github.com/syntax-tree/mdast-util-to-hast#note

[commonmark]: https://commonmark.org

[integrations]: #integrations

0 comments on commit b7a9bcd

Please sign in to comment.