# gemrendr
A specful Gemtext parser that turns Gemtext into idiomatic HTML fragments.
This project is designed mainly for use with Forgejo's pluggable markup system. For now, only stdin/stdout are supported. File I/O may come later.
## Features
* Support for `no_std` environments (library only)
* Receive Gemtext via stdin
* Output HTML via stdout
* Text lines are shown as regular HTML paragraphs (with the presence or absence of empty lines rendered verbatim)
* Empty text lines may be rendered using either `<br>` or `<p></p>` tags
* Link lines are clickable as regular HTML anchors, showing their label text in place of their link URI where given
* Heading lines are rendered as regular HTML headings, up to <h3>
* List item lines are rendered in a regular HTML unordered list
* Quote lines are rendered as individual HTML blockquotes
* Preformat toggle lines cause text in between them to be rendered in plaintext
* Preformatted blocks may include a button to copy their contents to the user's clipboard (only works on Forgejo so far)
## Planned Features
* Each link has an icon to make clear the kind of link presented, similar to Lagrange's render
* The alt text portion of the starting preformat toggle is shown to screen readers before the contents
* Preformatted blocks include syntax highlighting appropriate to the language specified in the block's alt text, if known
* A REPL (Read-eval-print loop) interface
## Example
This command:
```sh
echo '# Hello, world!' | gemrendr --no-preamble -O - -
```
results in the following markup:
```html
<h1>Hello, world!</h1>
```
## Installation
### Package repository (cargo)
=> https://www.rust-lang.org/tools/install First, ensure `cargo` is installed.
Then run the following:
```sh
cargo install --index sparse+https://git.average.name/api/packages/AverageHelper/cargo/ gemrendr
```
After the build, the gemrendr binary should be installed on your system and ready to use.
### Build from source
=> https://www.rust-lang.org/tools/install First, ensure `cargo` is installed.
Then clone the repo, and run the following:
```sh
cargo install --path .
```
After the build, the gemrendr binary should be installed on your system and ready to use.
## Usage
### As CLI binary
Take Gemtext from stdin and print HTML to stdout:
```sh
gemrendr --out-file=- -
```
Use `gemrendr --help` for more information.
### As a Forgejo external markup tool
=> https://forgejo.org/docs/latest/admin/config-cheat-sheet/#markup-markup doc
Add the following to your `app.ini` file:
```ini
[markup.gemtext]
ENABLED = true
NEED_POSTPROCESS = true
FILE_EXTENSIONS = .gmi,.gmni,.gemini
RENDER_COMMAND = "gemrendr --out-file=- -"
IS_INPUT_FILE = false
```
If you're using a Docker setup, be sure to link the gemrendr binary to the container's `/usr/bin/gemrendr`.
### As a library
This crate may be imported into Rust projects using `cargo add gemrendr`.
=> https://docs.rs/gemrendr/ See our docs page for more information.
### Support for no_std (library only)
When used as a library, this project does not require the use of `std` features, only `core` and `alloc`. To enable `no_std` support, use `--no-default-features` when adding the crate, or set `default-features = false` in your Cargo.toml file.
## Contributing
All kinds of contributions are accepted, including reporting bugs via Issues and submitting code changes via Pull Requests.
=> https://git.average.name/AverageHelper/gemrendr/issues/ Issues
=> https://git.average.name/AverageHelper/gemrendr/pulls/ Pull Requests
### Testing
While writing code for this project, consider running unit tests on your own machine periodically. Use `cargo test` for quick tests, and `./test.sh` to test code coverage.