Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android

Background

As ChatGPT-style products became common, many apps started integrating AI responses into chat interfaces. Those responses are usually returned as Markdown, so mobile clients need reliable Markdown rendering support. A quick survey showed three practical constraints:

  1. Many existing solutions are based on WebView, which can be expensive on mobile.
  2. On iOS, CocoaMarkdown is one of the few native rendering libraries, but its feature coverage and extensibility are limited.
  3. On Android, Markwon has a solid architecture, but it is Android-only.

That led to a native cross-platform renderer with a shared C++ core and thin platform adapters for iOS and Android. In this article, uppercase Markdown refers to the SDK, while lowercase markdown refers to the syntax.

Library overview

Markdown is an embeddable native rendering library for iOS and Android. It supports standard Markdown syntax together with a selected set of HTML elements. The current implementation targets those two platforms, with no additional adapters planned for now.

Supported syntax

  1. Basic syntax
    https://www.markdownguide.org/basic-syntax/

  2. Extended syntax
    https://www.markdownguide.org/extended-syntax/

Rendering result

iOS is shown on the left and Android on the right.

Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Rendering result (figure 1) Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Rendering result (figure 2)

Here are the demo videos:

How to use it

iOS

  1. Register ImageDownloader

Some images referenced by markdown need to be downloaded, but networking does not belong in the shared C++ rendering core. The SDK therefore exposes an ImageDownloaderDelegate interface. The host app implements that interface with its preferred networking and caching stack, then injects the downloader through the public API.

1
2
3
4
5
6
// an example of image downloader
@interface MyImageDownloader : NSObject<ImageDownloaderDelegate>
@end

// register image downloader
[MarkdownEngine registerImageDownloader:[MyImageDownloader new]];
  1. Set up the parameters
1
2
3
4
5
MarkdownParam *param = [[MarkdownParam alloc] init];
param.fontSize = 16.f;
param.fontName = @"PingFangSC";
param.content = @"[Markdown syntax](https://markdown.com.cn)";
param.maxWidth = [UIScreen mainScreen].bounds.size.width;
  1. Build the icon

We strongly recommend doing this step on an asynchronous thread.

1
MarkdownIcon *icon = [MarkdownEngine buildIconWithParam:param];
  1. Create MarkdownView and bind the icon to it
1
2
3
MarkdownView *view = [[MarkdownView alloc] initWithParam:param icon:icon];
view.frame = CGRectMake(0, 0, width, (icon ? icon.height : 0));
[self.view addSubview:view];

Android

  1. Initialize the library
1
MarkdownInitializer.init(Application.getInstance())
  1. Register imageLoader
1
2
3
4
5
6
7
8
9
// an example of IImageLoader
class MyMarkdownImageLoader : IImageLoader {
override fun load(imageview: ImageView, url: String, callback: ILoadResult?) {
// add custom handle for image
}
}

// register MyMarkdownImageLoader into HtmlEngine
MarkwonEngine.registerImageLoader(MyMarkdownImageLoader())
  1. Set up the parameters
1
2
3
4
val content = "[Markdown syntax](https://markdown.com.cn)"
val maxWidth = MDSize(screenWidth, TypedValue.COMPLEX_UNIT_PX)
val fontSize = MDSize(12F, TypedValue.COMPLEX_UNIT_DIP)
val param = MarkdownParam(content, maxWidth, fontSize)
  1. Build the icon
1
2
val iconBuilder = MarkdownIconBuilder(param)
val icon = iconBuilder.build()
  1. Bind the icon to MarkdownView
1
2
3
4
val view = findViewById(R.id.markdownView)
if (icon != null) {
view.bindMarkdownIcon(icon)
}

Implementation

Cross-platform foundation

Rendering eventually touches platform UI APIs, while the reusable parts of the problem, parsing and layout, are a better fit for portable C++. The design works by placing abstract drawing interfaces between those two worlds.

The C++ core lays out and paints content against abstract canvases, brushes, fonts, and views. Each platform adapter binds those interfaces to its native graphics stack only when measurement or drawing is required.

The advantages are:

  1. Both platforms can produce almost identical rendering results.
  2. Both platforms only need to develop and maintain one copy of the core logic.
  3. The portable core leaves room for additional platform adapters.

Of course, it also has drawbacks:

  1. The implementation requires solid C/C++ experience, and the learning curve is steeper than it is for most platform-native UI frameworks.
  2. The abstraction boundary hides some conveniences that native UI frameworks normally provide out of the box.

Architecture

The engine is divided into a platform-independent core and a thin platform layer:

  1. The blue area is the C++ core, responsible for parsing Markdown and producing layout and drawing operations.

    1. The third-party library md4c performs the actual markdown parsing.
    2. NodeTree, AtomTree, and BoxTree form the engine’s three-stage representation.
    3. Graphics2D and its supporting interfaces provide the platform-neutral drawing surface.
    4. BoxBreaker contains the line-breaking and layout rules.
  2. The orange area contains the iOS and Android adapters.

    1. The iOS adapter is implemented in Objective-C++.
    2. The Android adapter uses Kotlin and JNI.

A future Flutter adapter could call the C++ core directly through Dart FFI rather than routing rendering through iOS or Android platform channels.

Sequence diagram

The following sequence diagram uses Android as the example.

Building the Node tree

Why md4c?

There is no reason to write another Markdown parser from scratch. I chose md4c for four practical reasons:

  1. It conforms to CommonMark 0.30.
  2. It parses quickly.
  3. It is simple to use.
  4. It is portable.

Qt also uses md4c for Markdown parsing.

How to use md4c

md4c uses a push parser: it walks the document and invokes application callbacks when blocks or spans begin and end, and whenever it encounters text. The engine registers five callbacks for those events:

1
2
3
4
5
6
7
8
9
class MDParser  {
......
public:
static int enterBlock(MD_BLOCKTYPE type, void* detail, void* userdata);
static int leaveBlock(MD_BLOCKTYPE type, void* detail, void* userdata);
static int enterSpan(MD_SPANTYPE type, void* detail, void* userdata);
static int leaveSpan(MD_SPANTYPE type, void* detail, void* userdata);
static int foundText(MD_TEXTTYPE type, const MD_CHAR* text, MD_SIZE size, void* userdata);
}

The usage is straightforward: set parser flags and callbacks, then start parsing.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// MDParser.cpp
void MDParser::parse(const std::string& content) {
// support some commonly requested and accepted extensions
static unsigned parser_flags = MD_FLAG_TABLES | MD_FLAG_STRIKETHROUGH | MD_FLAG_PERMISSIVEAUTOLINKS | MD_FLAG_TASKLISTS;
MD_HTML render = { NULL, this, 0, 0, { 0 } };

// set callback for the MD_PARSER
MD_PARSER parser = {
0,
parser_flags,
supercast<int (*)(MD_BLOCKTYPE, void*, void*)>(&MDParser::enterBlock),
supercast<int (*)(MD_BLOCKTYPE, void*, void*)>(&MDParser::leaveBlock),
supercast<int (*)(MD_SPANTYPE, void*, void*)>(&MDParser::enterSpan),
supercast<int (*)(MD_SPANTYPE, void*, void*)>(&MDParser::leaveSpan),
supercast<int (*)(MD_TEXTTYPE, const MD_CHAR*, MD_SIZE, void*)>(&MDParser::foundText),
supercast<void (*)(const char*, void* )>(&MDParser::debugLog),
NULL
};

// start to parse
int ret = md_parse(input.c_str(), content.length, &parser, (void*)&render);

// error callback
this->parseErrorProcess(ret);
}

Markdown node definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// MDBaseNode.h
class MDBaseNode {
public:
MDBaseNode(const std::string& name, const std::map<std::string, std::string>& attributes = {}, std::shared_ptr<MDBuildParam> param = {});
~MDBaseNode();

void addChild(const std::shared_ptr<MDBaseNode>& child);
void removeChild(const std::shared_ptr<MDBaseNode>& child);
void removeAllChildren();

std::shared_ptr<MDBuildParam> mBuildParam;
std::weak_ptr<MDBaseNode> mParent;
std::vector<std::shared_ptr<MDBaseNode>> mChildren;
std::string mName;
std::map<std::string, std::string> mAttributes;
};

The SDK currently defines the following syntax-tree node types:

How to build the node tree

1
2
3
4
5
6
class MDParser  {
......
std::shared_ptr<MDBaseNode> mRootNode;
std::shared_ptr<MDBaseNode> mCurrentNode;
std::stack<std::shared_ptr<MDBaseNode>> mNodeStatck;
};

A stack turns md4c’s callback stream into a tree:

  1. enterBlock or enterSpan starts a node and pushes it onto the stack.
    1. The first node becomes mRootNode and never changes.
    2. mCurrentNode points to the stack top. A newly parsed node is attached to it, then becomes the new current node.

Using an unordered list as an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
int MDParser::enterBlock(MD_BLOCKTYPE type, void* detail, void* userdata) {

std::shared_ptr<MDBaseNode> node = nullptr;

static const MD_CHAR* head[6] = { "h1", "h2", "h3", "h4", "h5", "h6" };
MD_HTML* r = (MD_HTML*) userdata;
MDParser *parser = (MDParser *)(r->userdata);

switch(type) {
......
case MD_BLOCK_OL:
{
MD_BLOCK_OL_DETAIL *info = (MD_BLOCK_OL_DETAIL *)detail;
std::string delimiter = {info->mark_delimiter, '\0'};
int index = info->start;
bool isTight = info->is_tight;
node = std::make_shared<MDOlNode>("ol", std::map<std::string, std::string>{
{"delimiter", delimiter},
{"index", std::to_string(index)},
{"is_tight", std::to_string(isTight)}
});
break;
}
......
}

parser->pushNode(node);
}
1
2
3
4
5
6
7
8
9
10
11
void MDParser::pushNode(const std::shared_ptr<MDBaseNode> &node) {
if (mCurrentNode) {
mCurrentNode->addChild(node);
node->mParent = mCurrentNode;
mCurrentNode = node;
} else {
mRootNode = node;
mCurrentNode = node;
}
mNodeStatck.push(mCurrentNode);
}
  1. leaveBlock or leaveSpan completes the current node. The parser pops it, restores mCurrentNode to its parent, and verifies that the closing callback matches the node being removed.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
