https://github.com/frantic1048/est

[CONSTRUCTING] reStructuredText parser and renderer.
https://github.com/frantic1048/est

pegjs resturcturedtext

Last synced: 10 days ago
JSON representation

[CONSTRUCTING] reStructuredText parser and renderer.

• Host: GitHub
• URL: https://github.com/frantic1048/est
• Owner: frantic1048
• License: gpl-3.0
• Created: 2017-05-25T19:49:17.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2018-08-29T17:50:24.000Z (about 6 years ago)
• Last Synced: 2024-10-27T19:46:36.321Z (11 days ago)
• Topics: pegjs, resturcturedtext
• Language: JavaScript
• Homepage:
• Size: 244 KB
• Stars: 10
• Watchers: 7
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
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 `_