LOWDOWN(3)

NAME
lowdown - simple markdown translator library

LIBRARY
liblowdown

SYNOPSIS
#include <sys/queue.h>
#include <stdio.h>
#include <lowdown.h>
struct lowdown_metadata
struct lowdown_node
struct lowdown_opts

DESCRIPTION
This library parses lowdown(5) into various output formats.

The library consists first of a high-level interface consisting of lowdown_buf(3), lowdown_buf_diff(3), lowdown_file(3), and lowdown_file_diff(3).

The high-level functions interface with low-level functions that perform parsing and formatting. These consist of lowdown_doc_new(3), lowdown_doc_parse(3), and lowdown_doc_free(3) for parsing lowdown(5) documents into an abstract syntax tree, then lowdown_html_free(3), lowdown_html_new(3), and lowdown_html_rndr(3) for HTML formatting; lowdown_nroff_free(3), lowdown_nroff_new(3), and lowdown_nroff_rndr(3) for roff(7) output; lowdown_term_free(3), lowdown_term_new(3), and lowdown_term_rndr(3) for ANSI-escaped UTF-8 terminal output; and finally lowdown_tree_free(3), lowdown_tree_new(3), and lowdown_tree_rndr(3) for formatting debugging output.

To compile and link, use pkg-config(1):

    % cc `pkg-config --cflags lowdown` -c -o sample.o sample.c
    % cc -o sample sample.o `pkg-config --libs lowdown`

  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.

  Types
All lowdown functions use one or more of the following structures.

The struct lowdown_opts structure manage features. It has the following fields:

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

    LOWDOWN_AUTOLINK
        Parse http, https, ftp, mailto, and relative links or link fragments.
    LOWDOWN_COMMONMARK
        Tighten input parsing to the CommonMark specification. This also uses the first ordered list value instead of starting all lists at one. This feature is experimental and incomplete.
    LOWDOWN_DEFLIST
        Parse PHP extra definition lists. This is currently constrained to single-key lists.
    LOWDOWN_FENCED
        Parse GFM fenced (language-specific) code blocks.
    LOWDOWN_FOOTNOTES
        Parse MMD style footnotes. This only supports the referenced footnote style, not the "inline" style.
    LOWDOWN_HILITE
        Parse highlit sequences. This are disabled by default because it may be erroneously interpreted as section headers.
    LOWDOWN_IMG_EXT
        Parse PHP image extended attributes.
    LOWDOWN_MATH
        Parse mathematics equations.
    LOWDOWN_METADATA
        Parse 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 use smart typography.
    LOWDOWN_NOCODEIND
        Do not parse indented content as code blocks.
    LOWDOWN_NOINTEM
        Do not parse emphasis within words.
    LOWDOWN_STRIKE
        Parse strikethrough sequences.
    LOWDOWN_SUPER
        Parse 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_TABLES
        Parse GFM tables.

    The default value is zero (none).

unsigned int 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.

    FOr LOWDOWN_LATEX:

    LOWDOWN_LATEX_NUMBERED
        Use the default numbering scheme for sections, subsections, etc. If not specified, these are inhibited.
    LOWDOWN_LATEX_SKIP_HTML
        Do not render in-document HTML at all. Text within HTML elements remains.

    And for LOWDOWN_MAN and LOWDOWN_NROFF:

    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.
    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_SKIP_HTML
        Do not render in-document HTML at all. Text within HTML elements remains.

    For LOWDOWN_TERM:

    LOWDOWN_TERM_SHORTLINK
        Render link URLs in short form.

    For any mode, you may specify:

    LOWDOWN_SMARTY
        Don't use smart typography 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.

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

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

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

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

enum lowdown_type type
    May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_LATEX for LaTeX, 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. This structure consists of the following fields:

char *key
    The metadata key in its lowercase, canonical form.

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

The abstract syntax tree is encoded in struct lowdown_node, which consists of the following.

enum lowdown_rndrt type
    The node type. (Described below.)

size_t id
    An identifier unique within the document. This can be used as a table index since the number is assigned from a monotonically increasing point during the parse.

struct lowdown_node *parent
    The parent of the node, or NULL at the root.