int MDParser::leaveBlock(MD_BLOCKTYPE type, void* detail, void* userdata)
{
if (type == MD_BLOCK_HTML) return 0;
std::string name = "";

static const MD_CHAR* head[6] = { "h1", "h2", "h3", "h4", "h5", "h6" };
switch(type) {
......
case MD_BLOCK_OL: name = "ol"; break;
......
}
std::shared_ptr<MDBaseNode> node = nullptr;
MD_HTML* r = (MD_HTML*) userdata;
MDParser *parser = (MDParser *)(r->userdata);
parser->popNode(name);
return 0;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
void MDParser::popNode(const std::string& name) {
assert(mNodeStatck.size() > 0);
if (mNodeStatck.size() == 0) {
std::string reason = "There is no node in mNodeStatck";
throw std::make_shared<md::Exception>("[Markdown ParseError]:" + reason);
} else {
auto& node = mNodeStatck.top();
if (node->getName() == name) {
mNodeStatck.pop();
mCurrentNode = mNodeStatck.size() > 0 ? mNodeStatck.top() : nullptr;
} else {
std::string reason = "the mNodeStatck top node isn't matching the name, maybe some of its parents matches";
throw std::make_shared<md::Exception>("[Markdown ParseError]:" + reason);
}
}
}
  1. foundText creates a leaf node and attaches it directly to the node at the top of the stack.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
int MDParser::foundText(MD_TEXTTYPE type, const MD_CHAR* text, MD_SIZE size, void* userdata) {
MD_HTML* r = (MD_HTML*) userdata;
MDParser *parser = (MDParser *)(r->userdata);
std::shared_ptr<MDBaseNode> node = nullptr;

switch(type) {
......
if (type == MD_TEXT_NORMAL) {
{
std::string content = std::string(text, text+size);
node = std::make_shared<MDTextNode>(content, std::map<std::string, std::string>{}, parser->mBuildParam);
break;
}
......
}
......
parser->addChildNode(node);
}
1
2
3
void MDParser::addChildNode(const std::shared_ptr<MDBaseNode>& node) {
mCurrentNode->addChild(node);
}

When md4c finishes, mRootNode owns the complete syntax tree.

How to handle HTML tags

Markdown may also contain inline HTML:

  1. md4c reports each HTML fragment as text rather than exposing its structure. A second parser must distinguish opening, closing, and self-closing elements such as <img/> and <br> and update the node stack accordingly.
  2. That parser must also extract element attributes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// MDParser.cpp
int MDParser::foundText(MD_TEXTTYPE type, const MD_CHAR* text, MD_SIZE size, void* userdata)
{
MD_HTML* r = (MD_HTML*) userdata;
MDParser *parser = (MDParser *)(r->userdata);
std::shared_ptr<MDBaseNode> node = nullptr;

if (type == MD_TEXT_HTML) {
std::string html = std::string(text, text+size);
parser->parseHtmlTag(html);
return 0;
}
......
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// MDParser.cpp
void MDParser::parseHtmlTag(const std::string& html) {
std::shared_ptr<HtmlTagBaseNode> node = nullptr;
HtmlTagParser tagParser(html);
if (tagParser.isSelfClosing()) {
// if tag is self closing, should call push and pop at the same time
node = tagParser.getNode();
if (node != nullptr) {
pushNode(node);
popNode(node->getName());
}
} else {
if (tagParser.isEndTag()) {
// if it is end tag, pop node
popNode(tagParser.tagName());
} else {
// if it is start tag, push node
node = tagParser.getNode();
pushNode(node);
}
}
}

HtmlTagParser handles that second parsing pass.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// HtmlTagParser.cpp
HtmlTagParser::HtmlTagParser(const std::string& text) : mText(text) {
const char *mTagName_begin = text.c_str();
const char *c = text.c_str() + (text.length() - 1);
++mTagName_begin;

// parse isEndTag
mIsEndTag = (*mTagName_begin == '/');
if (mIsEndTag) ++mTagName_begin;

// parse tagName
const char *mTagName_end = mTagName_begin;
while (mTagName_end != c && isalnum(*mTagName_end)) {
++mTagName_end;
}
mTagName = std::string(mTagName_begin, mTagName_end);

// parse isSelfClosing
mIsSelfClosing = (*(c-1) == '/') || mTagName == "hr";

// parse attributes
if (!mIsEndTag) {
parseAttributes();
}
}

The SDK currently supports these HTML elements:

Most HTML elements reuse existing Markdown nodes; superscript and subscript require dedicated node types.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// HtmlTagNodeAlias.h
typedef MDBaseNode HtmlTagBaseNode;
typedef MDBoldNode HtmlTagBoldNode;
typedef MDItalicNode HtmlTagItalicNode;
typedef MDULineNode HtmlTagULineNode;
typedef MDUlNode HtmlTagUlNode;
typedef MDLiNode HtmlTagLiNode;
typedef MDTableNode HtmlTagTableNode;
typedef MDTheadNode HtmlTagTheadNode;
typedef MDTbodyNode HtmlTagTbodyNode;
typedef MDTrNode HtmlTagTrNode;
typedef MDThNode HtmlTagThNode;
typedef MDTdNode HtmlTagTdNode;
typedef MDDelNode HtmlTagDelNode;
typedef MDHxxNode HtmlTagHxxNode;
typedef MDBrNode HtmlTagBrNode;
typedef MDHrNode HtmlTagHrNode;

How to handle HTML entities

HTML entities may also appear in Markdown input. The parser decodes them before layout and stores the resulting Unicode text in MDTextNode objects.

1
&#8377;&nbsp;&#39;&minus;&alpha;&rArr;&beta;&there4;&ndash;&rsquo;&gamma;&amp;&radic;&ne;&times;&lsquo;&quot;&sup2;&plusmn;&hellip;&le;&ge;&divide;&lambda;&deg;&mdash;&frac12;&OQ&Hints&ordm;&sup3;&shy;&pi;&ang;&Delta;&perp;&ldquo;&rdquo;&middot;&sim;&rarr;&theta;&prime;&bdquo;&sum;&asymp;&cong;&thinsp;&sdot;&spades;&hearts;&diams;&clubs;&phi;&isin;&forall;&notin;&Prime;&lowast;&or;&and;&cup;&delta;&cap;&frac14;&sub;&mu;&int;&aelig;&ouml;&para;&plusmn;&pm;&pound;&raquo;&reg;&sect;&strns;&sup1;&sup2;&sup3;&szlig;&thorn;&times;&uacute;&ucirc;&ugrave;&uml;&uuml;&yacute;&yen;&yuml;
1
2
3
4
5
6
7
8
9
10
11
12
// MDParser.cpp
int MDParser::foundText(MD_TEXTTYPE type, const MD_CHAR* text, MD_SIZE size, void* userdata)
{
switch(type) {
case MD_TEXT_ENTITY:
{
std::string entity = parse_entity(r, text, size);
node = std::make_shared<MDTextNode>(entity, std::map<std::string, std::string>{}, parser->mBuildParam);
break;
}
......
}

Entity parsing has a few edge cases. The following code shows the core approach:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// MDParser.cpp
static std::string parse_entity(MD_HTML* r, const MD_CHAR* text, MD_SIZE size)
{
if(r->flags & MD_HTML_FLAG_VERBATIM_ENTITIES) {
return std::string(text, size);
}

/* We assume UTF-8 output is what is desired. */
if(size > 3 && text[1] == '#') {
unsigned codepoint = 0;

if(text[2] == 'x' || text[2] == 'X') {
/* Hexadecimal entity (e.g. "&#x1234abcd;")). */
MD_SIZE i;
for(i = 3; i < size-1; i++)
codepoint = 16 * codepoint + hex_val(text[i]);
} else {
/* Decimal entity (e.g. "&1234;") */
MD_SIZE i;
for(i = 2; i < size-1; i++)
codepoint = 10 * codepoint + (text[i] - '0');
}
return parse_utf8_codepoint(r, codepoint);
} else {
/* Named entity (e.g. "&nbsp;"). */
const struct entity* ent;

ent = entity_lookup(text, size);
if(ent != NULL) {
std::string ret = parse_utf8_codepoint(r, ent->codepoints[0]);
if(ent->codepoints[1])
ret += parse_utf8_codepoint(r, ent->codepoints[1]);
return ret;
}
}

return std::string(text, size);
}

After parsing, the display result looks like this:

1
₹ '−α⇒β∴–’γ&√≠ב"²±…≤≥÷λ°—½&OQ&Hintsº³­π∠Δ⊥“”·∼→θ′„∑≈≅ ⋅♠♥♦♣φ∈∀∉″∗∨∧∪δ∩¼⊂μ∫æö¶±±£»®§¯¹²³ßþ×úûù¨üý¥ÿ

Example

The following fixture intentionally keeps Chinese text. It is not untranslated body copy; it is test data for CJK typography, inline HTML, emoji, entities, and the node/atom/box trees generated from non-Latin text:

1
2
3
4
5
6
测试列表
- 粗体、*斜体*、*粗斜体*
- 链接:[www.baidu.com](www.baidu.com)
- 上角标<sup>TM</sup>和下角标<sub>AT</sub>
- emoji表情:😀😃😄😁
- html实体:&minus;&alpha;&rArr;&beta;

For this markdown text, the generated node tree looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
MDDocNode
├───MDParagraphNode
│ └──MDTextNode (测试列表)
└───MDUlNode
├──MDLiNode
│ ├──MDBoldNode
│ │ └──MDTextNode (粗体)
│ ├──MDTextNode (、)
│ ├──MDItalicNode
│ │ └──MDTextNode (斜体)
│ ├──MDTextNode (、)
│ └──MDItalicNode
│ └──MDBoldNode
│ └──MDTextNode (粗斜体)
├──MDLiNode
│ ├──MDTextNode (链接:)
│ └──MDHrefNode
│ └──MDTextNode (www.baidu.com)
├──MDLiNode
│ ├──MDTextNode (上角标)
│ ├──HtmlTagSupNode
│ │ └──MDTextNode (TM)
│ ├──MDTextNode (和下角标)
│ └──HtmlTagSupNode
│ └──MDTextNode (AT)
├──MDLiNode
│ └──MDTextNode (emoji表情:😀😃😄😁)
└──MDLiNode
├──MDTextNode (html实体:)
├──MDTextNode (&minus;)
├──MDTextNode (&alpha;)
├──MDTextNode (&rArr;)
└──MDTextNode (&beta;)

Building the Atom tree

After recursive descent produces the syntax tree, the engine converts it into an Atom tree. Most Node types map to an Atom, although the relationship is not strictly one-to-one.

Atom assembly rules

Atoms preserve the hierarchy of the syntax tree. A node usually produces either one Atom or a RowAtom containing several children, and those children may themselves contain nested atoms.

Each Node has a virtual getAtom method. The base implementation in MDBaseNode looks like this:

1
2
3
4
5
6
7
8
9
// MDBaseNode.cpp
std::shared_ptr<Atom> MDBaseNode::getAtom() {
std::vector<std::shared_ptr<Atom>> atoms;
for(auto& node : mChildren) {
atoms.push_back(node->getAtom());
}
std::shared_ptr<RowAtom> rowAtom = std::make_shared<RowAtom>(atoms);
return rowAtom;
}

Pure container nodes such as MDDocNode and MDParagraphNode can inherit the default implementation. Nodes with formatting or structural semantics override getAtom.

For example, MDBoldNode::getAtom wraps each child atom in a BoldAtom, then combines the results in a RowAtom.

1
2
3
4
5
6
7
8
9
10
// MDBoldNode.cpp
std::shared_ptr<Atom> MDBoldNode::getAtom() {
std::vector<std::shared_ptr<Atom>> atoms;
for(auto& node : this->mChildren) {
std::shared_ptr<BoldAtom> boldAtom = std::make_shared<BoldAtom>(node->getAtom());
atoms.push_back(boldAtom);
}
std::shared_ptr<RowAtom> rowAtom = std::make_shared<RowAtom>(atoms);
return rowAtom;
}

Some nodes have more complex rules. For example, MDTableNode::getAtom extracts its children and grandchildren and reassembles them into an MDTableAtom.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// MDTableNode.cpp
std::shared_ptr<Atom> MDTableNode::getAtom() {
std::vector<std::shared_ptr<Atom>> headCells;
std::vector<std::vector<std::shared_ptr<Atom>>> bodyCells;
std::vector<Align> aligns;

std::vector<std::shared_ptr<Atom>> atoms;
assert(mChildren.size() == 2);
std::shared_ptr<MDTheadNode> thead = std::static_pointer_cast<MDTheadNode>(mChildren[0]);
std::shared_ptr<MDTbodyNode> body = std::static_pointer_cast<MDTbodyNode>(mChildren[1]);
for(auto& node : thead->mChildren[0]->mChildren) {
std::shared_ptr<MDThNode> thNode = std::static_pointer_cast<MDThNode>(node);
aligns.push_back(thNode->align);
headCells.push_back(node->getAtom());
}
for(auto& tr : body->mChildren) {
std::vector<std::shared_ptr<Atom>> rows;
for (auto& td : tr->mChildren) {
rows.push_back(td->getAtom());
}
bodyCells.push_back(rows);
}
std::shared_ptr<Atom> atom = std::make_shared<MDTableAtom>(aligns, headCells, bodyCells);
return atom;
}

Example

Continuing with the node tree above, the generated Atom tree looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
RowAtom
├───ForceBreakMarkAtom
├───FontRenderingAtom (测)
├───FontRenderingAtom (试)
├───FontRenderingAtom (列)
├───FontRenderingAtom (表)
├───ForceBreakMarkAtom
├───MDListAtom
│ ├───MDLiAtom
│ │ │───BoldAtom
│ │ │ └───RowAtom
│ │ │ ├───FontRenderingAtom (粗)
│ │ │ └───FontRenderingAtom (体)
│ │ │───FontRenderingAtom (、)
│ │ │───ItAtom
│ │ │ └───RowAtom
│ │ │ ├───FontRenderingAtom (斜)
│ │ │ └───FontRenderingAtom (体)
│ │ │───FontRenderingAtom (、)
│ │ └───ItAtom
│ │ └───BoldAtom
│ │ └───RowAtom
│ │ ├───FontRenderingAtom (粗)
│ │ ├───FontRenderingAtom (斜)
│ │ └───FontRenderingAtom (体)
│ └───...
└───ForceBreakMarkAtom

Building the Box tree

Each Atom produces one or more layout boxes through the base class’s virtual createBox method:

1
2
3
4
5
// Atom.h
class Atom : public std::enable_shared_from_this<Atom> {
public:
virtual std::shared_ptr<Box> createBox(const std::shared_ptr<Environment>& env) = 0;
};

A Box is a measurable drawing unit with four key properties:

1
2
3
4
5
6
7
class Box : public std::enable_shared_from_this<Box> {
public:
double width = 0;
double height = 0;
double depth = 0;
double shift = 0; // baseline
};

Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Building the Box tree (figure 3)

Because the previous step produced an n-ary tree of Atoms, createBox also works recursively: each child generates its own Box, and the current node combines those boxes according to its layout rules. The boxes are aligned around their baseline values and eventually form an n-ary tree that mirrors the Atom tree.

Example

Continuing with the previous Atom tree, the generated Box tree looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
HorizontalBox
├───FontRenderingBox (测)
├───FontRenderingBox (试)
├───FontRenderingBox (列)
├───FontRenderingBox (表)
├───VerticalBox
│ ├───HorizontalBox
│ │ ├───FontRenderingBox (●)
│ │ ├───StrutBox
│ │ └───HorizontalBox
│ │ ├───HorizontalBox
│ │ │ ├───FontRenderingBox(粗)
│ │ │ └───FontRenderingBox(体)
│ │ ├───FontRenderingBox (、)
│ │ ├───HorizontalBox
│ │ │ ├───FontRenderingBox(斜)
│ │ │ └───FontRenderingBox(体)
│ │ ├───FontRenderingBox (、)
│ │ └───HorizontalBox
│ │ ├───FontRenderingBox(粗)
│ │ ├───FontRenderingBox(斜)
│ │ └───FontRenderingBox(体)
└───StrutBox

The debug grid in the rendered output makes the final Box boundaries visible.

image%203.png

Layout

The previous stages produce an n-ary Box tree in the C++ core. Before those boxes can be painted onto the abstract canvas, the layout engine must assign each one a final position.

Streaming Box splitting

Markdown content follows a flow layout, but every line has a finite width. The first layout problem is therefore deciding where the Box tree can be split to wrap onto the next line.

image%2011.png

Assume the figure is the Box tree:

  1. The white node is root.
  2. The light-blue node is the first child.
  3. The orange-red node is the second child, and it has three child nodes: yellow, sky blue, and purple.
  4. The blue node is the third child.

Suppose the first line ends inside the orange-red subtree. Because that node has children, the algorithm descends into it: the yellow child fits, the purple child does not, and the leaf-level sky-blue node must report whether it can be split internally.

  1. If it cannot be split, the result may look like this:

image%2018.png

  1. If it can be split, the layout may look like this:

image%2019.png

The orange-red node disappears from the split result because it is only a container; its children define all of its geometry. If the sky-blue node also has children, the algorithm descends again and continues until it reaches a valid break point or fills the line.

Pre-layout inside block elements

Block elements such as tables, lists, and quotes occupy a full line in the outer flow, but their contents may still wrap internally. They therefore perform an internal layout pass before they enter the outer line-breaking algorithm.

  1. Quote

Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Pre-layout inside block elements (figure 8)

In the quote example, the gray rule and the gap beside it consume part of the available width. The quote lays out its text against the remaining width, then sizes the rule to the resulting text height.

1
2
3
4
5
6
7
8
9
10
11
12
13
std::shared_ptr<Box> MDQuoteAtom::createBox(const std::shared_ptr<Environment>& env) {
std::vector<std::shared_ptr<Box>> boxes;
auto env0 = env->copy();
env0->setWidth(env->getWidth() - 1.f);
double baselineskip = env->getLineSpace();
for (auto& atom : atoms) {
auto box = atom->createBox(env0);
box = BoxBreaker::split(box, env0->getWidth(), baselineskip, Align::LEFT);
boxes.push_back(box);
}
std::shared_ptr<Box> box = std::make_shared<MDQuoteBox>(boxes);
return box;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
MDQuoteBox::MDQuoteBox(const std::vector<std::shared_ptr<Box>>& boxes) : boxes(boxes) {
std::shared_ptr<VerticalBox> vb = std::make_shared<VerticalBox>();
vb->add(std::make_shared<StrutBox>(0, 0.4f, 0, 0), true);
for(auto& box : boxes) {
box->setFg(graphics->createColor(153, 153, 153));
vb->add(box, true);
vb->add(std::make_shared<StrutBox>(0, 0.4f, 0, 0), true);
}

std::shared_ptr<HorizontalBox> hb = std::make_shared<HorizontalBox>();

// add the vertical gray line through VerticalRule
auto vr = std::make_shared<VerticalRule>(0.2f, vb->getHeight()+vb->getDepth(), 0.f);
vr->setBg(graphics->createColor(223, 226, 229));
hb->add(vr);

// add the white space through StrutBox
hb->add(std::make_shared<StrutBox>(0.8f, 0, 0, 0));
hb->add(vb);

// add the right content
this->base = std::make_shared<VerticalBox>(hb);

// update width and height
this->setWidth(base->getWidth());
this->setHeight(base->getHeight() + base->getDepth());
}
  1. Table

Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Pre-layout inside block elements (figure 9)

Table layout is more complex:

  1. Determine the natural width of each column and compare their sum with the available table width:

    1. Calculate the maximum width of each column.
    2. Sum all column widths.
      1. If the columns already fit, keep their natural widths.
      2. Otherwise, shrink them proportionally to fit the available width.
    3. Reflow each cell against its final column width.
  2. Apply the left, center, or right alignment parsed from the Markdown table definition.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
std::shared_ptr<Box> MDTableAtom::createBox(const std::shared_ptr<Environment>& env) {
......
// relayout
double baselineskip = env->getLineSpace();

for (int i = 0; i < rows + 1; ++i) {
for (int j = 0; j < cols; ++j) {
double columnWidth = columnFinalWidths[j];
boxMatrix[i][j] = BoxBreaker::split(boxMatrix[i][j], columnWidth, baselineskip, aligns[j]);
double delta = columnWidth - boxMatrix[i][j]->getWidth();
std::shared_ptr<HorizontalBox> hb = std::make_shared<HorizontalBox>();
if (aligns[j] == Align::LEFT) {
hb->add(boxMatrix[i][j]);
hb->add(std::make_shared<StrutBox>(delta,0,0,0));
} else if (aligns[j] == Align::CENTER) {
hb->add(std::make_shared<StrutBox>(delta * 0.5,0,0,0));
hb->add(boxMatrix[i][j]);
hb->add(std::make_shared<StrutBox>(delta * 0.5,0,0,0));
} else {
hb->add(std::make_shared<StrutBox>(delta,0,0,0));
hb->add(boxMatrix[i][j]);
}
boxMatrix[i][j] = hb;
rowFinalHeights[i] = fmax(rowFinalHeights[i], boxMatrix[i][j]->getHeight() + boxMatrix[i][j]->getDepth());
}
}

std::shared_ptr<Box> box = std::make_shared<MDTableBox>(boxMatrix, rowFinalHeights, columnFinalWidths);
return box;
}

Inline alignment

Inline content supports left, right, center, and justified alignment:

  1. For left alignment, calculate the right-side blank space and fill it with a StrutBox.
  2. For right alignment, calculate the left-side blank space and fill it with a StrutBox.
  3. For center alignment, calculate blank space on both sides and fill it with StrutBoxes.
  4. For justified alignment, distribute the remaining width between neighboring boxes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
double rest = w - b->getWidth();
if (rest > 0) {
if (alignment == Align::CENTER || alignment == Align::NONE) {
std::shared_ptr<StrutBox> s = std::make_shared<StrutBox>(rest / 2, 0.0, 0.0, 0.0);
add(s);
add(b);
add(s);
} else if (alignment == Align::LEFT) {
add(b);
add(std::make_shared<StrutBox>(rest, 0.0, 0.0, 0.0));
} else if (alignment == Align::RIGHT) {
add(std::make_shared<StrutBox>(rest, 0.0, 0.0, 0.0));
add(b);
} else if (alignment == Align::JUSTIFIED) {
if (std::dynamic_pointer_cast<HorizontalBox>(b) != nullptr) {
auto hb = std::static_pointer_cast<HorizontalBox>(b);
int childrenCount = (int)hb->children.size();
if (rest < SINGLE_TEXT_WIDTH && childrenCount > 1) {
double splitWidth = rest / (hb->children.size() - 1);
for (int i = 0; i < childrenCount; ++i) {
add(hb->children[i]);
if (i != childrenCount - 1) {
add(std::make_shared<StrutBox>(splitWidth, 0.0, 0.0, 0.0));
}
}
} else {
add(b);
}
} else {
add(b);
}
}
}

Layout rules: details matter

Text layout also needs language-aware break rules. Here those rules operate on a nested Box tree rather than a flat character stream, so the engine must preserve semantic groups while searching for break points.

  1. Chinese characters are all potential line-break points.
  2. Punctuation that must avoid line start or line end is not a line-break point.
  3. Consecutive em dashes are not line-break points.
  4. Spaces are line-break points.
  5. English words are not line-break points.
  6. Some English punctuation marks are not line-break points.
Keeping punctuation groups together

The following sequences are treated as indivisible units during line breaking:

  1. Em dashes: ––
  2. Ellipses: …... and ······
  3. Straight double quotes: "xxx", where xxx is one English word.
  4. Abbreviations such as I'm and You're.

MDTextNode groups these sequences before layout so the line breaker sees each one as a single unit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
std::shared_ptr<Atom> MDTextNode::getAtom() {
......
for(int i = 0; i < totalLength; ++i) {
wchar_t curChar = content[i];
// strategy 1, not cut words when wrapping
if (mBuildParam->splitStyle == SplitStyle::WORD) {
if (curChar == L'.' || curChar == L'·' || curChar == L'–') {
/// Prohibition Rules for Unbreakable Marks:
/// 1. Two-em dashes show a continuation of tone or sound, an abrupt change in thought, or adding new content to the context, appearing as a horizontally and vertically centered line, and take 2 em
/// 2. Ellipses are used to indicate a truncation of text, an unfinished sentence or a break in speech. An ellipsis in Chinese consists of six dots, takes up the space of two Hanzi characters, and is horizontally and vertically centered within its character frame.
int start = i;
while (i < totalLength && content[i] == content[start]) ++i;
wordTemp = content.substr(start, i - start);
--i;
} else if (curChar == L'"') {
/// Straight double quote
/// "xxx", When xxx is a pure word instead of a phrase, we want them to be bound together
int start = i, j = i + 1;
while (j < totalLength && (isalpha(content[j]) || isdigit(curChar)) ) ++j;
if (content[j] == L'"') {
wordTemp = content.substr(start, j - start + 1);
i = j + 1;
} else {
wordTemp = curChar;
}
} else if (curChar == L'\u0027') {
// Process abbreviation such as I'm, you're etc.
int k = i - 1, j = i + 1;
if (k >= 0 && isalpha(content[k]) && j < totalLength && isalpha(content[j])) {
atoms.pop_back();
while (j < totalLength && isalpha(content[j])) ++j;
while (k >= 0 && isalpha(content[k])) --k;
wordTemp = content.substr(k + 1, j - k - 1);
i = j - 1;
} else {
wordTemp = curChar;
}
} else {
wordTemp = curChar;
}

addTextAtom(atoms, wordTemp, font, splitStyle);
}
......
Line-start and line-end punctuation rules

To keep reading smooth and consistent, most punctuation marks have positional restrictions. Depending on their type, a punctuation mark may be forbidden at the start or end of a line:

  1. Pause marks, commas, periods, colons, semicolons, exclamation marks, question marks, closing quotes, closing brackets, closing book-title marks, hyphens, middle dots, and separators should not appear at the beginning of a line.
  2. Opening quotes, opening brackets, and opening book-title marks should not appear at the end of a line.

Which punctuation marks need these rules?

Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Layout rules: details matter (figure 10)

Figure source: https://www.zcool.com.cn/article/ZMTE5NjYwOA==.html#kuak

Push-out vs prefer-push-in punctuation handling
Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Layout rules: details matter (figure 11) Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: Layout rules: details matter (figure 12)

Both figures are from: https://www.zcool.com.cn/article/ZMTE5NjYwOA==.html#kuak

  1. “Push-out” handling is what most layout systems do. For punctuation that cannot appear at the start of a line, if it is placed at line start, the system pulls one character from the previous line into the current line. This enlarges character spacing on the previous line and interrupts the reading rhythm, as shown on the left.
  2. “Prefer-push-in” handling compresses the punctuation width inside the current line to make room for the comma that otherwise would not fit. This keeps character spacing stable. Only when the punctuation on the current line cannot be compressed enough does it fall back to push-out behavior, as shown on the right.
Leading-space handling

Sometimes whitespace appears at the beginning of a line. In that case, leading whitespace should be removed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// LayoutRuler.cpp
void LayoutRuler::applyLeadingSpaceBoxesRule(const std::shared_ptr<Box>& currentBox, const std::shared_ptr<HorizontalBox>& parentBox) {
std::stack<Box> stack;
if (currentBox->isType<FontRenderingBox>()) {
std::shared_ptr<FontRenderingBox> frb = currentBox->typeValue<FontRenderingBox>();
if (frb->getRawContent() == L" ") {
auto& children = parentBox->getChildren();
for(auto& childBox : children) {
if (childBox->isType<FontRenderingBox>()) {
std::shared_ptr<FontRenderingBox> frb = childBox->typeValue<FontRenderingBox>();
if (frb->getRawContent() == L" ") {
childBox = std::make_shared<StrutBox>();
} else {
break;
}
} else {
break;
}
}
}
} else if (currentBox->isType<HorizontalBox>()) {
std::shared_ptr<HorizontalBox> hb = currentBox->typeValue<HorizontalBox>();
auto& children = hb->getChildren();
if (children.size() > 0) {
std::shared_ptr<Box>& fb = children[0];
applyLeadingSpaceBoxesRule(fb, hb);
}
}
}
Punctuation width adjustment
Consecutive punctuation

Regardless of the overall text style, when annotation punctuation is adjacent to other punctuation, or when annotation punctuation repeats, spacing should be adjusted to make text more compact and readable. In principle, if two adjacent punctuation marks occupy two character widths, they should be reduced to 1.5 character widths. On that basis, a style may further compress them to one character width. The compression direction should make opening and closing annotation marks stay close to the content they annotate.

The detailed compression rules are:

  1. If a closing annotation mark is followed by an opening annotation mark, another closing annotation mark, a pause mark, comma, period, colon, or semicolon, squeeze it.
  2. If an opening annotation mark is followed by another opening annotation mark, squeeze it.
  3. If a pause mark, comma, or period is followed by an opening or closing annotation mark, squeeze it.
  4. If a semicolon or colon is followed by an opening annotation mark, squeeze it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
void LayoutRuler::applySqueezeRulesOfAdjacentPunctuation(const std::shared_ptr<HorizontalBox>& root) {
std::stack<std::shared_ptr<Box>> s;
s.push(root);
std::shared_ptr<Box> p = nullptr, pre = nullptr;
while(!s.empty()) {
// remember the last node
pre = p;

// get the current node
p = s.top(); s.pop();

// deal the current node if needed
if (pre && pre->isType<FontRenderingBox>() && p->isType<FontRenderingBox>()) {
std::shared_ptr<FontRenderingBox> preFrb = pre->typeValue<FontRenderingBox>();
std::shared_ptr<FontRenderingBox> pFrb = p->typeValue<FontRenderingBox>();
wchar_t preChar = preFrb->getRawContent().back();
wchar_t pChar = pFrb->getRawContent().front();
if (isEndBracketPunctuation(preChar)) {
if (isBeginBracketPunctuation(pChar) || isEndBracketPunctuation(pChar) ||
pChar == L'、' || pChar == L',' || pChar == L'。' || pChar == L':') {
preFrb->setMode(FontRenderingMode::KeepLeft);
}
} else if (isBeginBracketPunctuation(preChar) && isBeginBracketPunctuation(pChar)) {
preFrb->setMode(FontRenderingMode::KeepLeft);
} else if (preChar == L'、' || preChar == L',' || preChar == L'。') {
if (isBeginBracketPunctuation(pChar) || isEndBracketPunctuation(pChar)) {
preFrb->setMode(FontRenderingMode::KeepLeft);
}
} else if (preChar == L':' || preChar == L';') {
if (isBeginBracketPunctuation(pChar)) {
preFrb->setMode(FontRenderingMode::KeepLeft);
}
}
}

// push the child nodes in reverse order
if (p->isType<HorizontalBox>()) {
auto& children = p->typeValue<HorizontalBox>()->getChildren();
for (int i = (int)children.size() - 1; i >= 0; --i) {
s.push(children[i]);
}
}
}
}
Line-start and line-end punctuation compression

When punctuation appears at the start or end of a line, the following spacing rules make the text more compact and readable:

  1. If an opening annotation mark appears at the start of a line, half a Han-character width can be removed from its leading side.
  2. If punctuation that originally occupies one character width appears at the end of a line, half a Han-character width can be removed from its trailing side.

RTL support

Right-to-left languages such as Arabic and Hebrew reverse the direction of both reading and many UI layouts. Since iOS 9, UIKit has supported this through semantic content attributes and direction-aware leading and trailing anchors.

Mirroring an entire window is not sufficient because text glyphs themselves must remain readable. UIKit therefore treats controls such as UILabel and UITextView as non-flippable and applies bidirectional text rules inside them.

The custom renderer must provide the equivalent behavior itself:

  1. Resolve bidirectional text within each paragraph instead of mirroring glyphs.
  2. Mirror the structure and alignment of block elements such as quotes, tables, and lists.

In the diagrams, the left side shows the Markdown engine without processing, while the right side shows the correct display after processing.

Usage
1
2
3
4
5
6
7
8
9
MarkdownParam *param = [[MarkdownParam alloc] init];
......
// Set enableSemanticContentRightToLeft to YES to support RTL
param.enableSemanticContentRightToLeft = YES;

// In most cases, align should be MarkdownAlignNatural:
// left-aligned in LTR and right-aligned in RTL.
// But this is not mandatory; LTR can still be right-aligned, and RTL can still be left-aligned.
param.align = MarkdownAlignNatural;
Text

For each paragraph, the engine uses the first character to determine the layout direction. For example, "مرحبا 你好" starts with Arabic, so RTL rules are used. Similarly, "你好 مرحبا" starts with Chinese, so LTR rules are used.

  1. If LTR rules are used, scan each line for RTL ranges and reverse the RTL text inside those ranges.
  2. If RTL rules are used:
    1. Scan each line for RTL ranges and reverse the RTL text inside them.
    2. Scan each line for LTR ranges, and move trailing punctuation and spaces in each LTR range to the beginning of that range.
    3. Use the scanned ranges as units and perform cyclic shifting.
Quote
  1. The gray vertical line should be laid out on the right.
  2. The text inside should be right-aligned as a whole.
Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 13) Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 14)
List

For lists:

  1. The bullet should be laid out on the right.
  2. The text should be right-aligned as a whole.
Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 15) Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 16)
Table

For tables:

  1. RTL tables should first be aligned to the right as a whole.
  2. Table columns should also be ordered from right to left. For example, the first numeric column in LTR becomes the third column in RTL.
  3. Alignment rules must also be adapted. Left alignment in LTR becomes right alignment in RTL.
Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 17) Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android: RTL support (figure 18)

Event interaction

Tap events

Links and other interactive elements need hit testing even though most rendered content has no native control behind it. The engine handles this by storing event metadata on boxes and searching the tree recursively for the box at a touch coordinate.

hitTest

Define hitTest on the base Box class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Box.h
class Box : public std::enable_shared_from_this<Box> {
public:
virtual std::shared_ptr<Box> hitTest(const std::shared_ptr<Point2D>& point);
}

// Box.cpp
std::shared_ptr<Box> Box::hitTest(const std::shared_ptr<Point2D>& point) {
double px = point->getX();
double py = point->getY();
if (px > x && px < x + width && py > y - height && py < y + getDepth()) {
return shared_from_this();
}
return nullptr;
}

Subclasses can override hitTest:

1
2
3
4
5
6
7
8
9
10
11
// HorizontalBox.cpp
std::shared_ptr<Box> HorizontalBox::hitTest(const std::shared_ptr<Point2D>& point) {
std::shared_ptr<Box> box = Box::hitTest(point);
if (box) {
for(auto& cb : getChildren()) {
box = cb->hitTest(point);
if (box) return box;
}
}
return nullptr;
}
Binding event information

Interactive nodes carry an AreaInfo object containing the event type and payload. MDHrefNode, for example, attaches that metadata to its atoms, which propagate it to the generated boxes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
std::shared_ptr<Atom> MDHrefNode::getAtom() {
std::shared_ptr<AreaInfo> areaInfo = std::make_shared<AreaInfo>();
areaInfo->type = AreaTypeHref;
areaInfo->info = mAttributes;

std::vector<std::shared_ptr<Atom>> atoms;
for (auto& node : mChildren) {
std::shared_ptr<Atom> atom = node->getAtom();
if (std::dynamic_pointer_cast<RowAtom>(atom) != nullptr) {
std::shared_ptr<RowAtom> ra = std::static_pointer_cast<RowAtom>(atom);
for (auto& a : ra->getElements()) {
a->areaInfo = areaInfo;
}
}
std::shared_ptr<ColorAtom> ca = std::make_shared<ColorAtom>(atom, nullptr, Colors::Instance().getFromRGB(63, 92, 212));
atoms.push_back(ca);
}
return std::make_shared<RowAtom>(atoms);
}
1
2
3
4
5
void FontRenderingAtom::addTexBox(SplitStyle splitStyle, std::shared_ptr<HorizontalBox>& hb, const std::wstring &str, int style, double factor, const std::shared_ptr<Font>& font, bool kerning) {
std::shared_ptr<Box> box = std::make_shared<FontRenderingBox>(str, style, factor, font, kerning);
box->areaInfo = areaInfo;
hb->add(box);
}
Finding event information by coordinate

When a touch arrives, Icon finds the smallest indivisible box containing that point. If the box carries AreaInfo, the renderer forwards the event payload to its delegate.

1
2
3
4
5
std::shared_ptr<AreaInfo> Icon::getAreaInfo(const std::shared_ptr<Point2D>& point) {
std::shared_ptr<Box> b = box->hitTest(point);
if (!b || !b->areaInfo) return nullptr;
return b->areaInfo;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
CGPoint loc = [[touches anyObject] locationInView:self];
std::shared_ptr<Point2D_iOS> point = std::make_shared<Point2D_iOS>(loc.x / _param.fontSize, loc.y / _param.fontSize);
std::shared_ptr<AreaInfo> eventInfo = _icon->getAreaInfo(point);

NSDictionary *info = nil;
MarkdownAreaType type = MarkdownAreaTypeNone;
if (eventInfo != nullptr) {
switch (eventInfo->type) {
case AreaTypeHref: {
NSString *url = str2nsstr(eventInfo->info["href"]);
info = @{@"url" : url ?: @""};
type = MarkdownAreaTypeHref;
break;
}
case AreaTypeImage: {
NSString *url = str2nsstr(eventInfo->info["src"]);
info = @{@"url" : url ?: @""};
type = MarkdownAreaTypeImage;
}

default:
break;
}
}

if (type != MarkdownAreaTypeNone && [self.delegate respondsToSelector:@selector(markdownView:didSelectAreaWithType:info:)]) {
[self.delegate markdownView:self didSelectAreaWithType:type info:info];
} else {
[super touchesBegan:touches withEvent:event];
}
}

Region selection

A native rich-text view also needs text selection. Because this renderer owns its layout tree, it cannot delegate selection to UILabel or UITextView; it must map the user’s gesture back to boxes and draw the selected range itself.

Long press to determine start and end points

A long press starts selection. As the gesture changes, the view tracks the anchor and extent; when the gesture ends, those points define the initial selected range.

1
2
3
4
5
6
7
8
9
10
11
12
- (void)handleLongPress:(UILongPressGestureRecognizer *)gestureRecognizer {
CGPoint point = [gestureRecognizer locationInView:gestureRecognizer.view];
if (gestureRecognizer.state == UIGestureRecognizerStateBegan) {
[self.selectView fireEvent:MarkdownSelectEventStartSelection info:@{@"point" : @(point)}];
} else if (gestureRecognizer.state == UIGestureRecognizerStateChanged) {
[self.selectView fireEvent:MarkdownSelectEventChangeSelection info:@{@"point" : @(point)}];
} else if (gestureRecognizer.state == UIGestureRecognizerStateEnded) {
[self.selectView fireEvent:MarkdownSelectEventFinishSelection info:@{@"point" : @(point)}];
} else if (gestureRecognizer.state == UIGestureRecognizerStateCancelled) {
[self.selectView fireEvent:MarkdownSelectEventCancelSelection info:@{@"point" : @(point)}];
}
}
Modifying start and end points

Afterward, the user can drag either handle to adjust the range.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
CGPoint point = [[touches anyObject] locationInView:self];
if (self.selectView.isSelecting) {
[self.selectView fireEvent:MarkdownSelectEventWillModifySelection info:@{@"point" : @(point)}];
return;
}
......
}

- (void)touchesMoved:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
CGPoint point = [[touches anyObject] locationInView:self];
[self.selectView fireEvent:MarkdownSelectEventModifySelection info:@{@"point" : @(point)}];
}

