react-native-nitro-markdown 0.1.0

package/README.md

@@ -0,0 +1,276 @@
+<p align="center">
+  <img src="./apps/example/assets/icon.png" alt="react-native-nitro-markdown logo" width="150" height="150" />
+</p>
+
+# react-native-nitro-markdown 🚀
+
+> The fastest Markdown parser for React Native. Period.
+
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-markdown?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-markdown)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+
+**react-native-nitro-markdown** is a high-performance Markdown parser built on **[md4c](https://github.com/mity/md4c)** (C++) and **[Nitro Modules](https://nitro.margelo.com)**. It parses complex Markdown, GFM, and LaTeX Math into a structured AST **synchronously** via JSI, bypassing the React Native Bridge entirely.
+
+---
+
+## ⚡ Why Nitro? (Benchmarks)
+
+We benchmarked this library against the most popular JavaScript parsers on a real mobile device (iPhone 15 Pro, Release Mode) using a heavy **237KB** Markdown document.
+
+| Parser                      | Time (ms)  | Speedup           | Frame Drops (60fps)   |
+| :-------------------------- | :--------- | :---------------- | :-------------------- |
+| **🚀 Nitro Markdown (C++)** | **~29 ms** | **1x (Baseline)** | **~1 frame** (Smooth) |
+| 📋 CommonMark (JS)          | ~82 ms     | 2.8x slower       | ~5 frames (Jank)      |
+| 🏗️ Markdown-It (JS)         | ~118 ms    | 4.0x slower       | ~7 frames (Jank)      |
+| 💨 Marked (JS)              | ~400 ms    | 13.5x slower      | ~24 frames (Freeze)   |
+
+> **Takeaway:** JavaScript parsers trigger Garbage Collection pauses. Nitro uses C++ to parse efficiently with zero-copy overhead, keeping your UI thread responsive.
+
+---
+
+## 📦 Installation
+
+Choose your preferred package manager to install the package and its core dependency (`react-native-nitro-modules`).
+
+### **1. Install Dependencies**
+
+**npm**
+
+```bash
+npm install react-native-nitro-markdown react-native-nitro-modules
+```
+
+**Yarn**
+
+```bash
+yarn add react-native-nitro-markdown react-native-nitro-modules
+```
+
+**Bun**
+
+```bash
+bun add react-native-nitro-markdown react-native-nitro-modules
+```
+
+**pnpm**
+
+```bash
+pnpm add react-native-nitro-markdown react-native-nitro-modules
+```
+
+### **2. Install Native Pods (iOS)**
+
+**Standard**
+
+```bash
+cd ios && pod install
+```
+
+### **3. Expo Users**
+
+If you are using Expo, you must run a **Prebuild** (Development Build) because this package contains native C++ code.
+
+```bash
+npx expo install react-native-nitro-markdown react-native-nitro-modules
+npx expo prebuild
+```
+
+---
+
+## 💻 Usage
+
+### Basic Parsing
+
+The parsing is synchronous and instant. It returns a fully typed JSON AST.
+
+```typescript
+import { parseMarkdown } from "react-native-nitro-markdown";
+
+const markdown = `
+# Hello World
+This is **bold** text and a [link](https://github.com).
+`;
+
+const ast = parseMarkdown(markdown);
+console.log(ast);
+// Output: { type: "document", children: [...] }
+```
+
+### Advanced Options (GFM & Math)
+
+Enable GitHub Flavored Markdown (Tables, TaskLists) or LaTeX Math support.
+
+```typescript
+import { parseMarkdown } from "react-native-nitro-markdown";
+
+const ast = parseMarkdown(markdown, {
+  gfm: true, // Tables, Strikethrough, Autolinks, TaskLists
+  math: true, // $E=mc^2$ and $$block$$
+  wiki: true, // [[WikiLinks]]
+});
+```
+
+---
+
+## 🎨 Rendering
+
+This library is a **Parser Only**. It gives you the raw data (AST) so you can render it with native components (`<Text>`, `<View>`) for maximum performance.
+
+Here is a simple recursive renderer example:
+
+```tsx
+import React from "react";
+import { Text, View, StyleSheet } from "react-native";
+import { parseMarkdown, type MarkdownNode } from "react-native-nitro-markdown";
+
+export function MarkdownView({ content }: { content: string }) {
+  const ast = parseMarkdown(content, { gfm: true });
+
+  return (
+    <View style={styles.container}>
+      <Renderer node={ast} />
+    </View>
+  );
+}
+
+function Renderer({ node }: { node: MarkdownNode }) {
+  switch (node.type) {
+    case "document":
+      return (
+        <View>
+          {node.children?.map((child, i) => (
+            <Renderer key={i} node={child} />
+          ))}
+        </View>
+      );
+
+    case "heading":
+      return (
+        <Text style={styles.h1}>
+          {node.children?.map((c, i) => (
+            <Renderer key={i} node={c} />
+          ))}
+        </Text>
+      );
+
+    case "paragraph":
+      return (
+        <Text style={styles.p}>
+          {node.children?.map((child, i) => (
+            <Renderer key={i} node={child} />
+          ))}
+        </Text>
+      );
+
+    case "text":
+      return <Text>{node.content}</Text>;
+
+    case "bold":
+      return (
+        <Text style={styles.bold}>
+          {node.children?.map((c, i) => (
+            <Renderer key={i} node={c} />
+          ))}
+        </Text>
+      );
+
+    // Handle 'table', 'code_block', 'math_inline' etc...
+    default:
+      return null;
+  }
+}
+
+const styles = StyleSheet.create({
+  container: { padding: 16 },
+  h1: { fontSize: 24, fontWeight: "bold", marginVertical: 8 },
+  p: { fontSize: 16, lineHeight: 24, marginBottom: 8 },
+  bold: { fontWeight: "700" },
+});
+```
+
+---
+
+## 📐 AST Structure
+
+The parser returns a `MarkdownNode` tree. The Types are fully exported for TypeScript support.
+
+```typescript
+export interface MarkdownNode {
+  type: NodeType;
+  // Content for Text/Code/Math
+  content?: string;
+  // Hierarchy
+  children?: MarkdownNode[];
+  // Metadata
+  level?: number; // Headings (1-6)
+  href?: string; // Links
+  checked?: boolean; // Task Lists
+  language?: string; // Code Blocks
+  // Table Props
+  align?: "left" | "center" | "right";
+  isHeader?: boolean;
+}
+
+export type NodeType =
+  | "document"
+  | "paragraph"
+  | "text"
+  | "heading"
+  | "bold"
+  | "italic"
+  | "strikethrough"
+  | "link"
+  | "image"
+  | "code_inline"
+  | "code_block"
+  | "blockquote"
+  | "list"
+  | "list_item"
+  | "task_list_item"
+  | "table"
+  | "table_row"
+  | "table_cell"
+  | "math_inline"
+  | "math_block";
+```
+
+---
+
+## 🧮 LaTeX Math Support
+
+We parse math delimiters (`$` and `$$`) natively using the `MD_FLAG_LATEXMATHSPANS` flag in `md4c`.
+
+To render the math, you should use a library like `react-native-math-view` inside your renderer:
+
+```tsx
+// Inside your switch(node.type)
+case 'math_inline':
+  return <MathView math={node.content} style={styles.math} />;
+case 'math_block':
+  return <MathView math={node.content} style={styles.mathBlock} />;
+```
+
+## 📊 Package Size
+
+| Metric | Size |
+| :----- | :--- |
+| **Packed (tarball)** | ~75 kB |
+| **Unpacked** | ~325 kB |
+| **Total files** | 55 |
+
+> The package includes the [md4c](https://github.com/mity/md4c) C source code (~244 kB) which is compiled natively on iOS and Android. This is a one-time cost that enables the high-performance parsing.
+
+---
+
+## 🤝 Contributing
+
+See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+
+## 📄 License
+
+MIT
+
+---
+
+Built with ❤️ using [Nitro Modules](https://nitro.margelo.com) and [md4c](https://github.com/mity/md4c).

package/android/CMakeLists.txt

@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(NitroMarkdown)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+# Define the path to our C++ sources
+set(CPP_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../cpp")
+
+# Collect source files
+file(GLOB MD4C_SOURCES "${CPP_ROOT}/md4c/*.c")
+file(GLOB CORE_SOURCES "${CPP_ROOT}/core/*.cpp")
+file(GLOB BINDING_SOURCES "${CPP_ROOT}/bindings/*.cpp")
+
+# Create the shared library with our sources
+add_library(${PROJECT_NAME} SHARED
+    ${MD4C_SOURCES}
+    ${CORE_SOURCES}
+    ${BINDING_SOURCES}
+    # JNI adapter
+    src/main/cpp/cpp-adapter.cpp
+)
+
+# Include directories
+target_include_directories(${PROJECT_NAME} PRIVATE
+    "${CPP_ROOT}/md4c"
+    "${CPP_ROOT}/core"
+    "${CPP_ROOT}/bindings"
+)
+
+# Preprocessor definitions
+target_compile_definitions(${PROJECT_NAME} PRIVATE
+    MD4C_USE_UTF8=1
+)
+
+# Include Nitro autolinking (adds nitrogen sources, definitions, and links)
+include(${CMAKE_CURRENT_SOURCE_DIR}/../nitrogen/generated/android/NitroMarkdown+autolinking.cmake)
+

package/android/build.gradle

@@ -0,0 +1,92 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.10.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroMarkdown+autolinking.gradle'
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroMarkdown_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroMarkdown_" + name]).toInteger()
+}
+
+android {
+  namespace "com.nitromarkdown"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += ["src/main/java"]
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += ["${project.buildDir}/generated/source/codegen/java"]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+  implementation project(":react-native-nitro-modules")
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroMarkdown_compileSdkVersion=34
+NitroMarkdown_minSdkVersion=24
+NitroMarkdown_targetSdkVersion=34
+NitroMarkdown_ndkVersion=27.1.12297006
+

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.nitromarkdown">
+</manifest>
+

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,7 @@
+#include <jni.h>
+#include "NitroMarkdownOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::NitroMarkdown::initialize(vm);
+}
+

package/android/src/main/java/com/nitromarkdown/NitroMarkdownPackage.kt

@@ -0,0 +1,23 @@
+package com.nitromarkdown
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class NitroMarkdownPackage : TurboReactPackage() {
+    companion object {
+        init {
+            System.loadLibrary("NitroMarkdown")
+        }
+    }
+
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { emptyMap() }
+    }
+}
+

package/cpp/CMakeLists.txt

@@ -0,0 +1,46 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(MD4CParserTest)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+# Define the path to our C++ sources
+set(CPP_ROOT "${CMAKE_CURRENT_SOURCE_DIR}")
+
+# Collect source files
+file(GLOB MD4C_SOURCES "${CPP_ROOT}/md4c/*.c")
+file(GLOB CORE_SOURCES "${CPP_ROOT}/core/*.cpp")
+# Exclude the test file from the library sources
+list(FILTER CORE_SOURCES EXCLUDE REGEX ".*Test\.cpp$")
+
+# Create the core library
+add_library(MD4CCore STATIC
+    ${MD4C_SOURCES}
+    ${CORE_SOURCES}
+)
+
+# Include directories for the library
+target_include_directories(MD4CCore PUBLIC
+    "${CPP_ROOT}/md4c"
+    "${CPP_ROOT}/core"
+)
+
+# Preprocessor definitions
+target_compile_definitions(MD4CCore PRIVATE
+    MD4C_USE_UTF8=1
+)
+
+# Create the test executable
+add_executable(MD4CParserTest
+    core/MD4CParserTest.cpp
+)
+
+# Link the test executable to the core library
+target_link_libraries(MD4CParserTest PRIVATE MD4CCore)
+
+# Include directories for the test
+target_include_directories(MD4CParserTest PRIVATE
+    "${CPP_ROOT}/core"
+)

package/cpp/bindings/HybridMarkdownParser.cpp

@@ -0,0 +1,112 @@
+#include "HybridMarkdownParser.hpp"
+#include <sstream>
+#include <iomanip>
+
+namespace margelo::nitro::NitroMarkdown {
+
+std::string HybridMarkdownParser::parse(const std::string& text) {
+    InternalParserOptions opts;
+    opts.gfm = true;
+    opts.math = true;
+    
+    auto ast = parser_->parse(text, opts);
+    return nodeToJson(ast);
+}
+
+std::string HybridMarkdownParser::parseWithOptions(const std::string& text, const ParserOptions& options) {
+    InternalParserOptions internalOpts;
+    internalOpts.gfm = options.gfm.value_or(true);
+    internalOpts.math = options.math.value_or(true);
+    
+    auto ast = parser_->parse(text, internalOpts);
+    return nodeToJson(ast);
+}
+
+static std::string escapeJson(const std::string& s) {
+    std::ostringstream o;
+    for (char c : s) {
+        switch (c) {
+            case '"': o << "\\\""; break;
+            case '\\': o << "\\\\"; break;
+            case '\b': o << "\\b"; break;
+            case '\f': o << "\\f"; break;
+            case '\n': o << "\\n"; break;
+            case '\r': o << "\\r"; break;
+            case '\t': o << "\\t"; break;
+            default:
+                if ('\x00' <= c && c <= '\x1f') {
+                    o << "\\u" << std::hex << std::setw(4) << std::setfill('0') << (int)(unsigned char)c;
+                } else {
+                    o << c;
+                }
+        }
+    }
+    return o.str();
+}
+
+std::string HybridMarkdownParser::nodeToJson(const std::shared_ptr<InternalMarkdownNode>& node) {
+    std::ostringstream json;
+    json << "{";
+    json << "\"type\":\"" << ::NitroMarkdown::nodeTypeToString(node->type) << "\"";
+
+    if (node->content.has_value()) {
+        json << ",\"content\":\"" << escapeJson(node->content.value()) << "\"";
+    }
+    
+    if (node->level.has_value()) {
+        json << ",\"level\":" << node->level.value();
+    }
+    
+    if (node->href.has_value()) {
+        json << ",\"href\":\"" << escapeJson(node->href.value()) << "\"";
+    }
+    
+    if (node->title.has_value()) {
+        json << ",\"title\":\"" << escapeJson(node->title.value()) << "\"";
+    }
+    
+    if (node->alt.has_value()) {
+        json << ",\"alt\":\"" << escapeJson(node->alt.value()) << "\"";
+    }
+    
+    if (node->language.has_value()) {
+        json << ",\"language\":\"" << escapeJson(node->language.value()) << "\"";
+    }
+    
+    if (node->ordered.has_value()) {
+        json << ",\"ordered\":" << (node->ordered.value() ? "true" : "false");
+    }
+    
+    if (node->start.has_value()) {
+        json << ",\"start\":" << node->start.value();
+    }
+    
+    if (node->checked.has_value()) {
+        json << ",\"checked\":" << (node->checked.value() ? "true" : "false");
+    }
+    
+    if (node->isHeader.has_value()) {
+        json << ",\"isHeader\":" << (node->isHeader.value() ? "true" : "false");
+    }
+    
+    if (node->align.has_value()) {
+        std::string alignStr = ::NitroMarkdown::textAlignToString(node->align.value());
+        if (!alignStr.empty()) {
+            json << ",\"align\":\"" << alignStr << "\"";
+        }
+    }
+
+    if (!node->children.empty()) {
+        json << ",\"children\":[";
+        for (size_t i = 0; i < node->children.size(); ++i) {
+            if (i > 0) json << ",";
+            json << nodeToJson(node->children[i]);
+        }
+        json << "]";
+    }
+    
+    json << "}";
+    return json.str();
+}
+
+} // namespace margelo::nitro::NitroMarkdown

package/cpp/bindings/HybridMarkdownParser.hpp

@@ -0,0 +1,28 @@
+#pragma once
+
+#include "HybridMarkdownParserSpec.hpp"
+#include "../core/MD4CParser.hpp"
+#include <memory>
+
+namespace margelo::nitro::NitroMarkdown {
+
+using InternalMarkdownNode = ::NitroMarkdown::MarkdownNode;
+using InternalParserOptions = ::NitroMarkdown::ParserOptions;
+
+class HybridMarkdownParser : public HybridMarkdownParserSpec {
+public:
+    HybridMarkdownParser() : HybridObject(TAG), HybridMarkdownParserSpec() {
+        parser_ = std::make_unique<::NitroMarkdown::MD4CParser>();
+    }
+    
+    ~HybridMarkdownParser() override = default;
+
+    std::string parse(const std::string& text) override;
+    std::string parseWithOptions(const std::string& text, const ParserOptions& options) override;
+
+private:
+    std::unique_ptr<::NitroMarkdown::MD4CParser> parser_;
+    std::string nodeToJson(const std::shared_ptr<InternalMarkdownNode>& node);
+};
+
+} // namespace margelo::nitro::NitroMarkdown