gemtext2md (gemtext2md v0.1.3)
View SourceConvert 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
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
-opaque context()
The state of a streaming conversion, made by new/0.
Functions
-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}}.
-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.
-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.
-spec new() -> context().
Start a streaming conversion.
-spec render(Elements) -> iodata() when Elements :: [gemini_text:tagged_line()].
Render elements already parsed by gemini_text:parse/1 as Markdown.