- (void)touchesEnded:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
CGPoint point = [[touches anyObject] locationInView:self];
[self.selectView fireEvent:MarkdownSelectEventDidModifySelection info:@{@"point" : @(point)}];
}

- (void)touchesCancelled:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
CGPoint point = [[touches anyObject] locationInView:self];
[self.selectView fireEvent:MarkdownSelectEventCancelSelection info:@{@"point" : @(point)}];
}
Determining the region from start and end points

The raw gesture points do not yet define a reliable selection rectangle.

If the start point is sp and the end point is ep, the orange area is the rectangle between them, while the light-green cells represent text boxes. A purely geometric containment test excludes some boxes that users would expect to be selected, so the raw coordinates need to be adjusted before hit testing.

Instead, the engine snaps each endpoint to the box it hits:

  1. Set the top-left coordinate of the start box as the new start point.
  2. Set the bottom-right coordinate of the end box as the new end point.

Multi-line selection needs one more step. Rather than classify every box by line, the engine constructs one enclosing rectangle and subtracts the two corner regions that lie outside the logical range:

  1. S1 is the rectangle spanning the adjusted start and end boxes.
  2. S2 and S3 are the unused corner regions introduced by that rectangle.
  3. A box is selected when it falls inside S1 but outside both S2 and S3.

