add README.md

This commit is contained in:
Noah Hellman 2023-02-05 12:38:18 +01:00
parent 83eebf369d
commit f4d8aee4cc

127
README.md Normal file
View file

@ -0,0 +1,127 @@
# Jotdown
Jotdown is a pull parser Rust library for the [Djot][djot] markup language. It
parses a Djot document into a sequence of events and may also render the events
to HTML.
Jotdown aims to be fast and efficient, using a minimal number of allocations.
The API should use idiomatic Rust and be easy to use and flexible. The event
interface allows clients to e.g. construct an AST or generate any type of
output format. It also allows one to perform filters on the document before
generating the output. Jotdown aims to be feature complete and match the
[syntax reference][djot-syntax] and the [reference implementation][djot-js] in
terms of output.
Another goal is to keep the implementation minimal and build times low. The
current implementation has zero dependencies, if major non-essential features
are added or larger dependencies are utilized, these should be optional using
feature flags.
Jotdown supports Rust edition 2021, i.e. Rust 1.56 and above.
[djot]: https://djot.net
[djot-syntax]: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html
[djot-js]: https://github.com/jgm/djot.js
## Usage
Jotdown is primarily a parsing library but also has a minimal CLI
implementation and a simple online demo version.
### Library
The Jotdown API is inspired by [pulldown-cmark] and is overall very similar.
The Jotdown crate contains in-source documentation, a rendered version is
available at <https://docs.rs/jotdown>.
While Jotdown is usable, it is still in early development and breaking changes
to the API may occur frequently. The Djot syntax is also in quite early stages
and may also change significantly.
[pulldown-cmark]: https://github.com/raphlinus/pulldown-cmark
### CLI
The Jotdown crate contains a minimal implementation of a CLI that simply reads
from standard input and writes HTML to standard output. It can be built from
this repository and run locally with cargo:
```
$ cargo build --release
$ echo "hello world" | ./target/release/djot
<p>hello world</p>
```
Alternatively, it can be installed from the crates.io repository using simply:
```
$ cargo install jotdown
```
It will be placed in `~/.cargo/bin/jotdown`.
### Web demo
A version of Jotdown compiled to WebAssembly and runnable in a web browser is
available at <https://hllmn.net/projects/jotdown/demo>. It can also be run
locally:
```
$ cd examples/jotdown_wasm
$ make run
```
You may need to install [wasm-pack] and make sure your Rust compiler has the
WebAssembly backend.
[wasm-pack]: https://rustwasm.github.io/wasm-pack/
## Status
As of writing, Jotdown implements all the current features of the Djot syntax,
including:
- links, images, either inline or with reference link definitions,
- autolinks,
- inline typesetting
- emphasis,
- highlight,
- super/subscript,
- insert/delete,
- smart punctuation,
- inline verbatim, code and code blocks,
- math,
- line breaks,
- comments,
- symbols,
- headings, including hierarchical sections, and automatic links
- block quotes,
- lists,
- unordered,
- ordered,
- task,
- definitions,
- raw inline and blocks,
- thematic breaks,
- pipe tables,
- attributes, on inline and block elements,
- inline spans and div blocks,
- footnotes.
The HTML output is in some cases not exactly identical to the [reference
implementation][djot-js]. There are two test suites that compares Jotdown with
the reference implementation. One uses the unit tests of the reference
implementation and runs them with Jotdown. It can be run with:
```
$ make suite
```
Another target uses the reference implementation to generate html output for
its benchmark files and compares it to the output of Jotdown:
```
$ make suite_bench
```
Note that it requires node in order to run the reference implementation.