soldout_markdown(3)

NAME

soldout_markdown, markdown – parse markdown document

SYNOPSIS

#include <markdown.h>

#define MKD_CELL_ALIGN_DEFAULT

#define MKD_CELL_ALIGN_LEFT

#define MKD_CELL_ALIGN_RIGHT

#define MKD_CELL_ALIGN_CENTER

#define MKD_CELL_ALIGN_MASK

#define MKD_CELL_HEAD

#define MKD_LIST_ORDERED

#define MKD_LI_BLOCK

void

markdown(struct buf *ob, struct buf *ib, const struct mkd_renderer *rndr);

DESCRIPTION

The markdown() function parses the input buffer ib and renders it into the output buffer ob; rndr is a pointer to the renderer structure.

Function pointers in struct mkd_renderer can be NULL. A null block-level callback will make the corresponding block disappear from the output, as if the callback was an empty function. A null span-level callback will cause the corresponding element to be treated as normal characters, copied verbatim to the output. Moreover, span-level callbacks return an integer, which tells whether the renderer accepts to render the item (non-zero return value) or whether it should be copied verbatim (zero return value).

The first argument of a renderer function is always the output buffer, where the function is supposed to write its output. The last argument of a renderer function is always a private pointer, which is opaque member of struct mkd_renderer. libsoldout itself never does nothing with this data.

emph_chars is a zero-terminated string which contains the set of characters that trigger emphasis. In regular markdown, emphasis is only triggered by ‘_’ and ‘*’, but in some extensions it might be useful to add other characters to this list. The character that triggered the emphasis is then passed to emphasis, double_emphasis and triple_emphasis function callbacks through the parameter c.

The normal_text callback should perform whatever escape is needed to have the output looking like the input data.

libsoldout supports PHP-Markdown-like tables. It uses the following flags: MKD_CELL_ALIGN_DEFAULT, MKD_CELL_ALIGN_LEFT, MKD_CELL_ALIGN_RIGHT, MKD_CELL_ALIGN_CENTER, MKD_CELL_ALIGN_MASK, MKD_CELL_HEAD in these function callbacks: table_cell and table_row.

MKD_LIST_ORDERED, MKD_LI_BLOCK are used as flags in these function callbacks: list and listitem.

Types

enum mkd_autolink

type of autolink:

MKDA_NOT_AUTOLINK: used internally when it is not an autolink.
MKDA_NORMAL: normal http/https/ftp link.
MKDA_EXPLICIT_EMAIL: e-mail link with explicit mailto.
MKDA_IMPLICIT_EMAIL: e-mail link without mailto.

struct mkd_renderer

consists of the following fields:

Document level callbacks

prolog

a pointer to a void function(struct buf *ob, void *opaque)

epilog

a pointer to a void function(struct buf *ob, void *opaque)

Block level callbacks (NULL skips the block)

blockcode: a pointer to a void function(struct buf *ob, struct buf *text, void *opaque)
blockquote: a pointer to a void function(struct buf *ob, struct buf *text, void *opaque)
blockhtml: a pointer to a void function(struct buf *ob, struct buf *text, void *opaque)
header: a pointer to a void function(struct buf *ob, struct buf *text, int level, void *opaque)
hrule: a pointer to a void function(struct buf *ob, void *opaque)
list: a pointer to a void function(struct buf *ob, struct buf *text, int flags, void *opaque)
listitem: a pointer to a void function(struct buf *ob, struct buf *text, int flags, void *opaque)
paragraph: a pointer to a void function(struct buf *ob, struct buf *text, void *opaque)
table: a pointer to a void function(struct buf *ob, struct buf *head_row, struct buf *rows, void *opaque)
table_cell: a pointer to a void function(struct buf *ob, struct buf *text, int flags, void *opaque)
table_row: a pointer to a void function(struct buf *ob, struct buf *cells, int flags, void *opaque)

Span level callbacks (NULL or return 0 prints the span verbatim)

autolink: a pointer to a int function(struct buf *ob, struct buf *link, enum mkd_autolink type, void *opaque)
codespan: a pointer to a int function(struct buf *ob, struct buf *text, void *opaque)
emphasis: a pointer to a int function(struct buf *ob, struct buf *text, char c, void *opaque)
double_emphasis: a pointer to a int function(struct buf *ob, struct buf *text, char c, void *opaque)
triple_emphasis: a pointer to a int function(struct buf *ob, struct buf *text, char c, void *opaque)
image: a pointer to a int function(struct buf *ob, struct buf *link, struct buf *title, struct buf *alt, void *opaque)
linebreak: a pointer to a int function(struct buf *ob, void *opaque)
link: a pointer to a int function(struct buf *ob, struct buf *link, struct buf *title, struct buf *content, void *opaque)
raw_html_tag: a pointer to a int function(struct buf *ob, struct buf *tag, void *opaque)

Low level callbacks (NULL copies input directly into the output)

entity: a pointer to a void function(struct buf *ob, struct buf *entity, void *opaque)
normal_text: a pointer to a void function(struct buf *ob, struct buf *text, void *opaque)

Renderer data

int max_work_stack: prevent arbitrary deep recursion.
const char * emph_chars: chars that trigger emphasis rendering.
void * opaque: opaque data send to every rendering callback.

RETURN VALUES

The markdown() function does not return a value.

AUTHORS

The soldout library was written by Natasha "Kerensikova" Porte ⟨[email protected]⟩. Manual page was originally written by Massimo Manghi ⟨[email protected]⟩, and rewritten to mdoc format by Svyatoslav Mishyn ⟨[email protected]⟩.