The same test works for both single-line and multi-line ranges.

Calculating contained elements from a region

After determining the region, the engine walks the n-ary Box tree in preorder and finds the boxes inside it. Their coordinates can then be converted and drawn directly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
std::vector<std::shared_ptr<Box>> Icon::getSelectedBoxes(const std::shared_ptr<Point2D>& sp, const std::shared_ptr<Point2D>& ep, double lineHeight) {
std::vector<std::shared_ptr<Box>> result;
Rect r0, r1, r2;

r0 = {0.f, sp->getY(), box->getWidth(), ep->getY() - sp->getY()};
r1 = {0.f, sp->getY(), sp->getX(), lineHeight};
r2 = {ep->getX(), ep->getY() - lineHeight, box->getWidth() - ep->getX(), lineHeight};

std::stack<std::shared_ptr<Box>> s;
s.push(box);
std::shared_ptr<Box> p = nullptr;
while(!s.empty()) {
// get the current node
p = s.top();
s.pop();

// filter
if (std::less_equal<float>()(p->y + p->depth, sp->getY()) ||
std::greater_equal<float>()(p->y - p->height, ep->getY())) {
continue;
}

switch (p->getBoxCode()) {
case BoxTypeTableBox: {
s.push(p->typeValue<MDTableBox>()->getBase());
break;
}
case BoxTypeListBox: {
s.push(p->typeValue<MDListBox>()->getBase());
break;
}
case BoxTypeQuoteBox: {
s.push(p->typeValue<MDQuoteBox>()->getBase());
break;
}
case BoxTypeCodeBox: {
s.push(p->typeValue<MDCodeBox>()->getBase());
break;
}
case BoxTypeScaleBox: {
s.push(p->typeValue<ScaleBox>()->getBase());
break;
}
case BoxTypeHorizontalBox: {
auto& children = p->typeValue<HorizontalBox>()->getChildren();
for (int i = (int)children.size() - 1; i >= 0; --i) {
s.push(children[i]);
}
break;
}
case BoxTypeVerticalBox: {
auto& children = p->typeValue<VerticalBox>()->children;
for (int i = (int)children.size() - 1; i >= 0; --i) {
s.push(children[i]);
}
break;
}
case BoxTypeFontRendingBox: {
if (isRectContainBox(r0, p) && !isRectContainBox(r1, p) && !isRectContainBox(r2, p)) {
result.push_back(p);
}
break;
}
default:
break;
}
}
return result;
}
Result

