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
• 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:

echo '# Hello, world!' | gemrendr --no-preamble -O - -

results in the following markup:

<h1>Hello, world!</h1>

Installation

Package repository (cargo)

=> https://www.rust-lang.org/tools/install First, ensure cargo is installed.

Then run the following:

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:

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:

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:

[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.