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

DESCRIPTION
This library parses Markdown as defined in lowdown(5) into various output formats. 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 {
      enum lowdown_type type;
      unsigned int feat;
      unsigned int oflags;
    };

It has the following fields:

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 the referenced footnote style, not the "inline" style.
    LOWDOWN_AUTOLINK
        Autolink http, https, ftp, mailto, and relative links or link fragments.
    LOWDOWN_STRIKE
        Strikethrough support.
    LOWDOWN_HILITE
        Highlight span support. This are disabled by default because it may be erroneously interpreted as section headers.
    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 within words.
    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 parse indented content as 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).

oflags
    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_ESCAPE
        If LOWDOWN_HTML_SKIP_HTML has not been set, escapes in-document HTML so that it is rendered as opaque text.
    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.
    LOWDOWN_HTML_OWASP
        When escaping text, be extra paranoid in following the OWASP suggestions for which characters to escape.
    LOWDOWN_HTML_NUM_ENT
        Convert, when possible, HTML entities to their numeric form. If not set, the entities are used as given in the input.
    LOWDOWN_HTML_SKIP_HTML
        Do not render in-document HTML at all.

    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 if LOWDOWON_NROFF_GROFF is not specified. 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. Only applies to the LOWDOWN_NROFF output type.

    For LOWDOWN_TERM:

    LOWDOWN_TERM_SHORTLINK
        Render link URLs in short form.

    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.

maxdepth
    The maximum parse depth before the parser exits. Most documents will have a parse depth in the single digits.

cols
    For LOWDOWN_TERM, the "soft limit" for width of terminal output not including margins. This might be zero, in which case a reasonable default should be used.

hmargin
    For LOWDOWN_TERM, the left margin (space characters).

vmargin
    For LOWDOWN_TERM, the top/bottom margin (newlines).

type
    May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_MAN for -man macros, LOWDOWN_TERM for ANSI-compatible UTF-8 terminal output, 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.

  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_term_free(3), lowdown_term_new(3), lowdown_term_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.