> ## Documentation Index > Fetch the complete documentation index at: https://docs.somark.cn/llms.txt > Use this file to discover all available pages before exploring further. # Overview > An open-source enhanced markup language spec built for math, chemistry, code, and beyond ## 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 Markup language spec and reference implementation Ready-to-use web rendering component SoMarkDown rendering component for Gradio SoMarkDown doesn’t reinvent the wheel. After careful research, it integrates and refines widely adopted community rendering solutions. ## Related projects ### 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](https://github.com/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](https://github.com/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](https://spec.commonmark.org/) + [markdown-it](https://github.com/markdown-it/markdown-it) | | Math formulas | [KaTeX](https://katex.org) | | Chemical equations | [mhchem](https://mhchem.github.io/MathJax-mhchem) | | Chemical structures | [SmilesDrawer](https://github.com/reymond-group/smilesDrawer) | | Code highlighting | [highlight.js](https://github.com/highlightjs/highlight.js) | | Diagrams | [Mermaid](https://github.com/mermaid-js/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](https://katex.org/) support for LaTeX math expressions, including `mhchem` chemical equation extensions. * **🧪 Chemical Structures**: Integrated [SmilesDrawer](https://github.com/reymond-group/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](https://highlightjs.org/). * **📑 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](https://spec.commonmark.org/) + [markdown-it](https://github.com/markdown-it/markdown-it) | | Math formulas | [KaTeX](https://katex.org) | | Chemical equations | [mhchem](https://mhchem.github.io/MathJax-mhchem) | | Chemical structures | [SmilesDrawer](https://github.com/reymond-group/smilesDrawer) | | Code highlighting | [highlight.js](https://github.com/highlightjs/highlight.js) | | Diagrams | [Mermaid](https://github.com/mermaid-js/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](/en/documentation/api) or [SoMark SDK](/en/documentation/sdk). ## Installation **npm:** ```bash theme={null} npm install somarkdown ``` **CDN (browser):** ```html theme={null} ``` **Build from source:** ```bash theme={null} 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. ```javascript theme={null} 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 ```javascript theme={null} 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](https://github.com/SoMarkAI/SoMarkDown/blob/master/LICENSE)