Overview - SoMark Docs

What is SoMarkDown?

In an age of information overload, the way we create content shapes how knowledge is preserved and shared. Markdown has become the foundational syntax of digital writing. Yet as knowledge expands—from complex math equations and precise chemical structures to interactive code blocks and semantic text annotations—existing markup languages often struggle to balance expressiveness with simplicity. SoMarkDown is an open-source markup language specification designed to bring together community wisdom, embrace professional expression, and become the de facto standard for the future.

SoMarkDown

Markup language spec and reference implementation

SoMarkDownViewer

Ready-to-use web rendering component

gradio_somarkdown

SoMarkDown rendering component for Gradio

SoMarkDown doesn’t reinvent the wheel. After careful research, it integrates and refines widely adopted community rendering solutions.

SoMarkDownViewer

SoMarkDownViewer is a ready-to-use web rendering component for displaying SoMarkDown content in the browser. It is suitable for document viewers, parsed result previews, and knowledge-base reading experiences.

Repository: SoMarkAI/SoMarkDownViewer
Best for: rendering SoMarkDown content directly in web pages

gradio_somarkdown

gradio_somarkdown is a custom Gradio component that brings SoMarkDown rendering into Python apps. It can replace gr.Markdown and supports KaTeX math, SMILES chemical structures, mhchem equations, syntax-highlighted code blocks, and TOC rendering.

Repository: SoMarkAI/gradio_somarkdown
Best for: rendering SoMarkDown output in Gradio apps (for example, parsed document results, scientific content, and technical reports)

Technology Stack

Capability	Solution
Base Markdown	CommonMark spec + markdown-it
Math formulas	KaTeX
Chemical equations	mhchem
Chemical structures	SmilesDrawer
Code highlighting	highlight.js
Diagrams	Mermaid

Key Features

🧬 Core capabilities:

Markdown Superset: Compliant with CommonMark specification, fully compatible with standard Markdown.
Paragraph Mapping: Automatic injection of line number attributes, enabling synchronized scrolling and mapping navigation similar to VSCode’s Markdown implementation.
High-Speed Rendering: Optimized based on markdown-it, delivering fast rendering performance with support for large document processing.
Multiple Themes: Built-in support for light, dark, and academic themes.
Universal Compatibility: Supports both browser and Node.js server-side rendering.

✨ Specialized Components:

📐 Mathematical Formulas: Integrated KaTeX support for LaTeX math expressions, including mhchem chemical equation extensions.
🧪 Chemical Structures: Integrated SmilesDrawer for rendering SMILES strings. Innovatively supports syntax merging between LaTeX and SMILES, greatly expanding chemical structure expression capabilities.
🎨 Code Syntax Highlighting: Automatic detection and highlighting via highlight.js.
📑 Table of Contents: Automatic TOC generation.
🖼️ Image Understanding: Support for image semantic descriptions and display.
🏷️ Caption Support: Support for figure and table captions.

Technology Stack

Capability	Solution
Base Markdown	CommonMark spec + markdown-it
Math formulas	KaTeX
Chemical equations	mhchem
Chemical structures	SmilesDrawer
Code highlighting	highlight.js
Diagrams	Mermaid (in development)

Relationship with SoMark API

The Markdown output from the SoMark Document Intelligence API follows the SoMarkDown specification. Math formulas, chemical structures, tables, and image semantic descriptions in parsed results all render correctly in any SoMarkDown-compatible renderer. If you want to start from the integration side first, see SoMark API or SoMark SDK.

Installation

npm:

npm install somarkdown

CDN (browser):

<script src="https://cdn.jsdelivr.net/npm/somarkdown/dist/somarkdown.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/somarkdown/dist/somarkdown.css">

Build from source:

git clone https://github.com/SoMarkAI/SoMarkDown.git
cd somarkdown
npm install
npm run build

Basic Usage

The project includes a browser example in example/browser. After compilation, open example/browser/index.html directly to view the demo.

import SoMarkDown from 'somarkdown';
import 'somarkdown/dist/somarkdown.css';

const somarkdown = new SoMarkDown({
  lineNumbers: { enable: true }
});

const markdown = `
# SoMarkDown Demo

## Math
$$ E = mc^2 $$

## Chemical Structure
$$\\smiles{CC(=O)Oc1ccccc1C(=O)O}$$

## Chemistry (mhchem)
$$ \\ce{CO2 + C -> 2 CO} $$
`;

const html = somarkdown.render(markdown);
console.log(html);

Configuration

const config = {
  linkify: true,        // Automatically convert URL-like text to links
  typographer: true,    // Enable language-neutral replacements + quotes beautification

  imgDescEnabled: true, // Whether to display image semantic descriptions

  lineNumbers: {
    enable: true,       // Enable line number injection (for bidirectional sync)
    nested: true        // Inject line numbers for nested blocks (list items, quotes, etc.)
  },

  katex: {
    throwOnError: false,
    errorColor: '#cc0000'
  },
  toc: {
    includeLevel: [1, 2, 3]  // Heading levels to include in TOC
  },
  smiles: {
    disableColors: false,
    width: 300,
    height: 200
  }
};

const somarkdown = new SoMarkDown(config);

Full configuration options are available in src/core/config.js.

Themes

SoMarkDown includes built-in themes imported via somarkdown.css. Apply a theme class to the container element:

Class	Description
`theme-light`	Light theme (default), suitable for general reading
`theme-dark`	Dark theme for low-light environments — deep colors with high contrast
`theme-academic`	Academic theme optimized for research papers — strong contrast and larger fonts

JS API

`new SoMarkDown(config)`

Creates a new renderer instance.

`render(src: string): string`

Renders SoMarkDown source to an HTML string.

License

MIT License

​What is SoMarkDown?

SoMarkDown

SoMarkDownViewer

gradio_somarkdown

​Related projects

​SoMarkDownViewer

​gradio_somarkdown

​Technology Stack

​Key Features

​Technology Stack

​Relationship with SoMark API

​Installation

​Basic Usage

​Configuration

​Themes

​JS API

​new SoMarkDown(config)

​render(src: string): string

​License

What is SoMarkDown?

Related projects

SoMarkDownViewer

gradio_somarkdown

Technology Stack

Key Features

Technology Stack

Relationship with SoMark API

Installation

Basic Usage

Configuration

Themes

JS API

`new SoMarkDown(config)`

`render(src: string): string`

License