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.

The following describes a general parse sequence:

1.  Create output, input buffers by bufnew() function.

2.  Fill input buffer by bufput() function.

3.  Create struct mkd_renderer or use provided renderer.

4.  Call markdown() function.

5.  Process output buffer.

6.  Call bufrelease() function to clean up buffers.

REFERENCE
This section documents the functions, types, definitions available via <markdown.h>.

  Types

enum mkd_autolink
type of 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
has this form:

    struct mkd_renderer {
    	/* document level callbacks */
    	void (*prolog)(struct buf *ob, void *opaque);
    	void (*epilog)(struct buf *ob, void *opaque);
    	/* block level callbacks - NULL skips the block */
    	void (*blockcode)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	void (*blockquote)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	void (*blockhtml)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	void (*header)(struct buf *ob,
    	    struct buf *text, int level,
    	    void *opaque);
    	void (*hrule)(struct buf *ob, void *opaque);
    	void (*list)(struct buf *ob,
    	    struct buf *text, int flags,
    	    void *opaque);
    	void (*listitem)(struct buf *ob,
    	    struct buf *text, int flags,
    	    void *opaque);
    	void (*paragraph)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	void (*table)(struct buf *ob,
    	    struct buf *head_row, struct buf *rows,
    	    void *opaque);
    	void (*table_cell)(struct buf *ob,
    	    struct buf *text, int flags,
    	    void *opaque);
    	void (*table_row)(struct buf *ob,
    	    struct buf *cells, int flags,
    	    void *opaque);
    	/* span level callbacks - NULL or return 0 prints the span verbatim */
    	int (*autolink)(struct buf *ob,
    	    struct buf *link, enum mkd_autolink type,
    	    void *opaque);
    	int (*codespan)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	int (*emphasis)(struct buf *ob,
    	    struct buf *text, char c,
    	    void *opaque);
    	int (*double_emphasis)(struct buf *ob,
    	    struct buf *text, char c,
    	    void *opaque);
    	int (*triple_emphasis)(struct buf *ob,
    	    struct buf *text, char c,
    	    void *opaque);
    	int (*image)(struct buf *ob,
    	    struct buf *link, struct buf *title, struct buf *alt,
    	    void *opaque);
    	int (*linebreak)(struct buf *ob, void *opaque);
    	int (*link)(struct buf *ob,
    	    struct buf *link, struct buf *title, struct buf *content,
    	    void *opaque);
    	int (*raw_html_tag)(struct buf *ob,
    	    struct buf *tag,
    	    void *opaque);
    	/* low level callbacks - NULL copies input directly into the output */
    	void (*entity)(struct buf *ob,
    	    struct buf *entity,
    	    void *opaque);
    	void (*normal_text)(struct buf *ob,
    	    struct buf *text,
    	    void *opaque);
    	/* renderer data */
    	int max_work_stack; /* prevent arbitrary deep recursion, cf README */
    	const char *emph_chars; /* chars that trigger emphasis rendering */
    	void *opaque; /* opaque data send to every rendering callback */
    };

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.

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

flags of the list and listitem function callbacks are: MKD_LIST_ORDERED, MKD_LI_BLOCK.

flags of the table_cell and table_row function callbacks are: MKD_CELL_ALIGN_DEFAULT, MKD_CELL_ALIGN_LEFT, MKD_CELL_ALIGN_RIGHT, MKD_CELL_ALIGN_CENTER, MKD_CELL_ALIGN_MASK, MKD_CELL_HEAD.

The normal_text callback should perform whatever escape is needed to have the output looking like the input 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.

EXAMPLES
Simple example that uses first argument as a markdown string, converts it to an HTML and outputs it to stdout.

    #include <stdio.h>
    #include <buffer.h>
    #include <markdown.h>
    #include <renderers.h>
    #define INPUT_UNIT  1024
    #define OUTPUT_UNIT 64
    int
    main(int argc, char *argv[])
    {
      struct buf *ib, *ob;
      /* Make sure we have enough arguments. */
      if (argc != 2) {
        return 1;
      }
      ib = bufnew(INPUT_UNIT);
      ob = bufnew(OUTPUT_UNIT);
      /* bufputs() is a wrapper over bufput() for nil-terminated string. */
      bufputs(ib, argv[1]);
      markdown(ob, ib, &mkd_html);
      /* Note the resulted data is not nil-terminated string;
       * to make it use bufnullterm(). */
      printf("%.*s", (int)ob->size, ob->data);
      bufrelease(ib);
      bufrelease(ob);
      return 0;
    }

SEE ALSO
soldout_array(3), soldout_buffer(3), soldout_renderers(3), John Gruber's markdown format: http://daringfireball.net/projects/markdown/

AUTHORS
-nosplit The soldout library was written by Natasha "Kerensikova" Porte <natacha@instinctive.eu>. Manual page was originally written by Massimo Manghi <mxmanghi@apache.org>, and rewritten to mdoc format by Svyatoslav Mishyn <juef@openmailbox.org>.