Discount

API reference

There are 17 public functions in the markdown library, broken into three categories:

Input functions

  1. MMIOT *mkd_in(FILE *f, mkd_flag_t *flags) reads a markdown input file and returns a MMIOT containing the preprocessed document. (which is then fed to markdown() for final formatting.)

  2. MMIOT *mkd_string(char *bfr, int size, mkd_flag_t *flags) reads the markdown input file that’s been written into bfr and returns a preprocessed blob suitable for feeding to markdown(). This function exists because annotations uses mmap() to access message files instead of traditional file i/o. (If you’re going to port Markdown to an AS/400, this function is the droid you’ve been looking for.)

“Big Picture”-style processing functions

  1. int markdown(MMIOT *doc, FILE *out, mkd_flag_t *flags) formats a document (created with mkd_in() or mkd_string()) and writes the resulting HTML document to out.

  2. int mkd_line(char *bfr, int size, char **out, mkd_flag_t *flags) allocates a buffer, then formats the text string into that buffer. text string, allocates a buffer, The differences from markdown() are it doesn’t support quoting, footnotes (“reference links”,) multiple paragraphs, lists, code sections, or pure html sections.

  3. int mkd_generateline(char*bfr, int size, FILE *out, mkd_flag_t *flags) formats the text string and writes the resulting HTML fragment to out. It is exactly like mkd_line() except that it writes the output to a FILE*.

Fine-grained access to the internals

  1. int mkd_compile(MMIOT *doc, mkd_flag_t *flags) takes a document created by mkd_in() or mkd_string() and compiles it into a tree of block elements.

  2. int mkd_generatehtml(MMIOT *doc, FILE *out) generates html from a compiled document.

  3. int mkd_document(MMIOT *doc, char **text) returns (in text) a pointer to the compiled html document, and (in the return code) the size of that document.

  4. int mkd_css(MMIOT *doc, char **out) allocates a buffer and populates it with any style blocks found in the document.

  5. int mkd_generatecss(MMIOT *doc, FILE *out) prints any style blocks in the document.

  6. int mkd_toc(MMIOT *doc, char **out) allocates a buffer, populates it with a table of contents, assigns it to out, and returns the length of the buffer.

    To get a table of contents, you must compile() the document with the MKD_TOC flag (described below)

  7. int mkd_generatetoc(MMIOT *doc, FILE *out) writes a table of contents to out; other than writing to a FILE*, it operates exactly like mkd_toc()

  8. int mkd_dump(MMIOT *doc, FILE *f, mkd_flag_t *flags, char *title) prints a block structure diagram of a compiled document.

  9. void mkd_cleanup(MMIOT *doc) releases the MMIOT allocated for the document.

Document header access functions

  1. char *mkd_doc_title(MMIOT *doc) returns the % title line.
  2. char *mkd_doc_author(MMIOT *doc) returns the % author(s) line.
  3. char *mkd_doc_date(MMIOT *doc) returns the % date line.

Url callback functions

  1. void mkd_e_url(MMIOT*, char* (callback)(char*,int,void*)) sets up a callback function that is called whenever discount processes a []() or <link> construct. The callback function is passed a pointer to the url, the size of the url, and a data pointer (null or supplied by mkd_e_data())
  2. void mkd_e_flags(MMIOT*, char *(callback)(char*,int,void*)) sets up a callback to provide additional arguments to the tags generated by []() and <link> constructs. If, for instance, you wanted to add target="_blank" to every generated url, you could just make a callback function that returned that string.
  3. `void mkd_e_code(MMIOT, char (callback)(char,int,void))‘ sets up a callback to format the contents of a code block.
  4. void mkd_e_free(char *, void*) is called to free any allocated memory returned by the url or flags callbacks.
  5. void mkd_e_data(MMIOT*, void*) assigns a callback data area to the url & flags callbacks.

Flag handling

  1. `mkd_flag_t *mkd_flags()‘ initializes a flag structure and returns a pointer to it.
  2. void mkd_free_flags(mkd_flag *) deletes a flag structure
  3. mkd_flag_t *mkd_copy(mkd_flag_t *) copies flags and returns a pointer to the copy.
  4. int mkd_flag_isset(mkd_flag_t *, int) checks if a flag is set.

  5. char *mkd_set_flag_string(mkd_flag_t *, char*) sets flags from a comma-separated list of flags; returns NULL if it was able to set all the flags, a pointer to the flag it couldn’t set otherwise.

    This function destroys the input string, so be aware!

  6. void mkd_set_flag_num(mkd_flag_t*, int) sets a specific flag.
  7. void mkd_clr_flag_num(mkd_flag_t*, int) clears a specific flag.
Flag Action
MKD_NOLINKS don’t do link processing, block tags
MKD_NOIMAGE don’t do image processing, block
MKD_NOPANTS don’t run smartypants()
MKD_NOHTML don’t allow raw html through AT ALL
MKD_NORMAL_LISTITEM disable github-style checkbox lists
MKD_TAGTEXT process text inside an html tag
MKD_NO_EXT don’t allow pseudo-protocols
MKD_EXPLICITLIST don’t combine numbered/bulletted lists
MKD_CDATA generate code for xml ![CDATA[…]]
MKD_NOSUPERSCRIPT no AB
MKD_STRICT conform to Markdown standard as implemented in Markdown.pl
MKD_NOTABLES disallow tables
MKD_NOSTRIKETHROUGH forbid strikethrough
MKD_1_COMPAT compatibility with MarkdownTest_1.0
MKD_TOC do table-of-contents processing
MKD_AUTOLINK make http://foo.com link even without <>s
MKD_NOHEADER don’t process header blocks
MKD_TABSTOP expand tabs to 4 spaces
MKD_SAFELINK paranoid check for link protocol
MKD_NODIVQUOTE forbid >%class% blocks
MKD_NOALPHALIST forbid alphabetic lists
MKD_EXTRA_FOOTNOTE enable markdown extra-style footnotes
MKD_NOSTYLE don’t extract <style> blocks
MKD_DLDISCOUNT enable discount-style definition lists
MKD_DLEXTRA enable extra-style definition lists
MKD_FENCEDCODE enabled fenced code blocks
MKD_IDANCHOR use id= anchors for TOC links
MKD_GITHUBTAGS allow dash and underscore in element names
MKD_URLENCODEDANCHOR urlencode non-identifier chars instead of replacing with dots
MKD_LATEX handle embedded LaTeX escapes
MKD_ALT_AS_TITLE use alt text as the title if no title is listed
MKD_EXTENDED_ATTR allow extended attribute suffixes
MKD_HTML5 handle html5 elements (maybe obsolete?)

Language bindings

I have an experimental C++ binding that lives on Github in mkdio.h++. It implements a couple of RAII objects; MKIOT – can’t call the class MMIOT because it clashes with the C MMIOT it wraps – for standard markdown (plus my extensions, of course) and GFIOT for github-flavo(u)red markdown. Alas, it is undocumented, but the mkdio.h++ header file is pretty simple and a trivial program that uses it is included in the mkdio.h++ sccs tree.