rich_md (C++)

Rich Markdown: markdown rendered in ImGui: text styles, headings, lists, tables, images, links, code blocks, LaTeX math and diagrams.

rich_md_host.h¶

MarkdownDownloadStatus (enum)¶

Status of a download (see HostServices::Download)

MarkdownDownloadResult (struct)¶

Result of a download attempt

The services¶

Context (struct)¶

A markdown context (its options, its fonts, its caches): made by create_context, destroyed by destroy_context. Opaque.

RichMd::set_download_function¶

Sets the function that downloads URL images (HostServices.Download), for every markdown context. imgui_bundle installs one at import (urllib in a thread on desktop, JS fetch in Pyodide).
Called every frame for a URL until it returns Ready or Failed; an asynchronous download returns
Downloading first and tracks its pending downloads itself. None disables URL images.

narrative_programming.h¶

RichMd::ResolveTransclusions¶

std::string ResolveTransclusions(const std::string& markdown, const ReadTextFile& readFile, const std::string& currentFile = "");

ResolveTransclusions replaces the embeds of a markdown text: readFile reads a file (or returns std::nullopt); currentFile is the file the text comes from, if any. Render() calls it with the host’s ReadAsset.

rich_md.h¶

RichMd::Render¶

void Render(const std::string& markdownString);

Renders a markdown string. Its common indentation is removed first (so that a string written inside an indented function renders as expected; no-op on flush-left text), then its transclusions are resolved (see ResolveTransclusions; the files are read through the host’s ReadAsset).

RichMd::RenderRaw¶

void RenderRaw(const std::string& markdownString);

Renders a markdown string as is (no unindent, no transclusion)

RichMd::PushSelectableText¶

void PushSelectableText(bool selectable);

Whether the text of the renders that follow can be selected, until the matching PopSelectableText(), in the same frame. For markdown inside something that reacts to a drag itself (a node of a node editor, a custom widget).

RichMd::PopSelectableText¶

void PopSelectableText();

RichMd::SetSelectableTextDefault¶

void SetSelectableTextDefault(bool selectable);

Whether the text can be selected, outside of a PushSelectableText(): changes the option selectableText of the current context

Options and callbacks¶

MarkdownFontOptions (struct)¶

MarkdownImage (struct)¶

RichMd::OnImage_Default¶

std::optional<MarkdownImage> OnImage_Default(const std::string& image_path);

RichMd::OnOpenLink_Default¶

void OnOpenLink_Default(const std::string& url);

MarkdownCallbacks (struct)¶

MarkdownOptions (struct)¶

Context¶

RichMd::CreateContext¶

Context* CreateContext(const MarkdownOptions& options = MarkdownOptions());

A context holds the options, the fonts and the caches (textures, formulas, diagrams). Most applications have one.
Contexts: CreateContext makes one, any time after ImGui::CreateContext(); it becomes the current context when there is none. The fonts load at the first Render() (Dear ImGui 1.92 loads glyphs on demand).
DestroyContext destroys one (None: the current one) and frees its textures: call it while the rendering backend is still alive. Several contexts (e.g. two font sizes, several ImGui contexts) can live together; all the other functions act on the current one. In ImGui Bundle, ImmApp makes one for you when markdown is enabled.

RichMd::DestroyContext¶

void DestroyContext(Context* context = nullptr);

RichMd::SetCurrentContext¶

void SetCurrentContext(Context* context);

RichMd::GetCurrentContext¶

Context* GetCurrentContext();

RichMd::SetAssetsFolder¶

void SetAssetsFolder(const std::string& folder);

The folder where the default host reads the assets (fonts, images) from the file system, when they are not embedded in the binary. Default: the current directory.

Rendering files¶

RichMd::RenderFile¶

void RenderFile(const std::string& path, const std::string& target = "");

Renders ![[path#target]]: target is a section (“Intro”), its code (“Escape#code”), a code region, a heading of a markdown document, or empty (the whole file). The path is looked up in the assets first, then on the file system: a source file renders its own narrative with RICHMD_RENDER_THIS_FILE(“Intro”) (C++) or rich_md.render_this_file(“Intro”) (Python).

RenderFile() renders a section, a code region or a whole file: a program renders its own narrative with RICHMD_RENDER_THIS_FILE. The syntax and the resolver: narrative_programming.h.

Extensions¶

RichMd::RegisterFencedBlockRenderer¶

void RegisterFencedBlockRenderer(const std::string& language, std::function<void(const std::string& code)> renderer);

Renders the code blocks of a given language (mermaid, csv, ...) with your own function, instead of the code block renderer. Applies to the current context.

Your own renderers for fenced code blocks, Mermaid diagrams and links outside of markdown.

RichMd::RenderMermaid¶

void RenderMermaid(const std::string& source);

Renders a Mermaid diagram (flowchart, sequence or class diagram), as ```mermaid blocks do. A diagram that cannot be parsed is shown as code, with the error below it; so is any diagram when the library is built without IMGUI_RICHMD_WITH_MERMAID.
Limitations: a subset of Mermaid, for small and medium diagrams, with its own layout (not a copy of mermaid.js) and the colors of the ImGui style. The other diagram types, styles (classDef, style), click, themes, front matter and markdown in labels are not supported. Details: docs/mermaid.md in imgui_rich_md.

RichMd::RenderTextAsLink¶

void RenderTextAsLink(const char* text, const char* url);

Renders a link with the given text and url. Can be used outside of markdown rendering.

Style and fonts¶

SizedFont (struct)¶

Note: Since v1.92, Fonts can be displayed at any size: in order to display a font at a given size, we need to call
ImGui::PushFont(font, size) (or call separately ImGui::PushFontSize)

RichMd::GetCodeFont¶

SizedFont GetCodeFont();

MarkdownFontSpec (struct)¶

MarkdownFontSpec::MarkdownFontSpec¶

MarkdownFontSpec(bool italic_ = false, bool bold_ = false, int headerLevel_ = 0) :

            italic(italic_), bold(bold_), headerLevel(headerLevel_);

RichMd::GetFont¶

SizedFont GetFont(const MarkdownFontSpec& fontSpec);

RichMd::LinkColor¶

ImVec4 LinkColor();

Capabilities¶

RichMd::HasLatex¶

bool HasLatex();

... and

rendered as formulas (else shown as their source)

What this build and its host provide (available once a context exists).

RichMd::HasUrlImages¶

bool HasUrlImages();

images downloaded from http(s) urls

RichMd::HasCodeEditor¶

bool HasCodeEditor();

code blocks with syntax highlighting (else plain monospaced blocks)

Legacy names¶

RichMd::InitializeMarkdown¶

void InitializeMarkdown(const MarkdownOptions& options = MarkdownOptions());

The former names, kept for existing code.
The former names: InitializeMarkdown makes a default context and makes it current (a second call does nothing); DeInitializeMarkdown destroys it.

RichMd::DeInitializeMarkdown¶

void DeInitializeMarkdown();

RichMd::RenderUnindented¶

void RenderUnindented(const std::string& markdownString);

The former name of Render

RichMd::GetFontLoaderFunction¶

VoidFunction GetFontLoaderFunction();

Legacy: the fonts now load at the first Render(). The returned function loads them right away, for hosts that build their font atlas once (no dynamic fonts).