ktsu.ImGui.Markdown 3.16.2

ktsu.ImGui.Markdown

ImGui.Markdown renders CommonMark markdown directly inside Dear ImGui, using Markdig for parsing. It is a standalone package with no dependency on ktsu.ImGui.App, so it can be dropped into any Hexa.NET.ImGui application.

Features

• CommonMark parsing: Full CommonMark syntax plus pipe tables, task lists, and autolinks, via a configured Markdig pipeline
• Headings, emphasis, and code: Headings scale from the live font size, so DPI and accessibility scaling are respected automatically; bold and italic fall back to faux styling when no matching font is registered
• Lists: Nested bullet, ordered, and task lists
• Blockquotes and thematic breaks: Rendered with an indent bar and a horizontal rule respectively
• Tables: Rendered with ImGui's native table API
• Links: Clickable, with an optional callback or automatic OS-open for http, https, and mailto schemes
• Images: Local images via a resolver callback; remote or unresolved images fall back to a placeholder box with the alt text
• Two APIs: A cached static Render for convenience, and a MarkdownDocument instance for hot render paths where the source is parsed once

Installation

dotnet add package ktsu.ImGui.Markdown

Quick Start

Static render (cached by source)

ImGuiMarkdown.Render parses the given markdown and caches the result keyed by the source string, so calling it every frame with the same text does not re-parse it.

using ktsu.ImGui.Markdown;
using Hexa.NET.ImGui;

ImGui.Begin("Markdown");
ImGuiMarkdown.Render("""
    # Hello, ImGui

    A **CommonMark** renderer for *Dear ImGui*, with `inline code` and [links](https://github.com/ktsu-dev).
    """);
ImGui.End();

MarkdownDocument for hot paths

When the same markdown source is rendered every frame, parse it once into a MarkdownDocument and render that instance instead of relying on the source-keyed cache.

using ktsu.ImGui.Markdown;

private static readonly MarkdownDocument ReadmeDocument = new("""
    # Changelog

    - Fixed a bug
    - Added a feature
    """);

// In the render loop:
ReadmeDocument.Render();

Configuration

Pass a MarkdownConfig to either API to control fonts, links, images, and spacing. All members are optional. Without any configuration, the renderer uses faux emphasis styling and image placeholder boxes.

MarkdownConfig config = new()
{
    FontResolver = ResolveFont,
    OnLinkClicked = url => Log.Info($"Clicked: {url}"),
    ImageResolver = ResolveImage,
};

ImGuiMarkdown.Render(markdown, config);

Registering real bold and italic fonts

By default, bold text is drawn with a faux technique (a second offset draw call that thickens the glyphs), and italic text renders upright because no shear is applied. For crisper output, register named font variants at startup (for example through ImGuiAppConfig.Fonts) and resolve them per role:

private static ImFontPtr? ResolveFont(MarkdownFontRole role, float pixelSize) => role switch
{
    MarkdownFontRole.Bold => boldFont,
    MarkdownFontRole.Italic => italicFont,
    MarkdownFontRole.BoldItalic => boldItalicFont,
    MarkdownFontRole.Code => monoFont,
    _ => null, // headings and body text keep the current font at pixelSize
};

Resolving local images

ImageResolver receives the raw source string from the markdown image syntax (for example ![logo](ktsu.png)) and returns the loaded texture ID and draw size:

private static MarkdownImageResult? ResolveImage(string source)
{
    AbsoluteFilePath imagePath = AppContext.BaseDirectory.As<AbsoluteDirectoryPath>() / source.As<FileName>();
    if (!File.Exists(imagePath))
    {
        return null; // falls back to a placeholder box with the alt text
    }

    ImGuiAppTextureInfo texture = ImGuiApp.GetOrLoadTexture(imagePath);
    return new MarkdownImageResult(texture.TextureId, new Vector2(64, 64));
}

Supported CommonMark Elements

• Headings (# through ######)
• Paragraphs, with bold (**) and italic (*) emphasis
• Inline code (`code`) and fenced or indented code blocks
• Bullet lists, ordered lists, and task lists (- [ ] / - [x]), all with nesting
• Blockquotes
• Thematic breaks (---)
• Pipe tables
• Links, including autolinks
• Images

v1 Limitations

• No syntax highlighting in code blocks; code is rendered in a plain monospace style
• No asynchronous remote image download; remote or unresolved image sources always show a placeholder box with the alt text
• Raw HTML blocks and inline HTML are rendered as escaped, literal text, not interpreted
• Faux italic renders upright when no italic font is supplied through FontResolver, since no glyph shear is applied

Demo

See examples/ImGuiMarkdownDemo/ for a runnable demo covering headings, emphasis, lists, quotes, code, tables, and images.

dotnet run --project examples/ImGuiMarkdownDemo

Contributing

Contributions are welcome! For feature requests, bug reports, or questions, please open an issue on the GitHub repository. If you would like to contribute code, please open a pull request with your changes.

License

ImGui.Markdown is licensed under the MIT License. See LICENSE for more information.