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

enum class MarkdownDownloadStatus

Status of a download (see HostServices::Download)

MarkdownDownloadResult (struct)¶

struct MarkdownDownloadResult

Result of a download attempt

narrative_programming.h¶

RichMd::ResolveTransclusions¶

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

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.
The embeds name files beside or below the document only (root empty: the folder of currentFile; for a text from no file, relative paths, below the assets): a document from anyone must not show a file of the machine.
A caller that trusts the text widens it: root is the folder the embeds may reach, “/” for any file.

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).
Its size follows a size pushed with ImGui::PushFont(None, size), relative to the frame’s base size:
PushFont(None, ImGui::GetStyle().FontSizeBase * 0.8) renders it at 80%.

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

Headings¶

Heading (struct)¶

struct Heading

A heading of the last render

RichMd::LastRenderHeadings¶

const std::vector<Heading>& LastRenderHeadings();

The headings of the last Render() call (valid until the next one)

RichMd::FoldAllHeadings¶

void FoldAllHeadings(bool folded);

Folds (or unfolds) all the foldable headings (MarkdownOptions::foldableHeadings), from the next frame: those of the current document between BeginDocument() and EndDocument(), else those of the last Render()

Documents¶

ScrollAnimation (enum)¶

enum class ScrollAnimation

The scroll to a match, a heading or an anchor: eased over scrollAnimationSeconds, unless reduced motion is asked

DocumentOptions (struct)¶

struct DocumentOptions

The options of a document

RichMd::BeginDocument¶

void BeginDocument(const char* id, ImVec2 size = ImVec2(0.f, 0.f), const DocumentOptions& options = DocumentOptions());

A document: the renders and the widgets drawn until EndDocument() share a scroll area and their headings. size: as BeginChild (0: all the available space). Call EndDocument() in the same frame. The content is always drawn: there is no return value to skip it. One document at a time.

RichMd::EndDocument¶

void EndDocument();

RichMd::RenderDocument¶

void RenderDocument(const char* id, const std::string& markdown, ImVec2 size = ImVec2(0.f, 0.f), const DocumentOptions& options = DocumentOptions());

The one-call form: BeginDocument(id, size, options), Render(markdown), EndDocument()

RichMd::DocumentHeading¶

bool DocumentHeading(int level, const std::string& text, bool drawTitle = true);

Starts a section of the document that is not markdown (widgets, a plot): a heading of the document, with its slug (an anchor for [text](#slug) links). drawTitle: draws the text as a markdown heading of that level; False when the title is drawn by other means (an ImGui text, a plot’s own title), or not at all. Returns whether the section shows: False when a fold hides it (MarkdownOptions::foldableHeadings), and the application skips its widgets.

Folding text¶

FoldingTextOptions (struct)¶

struct FoldingTextOptions

The options of a folding text

RichMd::RenderFolding¶

bool RenderFolding(const char* id, const std::string& markdown, const FoldingTextOptions& options = FoldingTextOptions());

Renders a markdown text, folded to its first paragraph (the headings before it stay) or to a line , or open; a link at its end folds or unfolds it. id: keeps its state, in the current window. Returns whether it is open.

Options and callbacks¶

MarkdownFontOptions (struct)¶

struct MarkdownFontOptions

MarkdownImage (struct)¶

struct MarkdownImage

RichMd::OnImage_Default¶

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

RichMd::OnOpenLink_Default¶

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

RichMd::IsWebUrl¶

bool IsWebUrl(const std::string& url);

Whether a link is a web address (http:// or https://, any case): the only ones OnOpenLink_Default opens

MarkdownCallbacks (struct)¶

struct MarkdownCallbacks

MarkdownOptions (struct)¶

struct MarkdownOptions

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

render_file() 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)¶

struct SizedFont

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();

The markdown’s fonts, at the size that a render would use now (see Render(): they follow a pushed size)

MarkdownFontSpec (struct)¶

struct MarkdownFontSpec

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