Platform-independent interfaces

The renderer isolates platform graphics APIs behind a small set of C++ interfaces. The most important ones are shown below.

Graphics2D

Graphics2D defines the platform-neutral 2D drawing surface:

  1. Draw strings, lines, rectangles, views, and so on.
  2. Apply transformations such as translation, scaling, and rotation.
  3. Set fonts, colors, strokes, and so on.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class Graphics2D {
public:
virtual std::shared_ptr<Stroke> getStroke() = 0;
virtual void setStroke(const std::shared_ptr<Stroke>& stroke) = 0;
virtual std::shared_ptr<Color> getColor() = 0;
virtual void setColor(const std::shared_ptr<Color>& color) = 0;
virtual std::shared_ptr<Font> getFont() = 0;
virtual void setFont(const std::shared_ptr<Font>& font) = 0;

virtual void fill(const std::shared_ptr<Shape>& rectangle) = 0;
virtual void fillRect(int x, int y, int width, int height) = 0;
virtual void fullRoundRect(const std::shared_ptr<RoundRectangle2D>& r) = 0;
virtual void fillArc(int x, int y, int width, int height, int startAngle, int arcAngle) = 0;

virtual void draw(const std::shared_ptr<Rectangle2D>& rectangle) = 0;
virtual void draw(const std::shared_ptr<RoundRectangle2D>& rectangle) = 0;
virtual void draw(const std::shared_ptr<Line2D>& line) = 0;
virtual void draw(const std::string& s, int x, int y) = 0;
virtual void draw(const std::shared_ptr<Path>& path) = 0;
virtual void draw(const std::shared_ptr<View>& view) = 0;
virtual void drawArc(int x, int y, int width, int height, int startAngle, int arcAngle) = 0;

virtual void translate(double x, double y) = 0;
virtual void scale(double x, double y) = 0;
virtual void rotate(double theta, double x, double y) = 0;
virtual void rotate(double theta) = 0;

......
};

TextLayout

TextLayout abstracts native text measurement and drawing.

