gemtext2md (gemtext2md v0.1.3)

View Source

Convert Gemini text (gemtext) to Markdown.

Parsing is done by gemini_text. The conversion follows the Rust gemtext2md:

  • headings keep their level, and text lines become paragraphs;
  • a link becomes * [label](URL), or * [URL](URL) without a label;
  • a list item becomes - item;
  • a quote line becomes > text, with a bare > line between the lines of a quote block, so each stays its own paragraph;
  • a preformatted block becomes a fenced block, keeping its alt text.

Consecutive links, list items or quote lines form one block. A blank line, or any other kind of line, ends it. Each block is followed by one blank line.

The input must be UTF-8; transcode anything else first. Control characters are passed through, so sanitise the result before display if the source is untrusted.

There are two ways in. convert/1 takes a whole document. new/0, convert/2 and finish/1 take it in pieces, which may be split anywhere:

C0 = gemtext2md:new(),
{ok, Out1, C1} = gemtext2md:convert(Chunk1, C0),
{ok, Out2, C2} = gemtext2md:convert(Chunk2, C1),
{ok, Out3} = gemtext2md:finish(C2).

Write the outputs in order. A link, list or quote group is held back until it ends, and a preformatted block until its closing fence, so finish/1 may return output too. After an error no context is returned, so a broken stream cannot be continued.

Errors are those of gemini_text:parse/1: {Reason, LineNumber}, for example {invalid_utf8, 3}.

Summary

Types

The state of a streaming conversion, made by new/0.

Functions

Convert a whole document to Markdown.

Feed a chunk of input, which may end anywhere in a line.

End the input, returning any Markdown still held back: an unterminated last line, a group still open, or a preformatted block that was never closed. The errors are those of convert/1.

Start a streaming conversion.

Render elements already parsed by gemini_text:parse/1 as Markdown.

Types

context()

-opaque context()

The state of a streaming conversion, made by new/0.

Functions

convert(Text)

-spec convert(Text) -> Result
                 when Text :: binary(), Result :: {ok, iodata()} | {error, gemini_text:parse_error()}.

Convert a whole document to Markdown.

Returns {ok, Markdown} or {error, {Reason, LineNumber}}, for example {error, {invalid_utf8, 3}}.

convert(Chunk, Ctx)

-spec convert(Chunk, Ctx) -> Result
                 when
                     Chunk :: binary(),
                     Ctx :: context(),
                     Result :: {ok, iodata(), context()} | {error, gemini_text:parse_error()}.

Feed a chunk of input, which may end anywhere in a line.

Returns the Markdown that is complete so far, and the new context. The errors are those of convert/1; after one, no context is returned.

finish(Ctx)

-spec finish(Ctx) -> Result
                when Ctx :: context(), Result :: {ok, iodata()} | {error, gemini_text:parse_error()}.

End the input, returning any Markdown still held back: an unterminated last line, a group still open, or a preformatted block that was never closed. The errors are those of convert/1.

new()

-spec new() -> context().

Start a streaming conversion.

render(Elements)

-spec render(Elements) -> iodata() when Elements :: [gemini_text:tagged_line()].

Render elements already parsed by gemini_text:parse/1 as Markdown.