From f4d8aee4cc3764bd009d15f8eb8943fef95a347f Mon Sep 17 00:00:00 2001
From: Noah Hellman <noah@hllmn.net>
Date: Sun, 5 Feb 2023 12:38:18 +0100
Subject: [PATCH] add README.md

---
 README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b4caf76
--- /dev/null
+++ b/README.md
@@ -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.