1
2
3
4
5
class TextLayout {
public:
virtual std::shared_ptr<Rectangle2D> getBounds() = 0;
virtual void draw(const std::shared_ptr<Graphics2D>& graphics, int x, int y) = 0;
};

Others

Supporting interfaces include Point2D, Line2D, Rectangle2D, Path, and View.

Platform adaptation

iOS

Objective-C++ integration

The iOS adapter uses Objective-C++, enabled by the .mm file extension, so the same translation unit can call both Objective-C and C++ APIs. The languages remain separate, however: Objective-C syntax cannot invoke arbitrary C++ objects, Objective-C classes do not gain C++ constructors or destructors, and the two class hierarchies cannot inherit from one another.

For a closer look at ownership across that boundary, see Understanding OC/C++ Closures.

Each platform-neutral interface has an Objective-C++ implementation that forwards to the corresponding Apple framework.

Graphics2D_iOS

For example, string drawing maps naturally to Core Text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
void Graphics2D_iOS::draw(const std::string& t, int x, int y) {
NSString *utf8String = [NSString stringWithCString:(const char*)t.c_str() encoding:NSUTF8StringEncoding];
if (!utf8String) return;
NSMutableAttributedString *attributedString = [[NSMutableAttributedString alloc] initWithString:utf8String];
[attributedString addAttribute:(__bridge NSString *)kCTFontAttributeName
value:(__bridge id)(_font->_ctFont)
range:NSMakeRange(0, attributedString.length)];

[attributedString addAttribute:(__bridge NSString *)kCTForegroundColorAttributeName
value:(__bridge id)_color->_color
range:NSMakeRange(0, attributedString.length)];

CTLineRef line = CTLineCreateWithAttributedString((__bridge CFAttributedStringRef)(attributedString));
CGContextSaveGState(_context);
CGContextSetTextPosition(_context, x, y);
CTLineDraw(line, _context);
CGContextStrokePath(_context);
CGContextRestoreGState(_context);
CFRelease(line);
}
TextLayout_iOS

TextLayout_iOS uses native text measurement APIs to calculate text bounds and returns a platform-adapted Rectangle2D_iOS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// TextLayout_iOS.mm
std::shared_ptr<Rectangle2D> TextLayout_iOS::getBounds() {
NSString *temp = [NSString stringWithCString:_src.c_str() encoding:NSUTF8StringEncoding];
NSMutableParagraphStyle *paraStyle = [[NSMutableParagraphStyle alloc] init];
paraStyle.alignment = NSTextAlignmentJustified;

shared_ptr<Font_iOS> f = static_pointer_cast<Font_iOS>(_font);
NSString *fontPostScriptName = (NSString *)CFBridgingRelease(CTFontCopyPostScriptName(f->_ctFont));
UIFont *font = [UIFont fontWithName:fontPostScriptName size:f->_size];
NSDictionary *attributes = @{NSParagraphStyleAttributeName : paraStyle, NSFontAttributeName : font};
CGRect rect = [temp boundingRectWithSize:CGSizeMake(CGFLOAT_MAX, CGFLOAT_MAX)
options:NSStringDrawingUsesFontLeading
attributes:attributes
context:nil];
return std::make_shared<Rectangle2D_iOS>(0, -CGRectGetHeight(rect) - CGRectGetMinY(rect), CGRectGetWidth(rect), CGRectGetHeight(rect));
}
Binding the renderer

MarkdownView owns both the parsed _icon and the iOS _graphics adapter. During drawRect:, it attaches the current CGContext to _graphics and passes that abstract renderer to paintIcon. C++ virtual dispatch then routes each drawing operation to the iOS implementation.

1
2
3
4
class Icon : public std::enable_shared_from_this<Icon>, public IIcon {
public:
void paintIcon(const std::shared_ptr<Graphics2D>& g2, int x, int y) override;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// MarkdownView.mm
- (void)drawRect:(CGRect)rect {
_graphics->startDrawing();

CGContextRef context = UIGraphicsGetCurrentContext();

// bind context to graphics
_graphics->setContext(context);
// set foreground
_icon->setForeground(_foreground);
// draw: _graphics = std::make_shared<md::Graphics2D_iOS>();
_icon->paintIcon(_graphics, 0.f, 0.f);
// unbind context
_graphics->setContext(nullptr);

_graphics->finishDrawing();

}

Android

Layered implementation

The Android adapter crosses the JNI boundary and is therefore split into three layers:

