@frantic1048/est

Est
=========
|license|_ |code quality|_ |ci|_ |dm|_

.. |license| image:: https://img.shields.io/github/license/frantic1048/est.svg?style=flat-square
.. _license: https://github.com/frantic1048/est/blob/master/LICENSE
.. |code quality| image:: https://img.shields.io/codacy/grade/3aa60448106f4001b7ac194829f98397.svg?style=flat-square
.. _code quality: https://www.codacy.com/app/frantic1048/Est/dashboard
.. |ci| image:: https://img.shields.io/travis/frantic1048/Est.svg?style=flat-square
.. _ci: https://travis-ci.org/frantic1048/Est
.. |dm| image:: https://img.shields.io/david/frantic1048/Est.svg?style=flat-square
.. _dm: https://david-dm.org/frantic1048/Est

reStructuredText parser and renderer.

Install
=========

Use yarn to fetch the package, or npm if you prefer.

.. code:: sh

yarn add @frantic1048/Est

Usage
=========

After build:

.. code:: js

// do not forget the `@frantic1048 scope
import est from '@frantic1048/Est'

// directly render rST into HTML string
const html = est.rst2html('reStructuredText string...')


// or...?
// welcome to the dark side...

// generate parsing tree
// which is an ASTy instance
const parse_t = est.parse('reStructuredText string...')

// transfrom parsing tree into doc tree
// which is an ASTy instance
const doc_t = est.transfrom(parse_t)

// render the doc tree into HTML string
const html_the_harder_way = est.render(doc_t)

All node types of the parsed tree can be found from est.TokenTypes .

.. _ASTy: https://github.com/rse/asty

The node structure of a specific markup could be referred in test/grammar..js

Render function is under constructing.

Build
=========

Prepare:

.. code:: sh

# fetch source code
git clone https://github.com/frantic1048/Est.git

# fetch dependencies
yarn


Build and run test:

.. code:: sh

yarn ci


Production build:

.. code:: sh

yarn dist


Develop:

.. code:: sh

yarn dev

The build output is under lib folder. All possible files are:

:est.dev.js: trace on, CommonJS module, debug and develop oriented.
:est.min.js: trace off, single variable, Browser oriented.
:est.js: trace off, CommonJS module, Node.js oriented.

Recognized Markups
==================

:Inline:

- emphasis _
- strong emphasis _
- interpreted text _
- inline literal _
- hyperlink reference _
- substitution reference _
- inline internal target _
- standalone hyperlink _

URI is refer to RFC 3986 _ 's absolute-URI definition, no scheme restriction.

Email address is a simplified subset of URI. See TextEmailAdress rule in src/parser.pegjs


:Block-level:

- section _

Unlike adorment line should be longer than title text in spec, section adornment length > 3 is accepted length.

- transition _
- paragraph _
- bullet list _

fixed 2 spaces indent.

- enumerated list _

the text immediately after the enumerator determines the indentation (same as spec).

- definition list _

fixed 4 spaces indent.

- field list _
- option list _
- footnote _

standalone hyperlink is not recognized in field name, while the other inline markups is recognized.

- citation _
- hyperlink target _
- directive _
- substitution definition `_