Skip to main content

​
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-Viewer

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.

​
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

CapabilitySolution
Base MarkdownCommonMark spec + markdown-it
Math formulasKaTeX
Chemical equationsmhchem
Chemical structuresSmilesDrawer
Code highlightinghighlight.js
DiagramsMermaid

​
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

CapabilitySolution
Base MarkdownCommonMark spec + markdown-it
Math formulasKaTeX
Chemical equationsmhchem
Chemical structuresSmilesDrawer
Code highlightinghighlight.js
DiagramsMermaid (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.

​
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:
ClassDescription
theme-lightLight theme (default), suitable for general reading
theme-darkDark theme for low-light environments — deep colors with high contrast
theme-academicAcademic 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