LOWDOWN(3)

NAME
lowdown - simple markdown translator library

LIBRARY
liblowdown

SYNOPSIS
#include <sys/queue.h>
#include <stdio.h>
#include <lowdown.h>
struct lowdown_opts
struct lowdown_metadata
enum lowdown_err
typedef void
(*lowdown_msg)(enum lowdown_err err, void *arg, const char *msg);

DESCRIPTION
The lowdown library parses Markdown as defined in lowdown(5) into HTML or roff (-ms or -man macro sets). It consists of both a high-level interface consisting of lowdown_buf(3), lowdown_buf_diff(3), lowdown_file(3), and lowdown_file_diff(3); then a series of low-level interfaces directly to the parsers and renderers.

Most functions use the struct lowdown_opts structure to manage features.

    struct lowdown_opts {
      lowdown_msg msg;
      enum lowdown_type type;
      void *arg;
      unsigned int feat;
      unsigned int oflags;
    };

It has the following fields:

arg Pointer passed to msg, if not NULL.

feat
    Features used during the parse. This bit-field may have the following bits OR'd:

    LOWDOWN_TABLES
        Allow for GFM tables.
    LOWDOWN_FENCED
        Allow for GFM fenced (language-specific) code blocks.
    LOWDOWN_FOOTNOTES
        MMD style footnotes. This only supports one-liner footnotes on the same line as the footnote definition (not the in-line referent).
    LOWDOWN_AUTOLINK
        Autolink http, https, ftp, mailto, and relative links or link fragments.
    LOWDOWN_STRIKE
        Strikethrough support.
    LOWDOWN_HILITE
        Highlight. Do not use this option.
    LOWDOWN_SUPER
        Allow for super-scripts. This accepts foo^bar, which puts the parts following the caret until whitespace in superscripts; or foo^(bar), which puts only the parts in parenthesis.
    LOWDOWN_MATH
        Recognise mathematics equations.
    LOWDOWN_NOINTEM
        Disable emphasis with links.
    LOWDOWN_COMMONMARK
        Tighten input parsing to the CommonMark specification. This also uses the first ordered list value instead of starting all lists at one. Experimental.
    LOWDOWN_NOCODEIND
        Do not indent code blocks.
    LOWDOWN_METADATA
        Accept MMD metadata. For the first paragraph to count as meta-data, the first line must have a colon in it. Otherwise it's considered a regular paragraph. Meta-data is escaped according to the output mode; and if the LOWDOWN_SMARTY flag is set, also smartypantsed.

    The default value is zero (none).

msg Message function (lowdown_msg) for logging messages. If NULL, messages are not logged.

ofeat
    Features used by the output generators. This bit-field may have the following enabled. Note that bits are by definition specific to an output type.

    For LOWDOWN_HTML:

    LOWDOWN_HTML_SKIP_HTML
        Do not render in-document HTML at all. Note that LOWDOWN_HTML_ESCAPE takes priority if both are specified. Text within HTML elements remains.
    LOWDOWN_HTML_ESCAPE
        Leaves in-line HTML in its source form as if it were opaque text. Takes precedence over LOWDOWN_HTML_ESCAPE.
    LOWDOWN_HTML_HARD_WRAP
        Retain line-breaks within paragraphs.
    LOWDOWN_HTML_HEAD_IDS
        Have an identifier written with each header element consisting of an HTML-escaped version of the header contents.

    And for LOWDOWN_MAN and LOWDOWN_NROFF:

    LOWDOWN_NROFF_SKIP_HTML
        Do not render in-document HTML at all. Text within HTML elements remains.
    LOWDOWN_NROFF_HARD_WRAP
        Retain line-breaks within paragraphs.
    LOWDOWN_NROFF_NUMBERED
        Use numbered sections. Only applies to the LOWDOWN_NROFF output type.
    LOWDOWN_NROFF_GROFF
        Use GNU extensions (i.e., for groff(1)) when rendering output. You'll need to include -m pdfmark when invoking groff(1) for formatting links.

    For any mode, you may specify:

    LOWDOWN_SMARTY
        Don't use “smartypants” formatting.
    LOWDOWN_STANDALONE
        Emit a full document instead of a document fragment. Parts of this envelope may be populated from metadata if LOWDOWN_METADATA was provided as an option. See lowdown(1) for details.

type
    May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_MAN for -man macros, or LOWDOWN_NROFF for -ms macros. The LOWDOWN_TREE type causes a debug tree to be written.

    Both LOWDOWN_MAN and LOWDOWN_MS will use troff tables, which usually require the tbl(1) preprocessor.

Another common structure is struct lowdown_metadata, which is used to hold parsed (and output-formatted) metadata keys and values if LOWDOWN_METADATA was provided as an input bit.

    struct lowdown_meta {
      char *key;
      char *value;
    };

This structure consists of the following fields:

key The metadata key in its lowercase, canonical form.

value
    The metadata value as rendered in the current output format.

An error message function of type lowdown_msg is given in struct lowdown_opts.

    typedef	void (*lowdown_msg)
      (enum lowdown_err, void *, const char *);

It accepts the following arguments:

err An error code programmatically describing the error.

arg An opaque pointer provided in struct lowdown_opts.

msg Additional information about the error.

The error code may be one of:

LOWDOWN_ERR_SPACE_BEFORE_LINK
    Spaces before the URL portion of a link. This is not portable.

LOWDOWN_ERR_METADATA_BAD_CHAR
    A bad character in a metadata key (it is converted into “”?).

LOWDOWN_ERR_UNKNOWN_FOOTNOTE
    A footnote reference to an unknown footnote, and is thus being ignored.

LOWDOWN_ERR_DUPE_FOOTNOTE
    A duplicate footnote reference was encountered, and is thus being ignored.

  Pledge Promises
The lowdown library is built to operate in security-sensitive environments, such as those using pledge(2) on OpenBSD. The only promise required is stdio for lowdown_file_diff(3) and lowdown_file(3): both require access to the stream for reading input.

SEE ALSO
lowdown(1), lowdown_buf(3), lowdown_buf_diff(3), lowdown_doc_free(3), lowdown_doc_new(3), lowdown_doc_parse(3), lowdown_errstr(3), lowdown_file(3), lowdown_file_diff(3), lowdown_html_free(3), lowdown_html_new(3), lowdown_html_rndr(3), lowdown_nroff_free(3), lowdown_nroff_new(3), lowdown_nroff_rndr(3), lowdown_tree_free(3), lowdown_tree_new(3), lowdown_tree_rndr(3), lowdown(5)

AUTHORS
The lowdown library was forked by Kristaps Dzonsons <kristaps@bsd.lv> from hoedown: https://github.com/hoedown/hoedown. It has been considerably changed since then.