enum lowdown_chng chng
    Change tracking: whether this node was inserted (LOWDOWN_CHNG_INSERT), deleted (LOWDOWN_CHNG_DELETE), or neither (LOWDOWN_CHNG_NONE).

struct lowdown_nodeq children
    A possibly-empty list of child nodes.

<anon union>
    An anonymous union of type-specific structures. See below for a description of each one.

The nodes may be one of the following types, with default rendering in HTML5 to illustrate functionality.

LOWDOWN_ROOT
    The root of the document. This is always the topmost node, and the only node where the parent field is NULL.

LOWDOWN_BLOCKCODE
    A block-level (and possibly language-specific) snippet of code. Described by the <pre><code> elements.

LOWDOWN_BLOCKHTML
    A block-level snippet of HTML. This is simply opaque HTML content. (Only if configured during parse.)

LOWDOWN_BLOCKQUOTE
    A block-level quotation. Described by the <blockquote> element.

LOWDOWN_CODESPAN
    A snippet of code. Described by the <code> element.

LOWDOWN_DOC_FOOTER
    Closes out the document opened in LOWDOWN_DOC_HEADER.

LOWDOWN_DOC_HEADER
    A header with data gathered from document metadata (if configured). Described by the <head> element. (Only if configured during parse.)

LOWDOWN_DOUBLE_EMPHASIS
    Bold (or otherwise notable) content. Described by the <strong> element.

LOWDOWN_EMPHASIS
    Italic (or otherwise notable) content. Described by the <em> element.

LOWDOWN_ENTITY
    An HTML entity, which may either be named or numeric.

LOWDOWN_FOOTNOTE_DEF
    A footnote within a LOWDOWN_FOOTNOTES_BLOCK node. Described by the <li id="fnXX"> element. (Only if configured during parse.)

LOWDOWN_FOOTNOTE_REF
    A reference to a LOWDOWN_FOOTNOTE_DEF. Described by the <sup><a> elements. (Only if configured during parse.)

LOWDOWN_FOOTNOTES_BLOCK
    A block of footnotes. Described by the <div class="footnotes"><hr /><ol> elements. (Only if configured during parse.)

LOWDOWN_HEADER
    A block-level header. Described by one of <h1> through <h6>. (The level is bound at 6.)

LOWDOWN_HIGHLIGHT
    Marked test. Described by the <mark> element. (Only if configured during parse.)

LOWDOWN_HRULE
    A horizontal line. Described by <hr>.

LOWDOWN_IMAGE
    An image. Described by the <img> element.

LOWDOWN_LINEBREAK
    A hard line-break within a block context. Described by the <br> element.

LOWDOWN_LINK
    A link to external media. Described by the <a> element.

LOWDOWN_LINK_AUTO
    Like LOWDOWN_LINK, except inferred from text content. Described by the <a> element. (Only if configured during parse.)

LOWDOWN_LIST
    A block-level list enclosure. Described by <ul> or <ol>.

LOWDOWN_LISTITEM
    A block-level list item, always appearing within a LOWDOWN_LIST. Described by <li>.

LOWDOWN_MATH_BLOCK
    A block (or inline) of mathematical text in LaTeX format. Described within \[xx\] or \(xx\). This is usually (in HTML) externally handled by a JavaScript renderer. (Only if configured during parse.)

LOWDOWN_META
    Meta-data keys and values. (Only if configured during parse.) These are described by elements in the <head> element.

LOWDOWN_NORMAL_TEXT
    Normal text content.

LOWDOWN_PARAGRAPH
    A block-level paragraph. Described by the <p> element.

LOWDOWN_RAW_HTML
    An inline of raw HTML. (Only if configured during parse.)

LOWDOWN_STRIKETHROUGH
    Content struck through. Described by the <del> element. (Only if configured during parse.)

LOWDOWN_SUPERSCRIPT
    A superscript. Described by the <sup> element. (Only if configured during parse.)

LOWDOWN_TABLE_BLOCK
    A table block. Described by <table>. (Only if configured during parse.)

LOWDOWN_TABLE_BODY
    A table body section. Described by <tbody>. Parent is always LOWDOWN_TABLE_BLOCK. (Only if configured during parse.)

LOWDOWN_TABLE_CELL
    A table cell. Described by <td> or <th> if in the header. Parent is always LOWDOWN_TABLE_ROW. (Only if configured during parse.)

