gemtext2md
Convert Gemini text (gemtext) to Markdown. This is an Erlang library
plus a command line filter built from it. The conversion follows the
Rust gemtext2md, and parsing is done by
gemini_text.
Conversion rules
| Gemtext | Markdown |
|---|---|
# , ## , ### |
same heading level |
| text line | paragraph |
=> URL label |
* [label](URL) |
=> URL (no label) |
* [URL](URL) |
* item |
- item |
> text |
> text |
| fenced block (with alt) | fenced block, alt text kept |
Consecutive links, list items or quote lines form one block. A blank
line or any other kind of line ends the block. Lines of a quote block
are separated by a bare > line, so each stays its own paragraph.
Blank lines are not otherwise reproduced; each block is followed by
one blank line.
Input must be UTF-8. Anything else is an error; transcode it first. Control characters are passed through unfiltered.
Library
Add the dependency to rebar.config:
{deps, [{gemtext2md, "~> 0.1"}]}.
Whole document:
{ok, Markdown} = gemtext2md:convert(<<"# Hello\n=> gemini://x.org X\n">>),
io:put_chars(Markdown).
convert/1 returns {ok, iodata()} or {error, Reason}. The
reason comes from gemini_text, for example invalid_utf8.
Streaming, for input that arrives in pieces (chunks may be split anywhere, including inside a line or a multibyte character):
C0 = gemtext2md:new(),
{ok, Out1, C1} = gemtext2md:convert(Chunk1, C0),
{ok, Out2, C2} = gemtext2md:convert(Chunk2, C1),
{ok, Out3} = gemtext2md:finish(C2).
Write Out1, Out2 and Out3 in order. After an error no context
is returned, so a broken stream cannot be continued. Output for a
link, list or quote group is held back until the group ends (the next
element of another kind, or finish/1); a preformatted block is
held back until its closing fence.
Escript
gemtext2md [FILE | -]
With no argument, or with -, it reads standard input; with one
argument it reads that file. Markdown goes to standard output.
$ gemtext2md page.gmi > page.md
$ curl -s gemini-proxy/page.gmi | gemtext2md
On failure it prints gemtext2md: <message> to standard error and
exits with status 1; otherwise it exits 0. It needs escript (an
Erlang/OTP install, 27 or later) on the PATH.
Building
make release
This runs rebar3 escriptize and prints the sha256 of
_build/default/bin/gemtext2md. Rebuilds of the same source give
different checksums; see CHECKSUMS.md before cutting a
release.
Using a released escript in another project's build
Pin the version and checksum, fetch once, and run it:
GEMTEXT2MD_VSN = 0.1.0
GEMTEXT2MD_REL = https://github.com/mk270/erl_gemtext2md/releases
GEMTEXT2MD_URL = $(GEMTEXT2MD_REL)/download/v$(GEMTEXT2MD_VSN)/gemtext2md
GEMTEXT2MD = _build/tools/gemtext2md-$(GEMTEXT2MD_VSN)
$(GEMTEXT2MD):
mkdir -p $(dir $@)
curl -fsSL -o $@ $(GEMTEXT2MD_URL)
echo "<sha256> $@" | sha256sum -c -
chmod +x $@
docs/%.md: docs/%.gmi $(GEMTEXT2MD)
$(GEMTEXT2MD) $< > $@
Without an escript, the same code can be run from the library:
gemtext2md_cli:main(Args) is the escript entry point, and
gemtext2md_cli:run(Args, OutDevice) returns the exit status instead
of halting.
Development
rebar3 eunit
rebar3 dialyzer
rebar3 ex_doc
The documentation is written as -moduledoc and -doc attributes, so
OTP 27 or later is required. rebar3 ex_doc writes HTML to doc/; it
needs an OTP release that the ex_doc build supports (27, or 28.1 and
later).
Licence
Apache-2.0 (SPDX identifier); see the licenses entry in
src/gemtext2md.app.src.