  1. The Kotlin API layer.
  2. The JNI communication layer.
  3. The C/C++ implementation layer.

Each abstract interface has both a C++ adapter (xxx_Android) and a Kotlin counterpart. The C++ side preserves the shared renderer contract, while the Kotlin side calls Android framework APIs; JNI connects the two.

Graphics2D_Android

The call flow is: draw -> markRecord -> JNI -> record -> play -> drawText.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Graphics2D_Android.cpp
void Graphics2D_Android::draw(const std::string& t, int x, int y) {
JNIEnv* env = getJNIEnv();
jstring jstr = env->NewStringUTF(t.c_str());
jfloat p[] = {x, y};
makeRecord(ACT_DRAWTEXT, jstr, p, 2);
env->DeleteLocalRef(jstr);
}

void Graphics2D_Android::makeRecord(int action, jobject arg, const jfloat* args, int argsLen) {
jfloatArray arr = 0;
JNIEnv* env = getJNIEnv();
if (argsLen != 0) {
arr = env->NewFloatArray(argsLen);
env->SetFloatArrayRegion(arr, 0, argsLen, args);
}
env->CallVoidMethod(_javaGraphics2D, gMethodRecord, action, arg, arr);
if (arr) env->DeleteLocalRef(arr);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Graphics2D.kt
fun record(action: Int, arg: Any?, args: FloatArray?) {
val act = GraphicAction(action.toByte(), arg, args)
play(act)
}

private fun play(act: GraphicAction?) {
if (act == null) return
var action = ACT.values()[act.action.toInt()]
when (action) {
......
ACT.ACT_DRAWTEXT -> this.drawText(
act.arg as String?, act.args!![0], act.args!![1]
)
......
}
}

private fun drawText(txt: String?, x: Float, y: Float) {
val canvas = getCanvas() ?: return
txt ?: return
beforeFill()
canvas.drawText(txt, 0, txt.length, x, y, paint)
afterFill()
}
TextLayout_Android

TextLayout_Android calls into the Kotlin side through JNI, uses Android text measurement APIs, and returns the result to the C++ layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
std::shared_ptr<Rectangle2D> TextLayout_Android::getBounds() {
JNIEnv* env = getJNIEnv();
std::shared_ptr<Font_Android> fontA = std::static_pointer_cast<Font_Android>(_font);
jobject jfont = fontA->getJavaFont();
jstring str = env->NewStringUTF(_src.c_str());
jobject obj = env->CallStaticObjectMethod(gClassTextLayout, gMethodGetBounds, str, jfont);
double x = env->GetFloatField(obj, gFieldRectX);
double y = env->GetFloatField(obj, gFieldRectY);
double w = env->GetFloatField(obj, gFieldRectW);
double h = env->GetFloatField(obj, gFieldRectH);
env->DeleteLocalRef(str);
env->DeleteLocalRef(obj);
return std::make_shared<Rectangle2D_Android>(x, y, w, h);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class TextLayout {
companion object {
private val PAINT = TextPaint()
private val TEXT_BOUNDS = android.graphics.Rect()

@JvmStatic
fun getBounds(txt: String, font: Font): Rect {
val oldTypeface = PAINT.typeface
PAINT.typeface = font.getTypeface()
PAINT.textSize = font.getSize()
PAINT.getTextBounds(txt, 0, txt.length, TEXT_BOUNDS)
val textWidth = PAINT.measureText(txt)
val r = Rect(
0F,
PAINT.fontMetricsInt.ascent.toFloat(),
textWidth,
(PAINT.fontMetricsInt.descent - PAINT.fontMetricsInt.ascent).toFloat()
)
PAINT.typeface = oldTypeface
return r
}
}
}
Binding the renderer

MarkdownView binds the current Android Canvas to Graphics2D, applies display-density scaling, and calls icon.paintIcon.

1
2
3
4
5
6
7
8
9
10
// MarkdownView.kt
override fun onDraw(canvas: Canvas) {
canvas.save()
g2.setCanvas(canvas)
canvas.scale(screenDensity, screenDensity)
icon.setForeground(icon.param.foregroundColor)
// g2 = Graphics2D(context)
icon.paintIcon(g2, 0, 0)
canvas.restore()
}
JNI communication
Kotlin -> C/C++

MarkdownIconBuilder.build, for example, delegates parsing to the C++ core through the native nParse method.

1
2
3
4
5
6
7
8
// MarkdownIconBuilder.kt
fun build(): MarkdownIcon? {
nIconBuilder = nParse(param, customViewGenerator.nPtr)
val nIcon = nBuild(nIconBuilder, param.content)
if (nIcon == 0L) return null
val icon = MarkdownIcon(nIcon, param)
return icon
}

Kotlin declares nParse; the native implementation performs the actual Markdown parsing.

1
private external fun nParse(param: MarkdownParam, generatorPtr: Long): Long

JNI maps nParse to Java_com_edu_markdown_api_MarkdownIconBuilder_00024Companion_nParse in jni_iconbuilder.cpp, which forwards the request to MDIconBuilder.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
extern "C"
JNIEXPORT jlong JNICALL
Java_com_edu_markdown_api_MarkdownIconBuilder_00024Companion_nParse(JNIEnv *env, jobject thiz, jobject param, jlong generatorPtr) {
std::shared_ptr<md::MDBuildParam> *buildParam = new std::shared_ptr<md::MDBuildParam>(getBuildParam(param));
env->DeleteLocalRef(param);

std::string content = getBuildContent(param);
jlong result = 0L;

std::shared_ptr<MDIconBuilder> builder = std::make_shared<MDIconBuilder>();
builder->callback = [&content](const std::string &msg) {
reportParseError(content, msg);
};
builder->setBuildParam(*buildParam);
auto func = [content, buildParam, generatorPtr, env](const std::string &name, const std::map<std::string, std::string> &attributes) -> std::shared_ptr<MDBaseNode> {
auto customViewGenerator = reinterpret_cast<MDCustomViewGenerator *>(generatorPtr);
std::shared_ptr<MDBaseNode> node = nullptr;
if (name == "img") {
node = std::make_shared<MDImageNode_Android>(name, attributes, *buildParam, customViewGenerator);
} else if (customViewGenerator->interceptTag(name)) {
node = std::make_shared<MDCustomNode_Android>(name, attributes, customViewGenerator);
}
return node;
};
builder->registerCustomNodeGenerateFunc(func);

auto *p = new std::shared_ptr<md::MDIconBuilder>(std::move(builder));
result = reinterpret_cast<long>(p);

return result;
}

That is the complete Kotlin-to-C++ path.

C/C++ -> Kotlin

Calls in the opposite direction follow the same bridge. Graphics2D_Android::makeRecord, for example, must invoke Kotlin because the C++ layer cannot draw on an Android Canvas directly.

1
2
3
4
5
6
7
8
9
10
void Graphics2D_Android::makeRecord(int action, jobject arg, const jfloat* args, int argsLen) {
jfloatArray arr = 0;
JNIEnv* env = getJNIEnv();
if (argsLen != 0) {
arr = env->NewFloatArray(argsLen);
env->SetFloatArrayRegion(arr, 0, argsLen, args);
}
env->CallVoidMethod(_javaGraphics2D, gMethodRecord, action, arg, arr);
if (arr) env->DeleteLocalRef(arr);
}

The adapter invokes the cached method through the appropriate JNIEnv::Call*Method function:

1
env->CallVoidMethod(_javaGraphics2D, gMethodRecord, action, arg, arr);

That completes the C++-to-Kotlin path.

jni_def.cpp caches the Kotlin classes and method IDs required by the C++ layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
static void load(JNIEnv* env) {
// Graphics2D
jclass graphics2D = env->FindClass("com/edu/markdown/native/graphic/Graphics2D");
gClassGraphics2D = (jclass)env->NewGlobalRef(graphics2D);
gMethodRecord = env->GetMethodID(gClassGraphics2D,"record","(ILjava/lang/Object;[F)V");

// TextLayout
jclass layout = env->FindClass("com/edu/markdown/native/graphic/TextLayout");
gClassTextLayout = (jclass)env->NewGlobalRef(layout);
gMethodGetBounds = env->GetStaticMethodID(gClassTextLayout, "getBounds", "(Ljava/lang/String;Lcom/edu/markdown/native/graphic/Font;)Lcom/edu/markdown/native/graphic/Rect;");

// Path
jclass path = env->FindClass("com/edu/markdown/native/graphic/Path");
gClassPath = (jclass)env->NewGlobalRef(path);
gMethodMoveTo = env->GetMethodID(gClassPath, "moveTo", "(DD)V");
gMethodLineTo = env->GetMethodID(gClassPath, "lineTo", "(DD)V");
gMethodQuadTo = env->GetMethodID(gClassPath, "quadTo", "(DDDD)V");
gMethodCubicTo = env->GetMethodID(gClassPath, "cubicTo", "(DDDDDD)V");

// Font
jclass font = env->FindClass("com/edu/markdown/native/graphic/Font");
gClassFont = (jclass)env->NewGlobalRef(font);
gMethodDeriveFont = env->GetMethodID(gClassFont, "deriveFont", "(I)Lcom/edu/markdown/native/graphic/Font;");
gMethodCreateFontFromName = env->GetStaticMethodID(gClassFont, "create", "(Ljava/lang/String;IF)Lcom/edu/markdown/native/graphic/Font;");
gMethodCreateFontFromFile = env->GetStaticMethodID(gClassFont, "create", "(Ljava/lang/String;F)Lcom/edu/markdown/native/graphic/Font;");

// Rect
jclass rect = env->FindClass("com/edu/markdown/native/graphic/Rect");
gFieldRectX = env->GetFieldID(rect, "x", "F");
gFieldRectY = env->GetFieldID(rect, "y", "F");
gFieldRectW = env->GetFieldID(rect, "w", "F");
gFieldRectH = env->GetFieldID(rect, "h", "F");

......
}

Customization

Different host apps may need to interpret or present particular nodes in their own way, while the SDK still needs sensible default behavior. The customization layer must support both without coupling the shared engine to one product’s UI.

To achieve this, the host app can provide a native view implementation for a node and inject it into the engine. That view participates in the Markdown layout pass and is later composed with the canvas output.

iOS

Abstract View interface

The first step is to define the View interface. getWidth, getHeight, and getDepth are used for layout, while setX, setY, and getNativeView are used for rendering. All pure virtual methods listed here are necessary.

1
2
3
4
5
6
7
8
9
10
class View  {
public:
virtual void* getNativeView() = 0;
virtual void setX(double x) = 0;
virtual void setY(double y) = 0;
virtual double getWidth() = 0;
virtual double getHeight() = 0;
virtual double getDepth() = 0;
......
};
Define View_iOS

The second step is to implement the View interface. On iOS, View_iOS calls invokeRenderBlockIfNeeded from setX, setY, and getNativeView. This keeps layout and rendering separate: background parsing computes dimensions without touching UIKit, and the native view is created lazily when rendering begins.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
View_iOS::View_iOS(double w, double h, double d, ViewRenderBlock block, NSDictionary *attr) {
mWidth = w;
mHeight = h;
mDepth = d;
mRenderBlock = block;
mAttr = attr;
}

View_iOS::~View_iOS() {
if (!mView) return;
CFRelease((void *)mView);
mView = NULL;
}

void* View_iOS::getNativeView() {
invokeRenderBlockIfNeeded();
return (__bridge void *)mView;
}

void View_iOS::setX(double x) {
invokeRenderBlockIfNeeded();
CGRect frame = mView.frame;
frame.origin.x = x;
mView.frame = frame;
}

void View_iOS::setY(double y) {
invokeRenderBlockIfNeeded();
CGRect frame = mView.frame;
frame.origin.y = y;
mView.frame = frame;
}


double View_iOS::getHeight() {
return mHeight;
}

double View_iOS::getWidth() {
return mWidth;
}

double View_iOS::getDepth() {
return mDepth;
}
......

void View_iOS::invokeRenderBlockIfNeeded() {
if (!mView){
UIView *view = mRenderBlock(mAttr, mWidth, mHeight, mDepth);
mView = (UIView *)CFRetain((void *)view);
}
}
Define MDCustomNode_iOS

Following the tree model described earlier, MDCustomNode_iOS is a custom Node. Its getAtom method invokes layoutBlock and creates an MDCustomAtom_iOS. One detail requires care: custom layout needs the node’s content, but that content is assembled from child nodes that are not available when the node is first created. The current implementation therefore extracts content only after the full node tree has been built, and currently supports plain-text children only.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
std::shared_ptr<Atom> MDCustomNode_iOS::getAtom() {
std::string content = "";
for (auto& node : mChildren) {
content += node->getRawContent();
}
mAttributes["content"] = content;

// layout first
mLayoutRender.info = dictionaryWithMap(mAttributes);
if (mLayoutRender.layoutBlock) {
mLayoutRender.layoutBlock(mLayoutRender.info, &(mLayoutRender.width), &(mLayoutRender.height), &(mLayoutRender.depth));
}

std::shared_ptr<MDCustomAtom_iOS> atom = std::make_shared<MDCustomAtom_iOS>(mName, mAttributes, mLayoutRender);
return atom;
}
Define MDCustomAtom_iOS

MDCustomAtom_iOS wraps the layout result and creates a View_iOS object with width, height, depth, render block, and attributes.

1
2
3
MDCustomAtom_iOS::MDCustomAtom_iOS(const std::string& name, const std::map<std::string, std::string>& attributes, CustomLayoutRender layoutRender) : MDCustomAtom(name, attributes), mLayoutRender(layoutRender) {
mCustomView = std::make_shared<View_iOS>(mLayoutRender.width, mLayoutRender.height, mLayoutRender.depth, mLayoutRender.renderBlock, mLayoutRender.info);
}
Layout custom views

During layout, MDCustomAtom creates an MDCustomViewBox, converts the native view size into engine coordinates according to the current environment font size, and returns it as a normal Box.

1
2
3
4
5
6
7
8
std::shared_ptr<Box> MDCustomAtom::createBox(const std::shared_ptr<Environment>& env) {
double size = env->getSize();
std::shared_ptr<MDCustomViewBox> box = std::make_shared<MDCustomViewBox>(mCustomView, env->getTeXFont());
box->setWidth(mCustomView->getWidth() / size);
box->setHeight(mCustomView->getHeight() / size);
box->setDepth(mCustomView->getDepth() / size);
return box;
}
Draw custom views

When the box is drawn, it sets the native view position and delegates drawing to Graphics2D. Through C++ polymorphism, g2->draw calls the iOS implementation, which adds the native view to its parent view (MarkdownView) through addSubview.

1
2
3
4
5
6
7
8
9
10
void MDCustomViewBox::draw(const std::shared_ptr<Graphics2D>& g2, double x, double y) {
int size = mFont->getSize();
startDraw(g2, x, y);
g2->translate(x, y);
mCustomView->setX(x * size);
mCustomView->setY(y * size - getHeight() * size);
g2->draw(mCustomView);
g2->translate(-x, -y);
endDraw(g2);
}
1
2
3
4
5
void Graphics2D_iOS::draw(const std::shared_ptr<View>& view) {
UIView *nativeView = (__bridge UIView *)view->getNativeView();
[nativeView removeFromSuperview];
[parentView addSubview:nativeView];
}

Cell reuse may leave a native view attached to an old parent. Before MarkdownView.drawRect adds it again, the renderer calls [nativeView removeFromSuperview].

Register custom implementation

Suppose the host app wants to render the sup tag as an input field. It can provide layout and rendering callbacks through MarkdownParam.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
auto func = ^CustomViewParam *(NSString* name, NSDictionary<NSString*, NSString*>* attributes) {
if ([name isEqual:@"sup"]) {
CustomViewParam *param = [[CustomViewParam alloc] init];
param.layoutFunc = ^(NSDictionary * _Nonnull attributes
, double * _Nonnull width, double * _Nonnull height, double * _Nonnull depth) {
*width = 150;
*height = 12;
*depth = -3;
};
param.renderFunc = ^UIView *(NSDictionary * _Nonnull attributes, double w, double h, double d) {
UITextField *textField = [[UITextField alloc] initWithFrame:CGRectMake(0, 0, w, h-d)];
textField.font = [UIFont systemFontOfSize:12];
textField.text = @"Custom input";
textField.backgroundColor = [UIColor redColor];
return textField;
};
return param;
}
return nil;
};

MarkdownParam *param = [[MarkdownParam alloc] init];
param.func = func;

Android

Abstract View interface

Android implements the same platform-neutral View contract used by iOS.

1
2
3
4
5
6
7
8
9
10
class View  {
public:
virtual void* getNativeView() = 0;
virtual void setX(double x) = 0;
virtual void setY(double y) = 0;
virtual double getWidth() = 0;
virtual double getHeight() = 0;
virtual double getDepth() = 0;
......
};
Define View_Android

View_Android wraps the Kotlin view in mView. Unlike iOS, Android creates that native view before layout and passes it into the wrapper; reproducing the iOS lazy-creation path across JNI would add more complexity and calls than it saves.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
View_Android::View_Android(double width, double height, double depth, jobject view) : mWidth(width), mHeight(height), mDepth(depth), mView(view){}

View_Android::~View_Android() {
if (mView) {
JNIEnv *env = getJNIEnv();
env->DeleteGlobalRef(mView);
}
}

void * View_Android::getNativeView() {
return (void *)mView;
}

void View_Android::setX(double x) {
jclass viewClass = getJNIEnv()->GetObjectClass(mView);
jmethodID mid = getJNIEnv()->GetMethodID(viewClass, "setX", "(D)V");
getJNIEnv()->CallVoidMethod(mView, mid, x);
getJNIEnv()->DeleteLocalRef(viewClass);
}

void View_Android::setY(double y) {
jclass viewClass = getJNIEnv()->GetObjectClass(mView);
jmethodID mid = getJNIEnv()->GetMethodID(viewClass, "setY", "(D)V");
getJNIEnv()->CallVoidMethod(mView, mid, y);
getJNIEnv()->DeleteLocalRef(viewClass);
}

double View_Android::getHeight() {
return mHeight;
}

double View_Android::getWidth() {
return mWidth;
}

double View_Android::getDepth() {
return mDepth;
}
Define MDCustomNode_Android

Android uses an MDCustomViewGenerator named mGenerator to measure and create custom views across the JNI boundary.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
std::shared_ptr<Atom> MDCustomNode_Android::getAtom() {
std::string content = "";
for (auto& node : mChildren) {
content += node->getRawContent();
}
mAttributes["content"] = content;
auto result = mGenerator->layoutView(mName, mAttributes);
mWidth = std::get<0>(result);
mHeight = std::get<1>(result);
mDepth = std::get<2>(result);

mAttributes["width"] = mWidth;
mAttributes["height"] = mHeight;
mAttributes["depth"] = mDepth;
jobject jView = mGenerator->createView(mName, mAttributes);
std::shared_ptr<MDCustomAtom_Android> atom = std::make_shared<MDCustomAtom_Android>(mName, mAttributes, mWidth, mHeight, mDepth, jView);
return atom;
}

The generator exposes separate methods for measurement and view creation:

1
2
3
4
5
6
7
8
9
10
11
12
class MDCustomViewGenerator {
public:
MDCustomViewGenerator(jobject generator);
~MDCustomViewGenerator();

jobject createView(const std::string &name, const std::map <std::string, std::string> &attributes);

std::tuple<double,double,double> layoutView(const std::string &name, const std::map <std::string, std::string> &attributes);
private:
jobject mGenerator;
......
};

Because the C++ object cannot instantiate an Android View, Kotlin provides the corresponding ICustomViewGenerator implementation. JNI forwards measurement and creation requests between the two generators.

1
2
3
4
interface ICustomViewGenerator {
fun createView(name: String, attribute: Map<String, String>): IView?
fun layoutView(name: String, attribute: Map<String, String>): FloatArray
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// CustomViewGeneratorManager.kt
open class CustomViewGeneratorManager(val param: MarkdownParam) : ICustomViewGenerator {

private val creatorMap = HashMap<String, ICustomViewGenerator>()

public fun registerViewGenerator(name: String, generator: ICustomViewGenerator) {
creatorMap[name] = generator
nRegister(name, nPtr)
}

var nPtr : Long = 0L

init {
nPtr = nCreate(this)
registerViewGenerator("img", CustomImageViewGenerator(param))
}

fun interceptTag(name: String): Boolean {
return creatorMap.containsKey(name)
}

override fun createView(name: String, attribute: Map<String, String>): IView? {
val generator = creatorMap[name] ?: return null
return generator.createView(name, attribute)
}

override fun layoutView(name: String, attribute: Map<String, String>): FloatArray {
val generator = creatorMap[name] ?: return FloatArray(3)
return generator.layoutView(name, attribute)
}

fun finalize() {
if (nPtr == 0L) return;
nFinalize(nPtr)
nPtr = 0L
}

private external fun nCreate(customViewGenerator: ICustomViewGenerator): Long
private external fun nFinalize(ptr: Long)
private external fun nRegister(name: String, ptr: Long)
}

MDCustomViewGenerator and CustomViewGeneratorManager communicate through the same JNI bridge used elsewhere in the adapter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
jobject MDCustomViewGenerator::createView(const std::string &name, const std::map<std::string, std::string> &attributes) {
auto jMap = convertMapToJMap(attributes);
auto jName = stringTojstring(getJNIEnv(), name);
jobject jView = getJNIEnv()->CallObjectMethod(mGenerator, gMethodCreateView, jName, jMap);
getJNIEnv()->DeleteLocalRef(jName);
getJNIEnv()->DeleteLocalRef(jMap);
return getJNIEnv()->NewGlobalRef(jView);
}

std::tuple<double,double,double> MDCustomViewGenerator::layoutView(const std::string &name, const std::map<std::string, std::string> &attributes) {
auto jAttribute = convertMapToJMap(attributes);
auto jName = stringTojstring(getJNIEnv(), name);
JNIEnv *env = getJNIEnv();
jobject jArray = env->CallObjectMethod(mGenerator, gMethodLayoutView, jName, jAttribute);
jfloat *arr = env->GetFloatArrayElements(static_cast<jfloatArray>(jArray), JNI_FALSE);
auto result = std::make_tuple(arr[0], arr[1], arr[2]);
getJNIEnv()->DeleteLocalRef(jName);
getJNIEnv()->DeleteLocalRef(jAttribute);
return result;
}
Define MDCustomAtom_Android

MDCustomAtom_Android wraps the generated Android custom view into View_Android.

1
2
3
MDCustomAtom_Android::MDCustomAtom_Android(const std::string& name, const std::map<std::string, std::string>& attributes, double width, double height, double depth, jobject jView) : MDCustomAtom(name, attributes) {
mCustomView = std::make_shared<View_Android>(width, height, depth, jView);
}
Layout custom views

Custom Android views enter the same Box-based layout pipeline as their iOS counterparts.

1
2
3
4
5
6
7
8
std::shared_ptr<Box> MDCustomAtom::createBox(const std::shared_ptr<Environment>& env) {
double size = env->getSize();
std::shared_ptr<MDCustomViewBox> box = std::make_shared<MDCustomViewBox>(mCustomView, env->getTeXFont());
box->setWidth(mCustomView->getWidth() / size);
box->setHeight(mCustomView->getHeight() / size);
box->setDepth(mCustomView->getDepth() / size);
return box;
}
Draw custom views

Through virtual dispatch, g2->draw reaches the Android adapter, obtains the native view, detaches it from any previous parent, and adds it to the renderer’s root view.

1
2
3
4
5
6
7
8
9
10
void MDCustomViewBox::draw(const std::shared_ptr<Graphics2D>& g2, double x, double y) {
int size = mFont->getSize();
startDraw(g2, x, y);
g2->translate(x, y);
mCustomView->setX(x * size);
mCustomView->setY(y * size - getHeight() * size);
g2->draw(mCustomView);
g2->translate(-x, -y);
endDraw(g2);
}
1
2
3
4
5
6
7
8
9
10
11
ACT.ACT_DRAWVIEW -> {
var view = act.arg!! as CustomBaseView
var context = getRootView()?.context as Context
var nativeView = view.getAndroidView(context)
var rootView = getRootView();
if (nativeView?.parent != rootView) {
val layoutParam = ViewGroup.LayoutParams((view.getViewWidth() * screenDensity).toInt(), ((view.getViewHeight() - view.getViewDepth()) * screenDensity).toInt())
(nativeView.parent as? ViewGroup)?.removeView(nativeView)
rootView?.addView(nativeView, layoutParam)
}
}
Register custom implementation

Suppose the host app wants to render the sup tag as an input field. It can implement ICustomViewGenerator, return the layout dimensions, create an Android view, and register the generator through MarkdownIconBuilder.

1
2
3
4
5
6
7
8
9
10
11
12
13
class InputViewGenerator : ICustomViewGenerator {
override fun createView(name: String, attribute: Map<String, String>): IView? {
val width = MDSize(130F, TypedValue.COMPLEX_UNIT_DIP)
val height = MDSize(16F, TypedValue.COMPLEX_UNIT_DIP)
val depth = MDSize(-5F, TypedValue.COMPLEX_UNIT_DIP)
return InputCustomView(width, height, depth)
}

override fun layoutView(name: String, attribute: Map<String, String>): FloatArray {
var fa = arrayOf(130F, 16F, -5F)
return fa.toFloatArray()
}
}
1
2
3
4
5
6
7
8
9
class InputCustomView(width: MDSize, height: MDSize, depth: MDSize) : CustomBaseView(width, height, depth) {
override fun createAndroidView(context: Context): View {
var editView = EditText(context)
editView.textSize = 12F
editView.setBackgroundColor(Color.YELLOW)
editView.setPadding(0,0,0,0)
return editView
}
}
1
2
3
4
5
6
7
8
9
10
11
12
val param = MarkdownParam(
content = model.text,
maxWidth = maxWidth,
fontName = "sans",
fontSize = textSize,
foregroundColor = foregroundColor,
backgroundColor = backgroundColor,
alignment = TexAlignment.LEFT
)
val customViewGenerator = CustomViewGeneratorManager(param)
val builder = MarkdownIconBuilder(param)
builder.registerViewGenerator("sups", InputViewGenerator())

Performance

The following measurements are a snapshot of the current implementation.

Binary size

Platform Device Static library Dynamic library
iOS iPhone11 290 KB 546 KB
Android Xiaomi M2104K10AC - 471 KB (arm64-v8a) 354 KB (armebabi-v7a)

The iOS static-library figure excludes part of the ThinLTO output. The packaged size is closer to 300–400 KB.

CPU time

  1. Asynchronous parsing: YES

  2. Asynchronous layout: YES

  3. Asynchronous rendering: NO

Platform Device Parse Layout Rendering
iOS iPhone11 9 ms 37 ms 8 ms
Android Xiaomi M2104K10AC 3 ms 34 ms 30 ms

Memory usage

Platform Device Memory usage
iOS iPhone11 ~8 MB
Android Xiaomi M2104K10AC ~10 MB

Conclusion

This article used Markdown to explore a broader problem: how to share parsing, layout, and drawing logic across native platforms without giving up platform-specific UI. The three-tree model, virtual graphics layer, and thin adapters are not limited to Markdown; the same architecture can support other structured-content renderers as well.

References

  1. https://commonmark.org/
  2. https://github.com/mity/md4c
  3. 英文标点要如何排版?
  4. 图文落地页阅读体验优化探索
  5. 深入中英文的排版与换行(视频)
  6. 深入中英文的排版与换行
  7. Basic writing and formatting syntax
  8. Requirements for Chinese Text Layout 中文排版需求
  9. 译文排版规则指北
  10. The punctuation guide
  11. 全角半角碎碎念
  12. 不离不弃的破折号
  13. https://www.uisdc.com/chinese-typesetting-3-principle
  14. 移动阅读软件 :中文排印上那些你不知道的事
  15. 孔雀计划:中文字体排印的思路
  16. https://github.com/w3c/clreq
  17. 阿拉伯文字的艺术、设计和开发:伊斯兰书法和字体
  18. 阿拉伯文字的艺术、设计和开发:RTL布局的设计要点
  19. 阿拉伯字母变形表
  20. Text Layout Requirements for the Arabic Script
  21. UNICODE及其编码(UTF-8、UTF-16、UTF-32)
  22. https://www.catch22.net/tuts/#
  23. https://juejin.cn/post/7124887769796591653
  24. https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6296
  25. http://rtlmd.codecast.ir/
  26. https://github.com/dalirnet/rtl-markdow
-------------本文结束 感谢您的阅读-------------
If this article helped you, your support encourages me to keep writing.

Title:Let's Build a Cross-Platform Markdown Rendering Library for iOS and Android

Author:lingyun

Published:2024-07-25 23:40

Updated:2026-10-08 00:23

Original link:https://tsuijunxi.github.io/en/2024/07/25/lets-build-a-cross-platform-markdown-rendering-library/

License: Attribution-NonCommercial-NoDerivatives 4.0 International Please keep the original link and author when sharing.