LOWDOWN_TABLE_HEADER
    A table header section. Described by <thead>. Parent is always LOWDOWN_TABLE_BLOCK. (Only if configured during parse.)

LOWDOWN_TABLE_ROW
    A table row. Described by <tr>. Parent is always LOWDOWN_TABLE_HEADER or LOWDOWN_TABLE_BODY. (Only if configured during parse.)

LOWDOWN_TRIPLE_EMPHASIS
    Combination of LOWDOWN_EMPHASIS and LOWDOWN_DOUBLE_EMPHASIS.

The following anonymous union structures correspond to certain nodes. Note that all buffers may be zero-length.

rndr_meta
    Each LOWDOWN_META key-value pair is represented. The keys are lower-case without spaces or non-ASCII characters. Enclosed nodes may consist only of LOWDOWN_NORMAL_TEXT and LOWDOWN_ENTITY.

rndr_definition
    For LOWDOWN_DEFINITION, containing flags that may be HLIST_FL_BLOCK if the definition list should be interpreted as containing block elements.

rndr_list
    For LOWDOWN_LIST, consists of a bitfield flags that may be set to HLIST_FL_ORDERED for an ordered list and HLIST_FL_UNORDERED for an unordered one. If HLIST_FL_BLOCK is set, the list should be output as if items were separate blocks. If start is a non-empty string, it is the first list item value.

rndr_paragraph
    For LOWDOWN_PARAGRAPH, species how many lines the paragraph has in the input file and beoln, set to non-zero if the paragraph ends with an empty line instead of a breaking block element.

rndr_listitem
    For LOWDOWN_LISTITEM, consists of a bitfield flags that may be set to HLIST_FL_ORDERED (an ordered list), HLIST_FL_UNORDERED (unordered list), HLIST_FL_DEF (definition list data), and/or HLIST_FL_BLOCK (list item output as if containing block elements). The HLIST_FL_BLOCK should not be used: use the parent list (or definition list) flags for this. The num is the index in an ordered list.

rndr_header
    For LOWDOWN_HEADER, the level of the header (1–6).

rndr_normal_text
    The basic text content for LOWDOWN_NORMAL_TEXT.

rndr_entity
    For LOWDOWN_ENTITY, the entity text.

rndr_autolink
    For LOWDOWN_LINK_AUTO, the link address as link; the textual component text; and the link type type, which may be one of HALINK_EMAIL for e-mail links and HALINK_NORMAL otherwise. Any buffer may be empty-sized.

rndr_raw_html
    For LOWDOWN_RAW_HTML, the opaque HTML text.

rndr_link
    Like rndr_autolink.

rndr_blockcode
    For LOWDOWN_BLOCKCODE, the opaque text of the block and the optional lang of the code language.

rndr_codespan
    The opaque text of the contents.

rndr_table_header
    For LOWDOWN_TABLE_HEADER, the number of columns in each row and the per-column flags, which may be bits of HTBL_FL_ALIGN_LEFT, HTBL_FL_ALIGN_RIGHT, or HTBL_FL_ALIGN_CENTER when masked with HTBL_FL_ALIGNMASK; or HTBL_FL_HEADER.

rndr_table_cell
    For LOWDOWN_TABLE_CELL, the current col colum number out of columns. See rndr_table_header for a description of the bits in flags.

rndr_footnote_def
    For LOWDOWN_FOOTNOTE_DEF, the footnote number num.

rndr_footnote_ref
    For a LOWDOWN_FOOTNOTE_REF reference to a LOWDOWN_FOOTNOTE_DEF, the footnote number num.

rndr_image
    For LOWDOWN_IMAGE, the image address link, the image title title, dimensions NxN (width by height) in dims, and alternate text alt.

rndr_math
    For LOWDOWN_MATH, the mode of display displaymode: if 1, in-line math; if 2, multi-line.

rndr_blockhtml
    For LOWDOWN_BLOCKHTML, the opaque HTML text.

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_latex_free(3), lowdown_latex_new(3), lowdown_latex_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
lowdown was forked from hoedown: https://github.com/hoedown/hoedown by Kristaps Dzonsons, kristaps@bsd.lv. It has been considerably modified since.