https://github.com/gdiasag/djotter
Shallow Ruby wrapper for the jotdown (Djot parser) Rust crate
https://github.com/gdiasag/djotter
djot html jotdown ruby
Last synced: 5 days ago
JSON representation
Shallow Ruby wrapper for the jotdown (Djot parser) Rust crate
- Host: GitHub
- URL: https://github.com/gdiasag/djotter
- Owner: gdiasag
- License: mit
- Created: 2025-08-12T23:47:08.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-15T18:59:25.000Z (11 months ago)
- Last Synced: 2026-06-09T17:07:02.741Z (18 days ago)
- Topics: djot, html, jotdown, ruby
- Language: Ruby
- Homepage:
- Size: 25.4 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-djot - gdiasag/djotter - Ruby wrapper for the jotdown Rust crate. (Parsers & Libraries / Ruby)
README
# Djotter
[](https://github.com/gustavodiasag/djotter/actions/workflows/ci.yml)
[](https://badge.fury.io/rb/djotter)
Ruby wrapper for Rust's [jotdown][djot-rs] crate.
Initially, djotter is designed to strictly generate HTML from a Djot document. The gem does not support features such as manipulating the AST generated by the underlying parser and the conversion of such intermediate representation to construct any type of output format other than HTML.
> [!NOTE]
> Even though `jotdown` aims to be feature complete and match the [reference implementation][djot-js], some edge cases are not yet dealt with. Since this wrapper mirrors the crate behavior, it is important to draw attention to that.
>
> For more information, see [the documentation below](#correctness)
[djot-rs]: https://github.com/hellux/jotdown
[djot-js]: https://github.com/jgm/djot.js
## Installation
Add this line to your application's Gemfile:
gem 'djotter'
and then execute:
$ bundle
Or install it yourself as:
$ gem install djotter
## Usage
This gem expects to receive UTF-8 strings. Ensure your strings are the right encoding before passing them into `Djotter`.
### Converting to HTML
Call `to_html` on a string to convert it to HTML:
```ruby
require 'djotter'
puts Djotter.to_html('a *b{#id key="*"}*')
#
a b
```
### Correctness
Even though the underlying implementation supports all the current features of the Djot syntax, the authors explicitly state that:
> The HTML output is in some cases not exactly identical to the reference implementation.
Taking that into consideration, the test cases against which the crate is submitted to are not as exhaustive as the [JavaScript][djot-js] and [Lua][djot-lua] versions. To address that, all the `.test` files from those parsers were [added][test-cases] to this wrapper for an extra layer of inspection. With that said, not all cases matched exactly the expected output, some just because of formatting shenanigans and others due to not completely handling edge cases. The exact cases where that happened were edited out.
Some of those are actually pointed out by the crate author, such as [issue #51][issue-51].
[djot-lua]: https://github.com/jgm/djot.lua
[test-cases]: ./spec/cases/
[issue-51]: https://github.com/hellux/jotdown/issues/51
## Development
After cloning the repo:
$ bundle install
$ bundle exec rake compile
If there were no errors, that's it! Otherwise, make sure you have all the tools required for both Ruby and Rust: `bundle`, `cargo`.
## Contributing
Issues, bug reports and pull requests are welcome.