LOWDOWN(3) Library Functions Manual LOWDOWN(3)

lowdown
simple markdown translator library

library “liblowdown”

#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);

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:
Allow for GFM tables.
Allow for GFM fenced (language-specific) code blocks.
MMD style footnotes. This only supports one-liner footnotes on the same line as the footnote definition (not the in-line referent).
Autolink http, https, ftp, mailto, and relative links or link fragments.
Strikethrough support.
Highlight. Do not use this option.
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.
Recognise mathematics equations.
Disable emphasis with links.
Recognise CommonMark input. Experimental.
Do not indent code blocks.
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:
Do not render in-document HTML at all. Note that LOWDOWN_HTML_ESCAPE takes priority if both are specified. Text within HTML elements remains.
Leaves in-line HTML in its source form as if it were opaque text. Takes precedence over LOWDOWN_HTML_ESCAPE.
Retain line-breaks within paragraphs.
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:
Do not render in-document HTML at all. Text within HTML elements remains.
Retain line-breaks within paragraphs.
Use numbered sections. Only applies to the LOWDOWN_NROFF output type.
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:
Don't use “smartypants” formatting.
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:
 
 
Spaces before the URL portion of a link. This is not portable.
 
 
A bad character in a metadata key (it is converted into “”?).
 
 
A footnote reference to an unknown footnote, and is thus being ignored.
 
 
A duplicate footnote reference was encountered, and is thus being ignored.

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.

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)

The lowdown library was forked by Kristaps Dzonsons <kristaps@bsd.lv> from hoedown. It has been considerably changed since then.
December 23, 2018 OpenBSD 6.4