LOWDOWN(3)

NAME
lowdown, lowdown_buf, lowdown_errstr, lowdown_file, lowdown_standalone_close, lowdown_standalone_open - simple markdown translator library

LIBRARY
liblowdown

SYNOPSIS
#include <stdio.h>
#include <lowdown.h>
void
lowdown_buf(const struct lowdown_opts *opts, const unsigned char *buf, size_t bufsz, unsigned char **ret, size_t *retsz, struct lowdown_meta **meta, size_t *metasz);
const char *
lowdown_errstr(enum lowdown_err);
int
lowdown_file(const struct lowdown_opts *opts, FILE *f, unsigned char **ret, size_t *retsz, struct lowdown_meta **meta, size_t *metasz);
void
lowdown_standalone_close(const struct lowdown_opts *opts, unsigned char **ret, size_t *retsz);
void
lowdown_standalone_open(const struct lowdown_opts *opts, const struct lowdown_meta *meta, size_t metasz, unsigned char **ret, size_t *retsz);

DESCRIPTION
The lowdown library parses Markdown into HTML or roff (-ms or -man macro sets). There are two forms of invocation.

The first, lowdown_file, operates from an already-opened FILE stream. The second, lowdown_buf, operates directly on an input buffer buf of size bufsz.

Both accept a configuration structure, opts, which 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 single-dollar math mode.
    LOWDOWN_NOINTEM
        Disable emphasis with links.
    LOWDOWN_SPHD
        Require a space between hash marks and header.
    LOWDOWN_MATHEXP
        Recognise double-dollar math mode. This only works if LOWDOWN_MATH has also been set.
    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.

    The default value is zero (none).

msg Message function 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.

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

type
    May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_MAN for -man macros, or LOWDOWN_NROFF for -ms macros. Both LOWDOWN_MAN and LOWDOWN_MS will use troff tables, which usually require the tbl(1) preprocessor.

The results for both functions are stored in ret, which must later be passed to free(3), of size retsz. Both functions also accept the meta and metasz pointers. If both of these are not NULL, they are set to any meta tags that have been parsed. It is the caller's job to free the meta structure resources. Obviously, the meta tags are parsed only if LOWDOWN_METADATA has been provided.

The lowdown_errstr is provided to return a human-readable version of enum lowdown_err. It returns a generic (en_GB) description.

The lowdown_standalone_open and lowdown_standalone_close are utility functions for outputting a document header and footer (in the given output format) given document meta-data.

RETURN VALUES
The lowdown_file returns zero if the file-reading sequenced failed, non-zero otherwise.

SEE ALSO
groff(1), lowdown(1)

AUTHORS
The lowdown library was forked by Kristaps Dzonsons <kristaps@bsd.lv> from hoedown: https://github.com/hoedown/hoedown.

CAVEATS
The lowdown library functions will invoke exit(3) if internal memory allocation fails. There is no way to catch these conditions.