SOLDOUT_MARKDOWN(3)

🎀 SOLDOUT_MARKDOWN(3) — the markdown parser, bestie edition 🎀

okay so this whole page is about soldout_markdown and markdown, and their whole job is to parse markdown documents. that's it. that's the vibe. it's a C library function that takes markdown in one hand and hands you rendered stuff back with the other. no cap 💅

---

✨ SYNOPSIS ✨

like, here's the whole cast list, copy-pasted with love:

#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 💖

so the markdown() function parses the input buffer ib and renders it into the output buffer ob. and rndr? that's a pointer to the renderer structure. that's the whole flow, bestie, input goes in, output comes out, the renderer decides what it all looks like 🦋

now here's the part that lowkey changes everything: function pointers inside struct mkd_renderer can be NULL. and the two kinds of NULL behave so differently:

• a null block-level callback makes that corresponding block disappear from the output entirely, like the callback was just an empty function that does nothing. poof. gone 💀
• a null span-level callback makes the corresponding element get treated as normal characters, copied verbatim into the output. so it survives, it's just naked.

and also — span-level callbacks return an int, and that int is basically a vibe check: it tells you whether the renderer accepts to render the item (non-zero return value) or whether it should be copied verbatim (zero return value). periodt.

the first argument of a renderer function is always the output buffer, which is where the function is supposed to write its output. and the last argument is always a private pointer, which is the opaque member of struct mkd_renderer. and listen — libsoldout itself never does anything with this data. it's yours. do whatever, it doesn't peek 🙈

emph_chars is a zero-terminated string holding 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 then gets passed to the emphasis, double_emphasis and triple_emphasis function callbacks through the parameter c. cute, right? 🎀

the normal_text callback should perform whatever escape is needed to have the output looking like the input data. that's on you, bestie.

libsoldout supports PHP-Markdown-like tables ✨. it uses these flags: MKD_CELL_ALIGN_DEFAULT, MKD_CELL_ALIGN_LEFT, MKD_CELL_ALIGN_RIGHT, MKD_CELL_ALIGN_CENTER, MKD_CELL_ALIGN_MASK, MKD_CELL_HEAD — and those show up in these function callbacks: table_cell and table_row.

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

---

🌸 Types 🌸

enum mkd_autolink

it's the type of autolink, and here's every single flavor:

• 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. that's it. nothing. silence. main character energy of saying nothing and meaning everything 💅

---

⭐ SEE ALSO ⭐

• soldout(3)
• soldout_buffer(3)
• soldout_renderers(3)

go read those next, iykyk 🦋

---

👑 AUTHORS 👑

the soldout library was written by Natasha "Kerensikova" Porte <natacha@instinctive.eu>. the manual page was originally written by Massimo Manghi <mxmanghi@apache.org>, and rewritten to mdoc format by Svyatoslav Mishyn <juef@openmailbox.org>. icons, all of them 🎀✨

---

and that's the whole page bestie!! this one shipped with Debian, dated May 30, 2016 — oldie but a goodie, fr fr. now go render something gorgeous 🌈💖