reasciidoc-parse

reasciidoc plugin to add support for parsing from AsciiDoc.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(reasciidocParse)
• Examples
  • Example: support AsciiDoc extensions
  • Example: turning AsciiDoc into HTML
• Syntax
• Syntax tree
• Types
• Compatibility
• Security
• Contribute
• License

What is this?

This package is a unified (reasciidoc) plugin that defines how to take AsciiDoc as input and turn it into a syntax tree.

See the monorepo readme for info on what the reasciidoc ecosystem is.

When should I use this?

This plugin adds support to unified for parsing AsciiDoc. If you also need to serialize AsciiDoc, you can alternatively use reasciidoc, which combines unified, this plugin, and reasciidoc-stringify.

If you just want to turn AsciiDoc into HTML (with maybe a few extensions), we recommend using this plugin with rehype-stringify. If you don't use plugins and want to access the syntax tree, you can directly use this package. reasciidoc focusses on making it easier to transform content by abstracting these internals away.

You can combine this plugin with other plugins to add syntax extensions. You can use any reasciidoc plugin after reasciidoc-parse.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install reasciidoc-parse

In Deno with esm.sh:

import reasciidocParse from 'https://esm.sh/reasciidoc-parse@1'

In browsers with esm.sh:

<script type="module">
  import reasciidocParse from 'https://esm.sh/reasciidoc-parse@1?bundle'
</script>

Use

Say we have the following module example.js:

import rehypeStringify from 'rehype-stringify'
import reasciidocParse from 'reasciidoc-parse'
import rehypeFromAsciiDoc from 'rehype-from-asciidoc'
import {unified} from 'unified'

const value = `
= Mercury

*Mercury* is the first planet from the https://en.wikipedia.org/wiki/Sun[Sun]
and the smallest planet in the Solar System.
`

const file = await unified()
  .use(reasciidocParse)
  .use(rehypeFromAsciiDoc)
  .use(rehypeStringify)
  .process(value)

console.log(String(file))

…then running node example.js yields:

<h1>Mercury</h1>
<p><strong>Mercury</strong> is the first planet from the <a href="https://en.wikipedia.org/wiki/Sun">Sun</a>
and the smallest planet in the Solar System.</p>

API

This package exports no identifiers. The default export is reasciidocParse.

unified().use(reasciidocParse)

Add support for parsing from AsciiDoc.

Parameters

There are no parameters.

Returns

Nothing (undefined).

Examples

Example: support AsciiDoc extensions

We support standard AsciiDoc by default. Non-standard AsciiDoc extensions can be enabled with plugins.

This example shows how to parse AsciiDoc with various features:

import rehypeStringify from 'rehype-stringify'
import reasciidocParse from 'reasciidoc-parse'
import rehypeFromAsciiDoc from 'rehype-from-asciidoc'
import {unified} from 'unified'

const doc = `
= My Document

== Section One

Hello *world* and https://example.com[links].

[source,javascript]
----
const x = 42
----
`

const file = await unified()
  .use(reasciidocParse)
  .use(rehypeFromAsciiDoc)
  .use(rehypeStringify)
  .process(doc)

console.log(String(file))

Yields:

<div class="sect1">
<h2 id="_my_document">My Document</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_section_one">Section One</h3>
<div class="paragraph">
<p>Hello <strong>world</strong> and <a href="https://example.com">links</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-javascript">const x = 42</code></pre>
</div>
</div>
</div>
</div>
</div>

Example: turning AsciiDoc into HTML

This example shows how to turn AsciiDoc into HTML by using unified with reasciidoc-parse and rehype-stringify:

import rehypeStringify from 'rehype-stringify'
import reasciidocParse from 'reasciidoc-parse'
import rehypeFromAsciiDoc from 'rehype-from-asciidoc'
import {unified} from 'unified'

const doc = `
= Saturn's Moon

Titan is the largest moon of Saturn and has a thick atmosphere.
`

const file = await unified()
  .use(reasciidocParse)
  .use(rehypeFromAsciiDoc)
  .use(rehypeStringify)
  .process(doc)

console.log(String(file))

Yields:

<div class="doc">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Titan is the largest moon of Saturn and has a thick atmosphere.</p>
</div>
</div>
</div>
</div>

Syntax

AsciiDoc is parsed according to the AsciiDoc specification. Other plugins can add support for syntax extensions. If you're interested in extending AsciiDoc, see the AsciiDoc Language Documentation.

Syntax tree

The syntax tree used in reasciidoc is adast.

Types

This package is fully typed with TypeScript. It exports the additional type Options (which is currently empty).

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

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, reasciidoc-parse@1, compatible with Node.js 16.

Security

See § Security in asciidoc-js/reasciidoc.

Contribute

See contributing.md in asciidoc-js/.github for ways to get started.

License

MIT © AsciiDoc.js contributors