sommark 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+
+## v2.3.0 (2026-02-23)
+
+### Added
+
+* Added missing JSON support in the CLI.
+* Added two new methods: makeFrontmatter and raw_js_imports.
+* Added new documentation.
+
+### Fixed
+
+* Fixed MDX format output error caused by extra whitespaces.
+* Fixed colon issue in atblock body.
+
+### Improved
+
+* Improved several internal methods.
+* Updated and enhanced tests.
+
+
 ## v2.2.0 (2026-02-23)
 ## Features
 - Added JSON support

package/README.md

@@ -5,15 +5,37 @@ SomMark is a declarative, extensible markup language for structured content that
 </p>
 
 <p align="center">
+<!--License-->
+<a href="https://www.npmjs.com/package/sommark" target="_blank">
 <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
+</a>
+
+<!--Npm Version-->
+<a href="https://www.npmjs.com/package/sommark" target="_blank">
 <img src="https://img.shields.io/npm/v/sommark?style=flat-square" />
-<img src="https://img.shields.io/badge/type-markup%20language-purple?style=flat-square" />
-<img src="https://img.shields.io/badge/html-supported-orange?style=flat-square" />
-<img src="https://img.shields.io/badge/markdown-supported-lightyellow?style=flat-square" />
-<img src="https://img.shields.io/badge/mdx-supported-lightblue?style=flat-square" />
-<img src="https://img.shields.io/badge/json-supported-yellow?style=flat-square" />
+</a>
+
+<!--Language Type-->
+<img src="https://img.shields.io/badge/type-markup%20language-white?style=flat-square" />
+
+<!--SomMark Playground-->
+<a href="https://adam-elmi.github.io/SomMark-Playground" target="_blank">
+<img 
+src="https://img.shields.io/badge/SomMark-Playground-blue?style=flat-square" 
+alt="SomMark Playground Badge" />
+</a>
 </p>
 
+
+----
+
+## Try SomMark Playground
+
+Test SomMark features live here:
+[https://adam-elmi.github.io/SomMark-Playground/](https://adam-elmi.github.io/SomMark-Playground/)
+
+----
+
 # SomMark v2
 
 > [!WARNING]
@@ -21,7 +43,6 @@ SomMark is a declarative, extensible markup language for structured content that
 
 **SomMark** lets you write structured content that can be converted to HTML, Markdown, JSON, or other formats. Unlike standard Markdown, it uses explicit syntax for blocks and elements, making content easier to process, customize, and transform.
 
-
 # Installation
 
 To install the Command Line Interface (CLI) globally:
@@ -58,20 +79,28 @@ Hello World
 `;
 
 const smark = new SomMark({
-    src: source,
-    format: "html"
+	src: source,
+	format: "html"
 });
 
 console.log(await smark.transpile());
 ```
 
+## Supported Languages
+
+* HTML
+* Markdown
+* MDX (Only ready components)
+* JSON
+
+
 # Documentation
 
 Detailed guides and API references are available in the `docs/` directory:
 
-*   **[Syntax Guide](docs/syntax.md)**: Master SomMark syntax (Blocks, Inline, At-Blocks).
-*   **[Core API](docs/core.md)**: Programmatic usage of the library (`transpile`, `lex`, `parse`).
-*   **[Mapper API](docs/mapper.md)**: Guide for creating custom mappers and rules.
-*   **[CLI Reference](docs/cli.md)**: Command line options and configurations.
-*   **[API Quick Reference](docs/api)**: Fast lookup for all classes and functions.
-*   **[Configuration Reference](docs/config.md)**: Guide for creating custom configurations.
+- **[Syntax Guide](docs/syntax.md)**: Master SomMark syntax (Blocks, Inline, At-Blocks).
+- **[Core API](docs/core.md)**: Programmatic usage of the library (`transpile`, `lex`, `parse`).
+- **[Mapper API](docs/mapper.md)**: Guide for creating custom mappers and rules.
+- **[CLI Reference](docs/cli.md)**: Command line options and configurations.
+- **[API Quick Reference](docs/api)**: Fast lookup for all classes and functions.
+- **[Configuration Reference](docs/config.md)**: Guide for creating custom configurations.

package/cli/commands/build.js

@@ -4,6 +4,7 @@ import { cliError, formatMessage } from "../../core/errors.js";
 import HTML from "../../mappers/languages/html.js";
 import MARKDOWN from "../../mappers/languages/markdown.js";
 import MDX from "../../mappers/languages/mdx.js";
+import Json from "../../mappers/languages/json.js";
 import { extensions } from "../constants.js";
 import { isExist, readContent, createFile } from "../helpers/file.js";
 import { loadConfig } from "../helpers/config.js";
@@ -56,7 +57,7 @@ export async function runBuild(format_option, sourcePath, outputFlag, outputFile
                 let mappingFile = config.mappingFile;
 
                 if (!mappingFile) {
-                    mappingFile = format === "html" ? HTML : format === "markdown" ? MARKDOWN : format === "mdx" ? MDX : null;
+                    mappingFile = format === "html" ? HTML : format === "markdown" ? MARKDOWN : format === "mdx" ? MDX : format === "json" ? Json : null;
                 }
 
                 // CLI Overrides

package/cli/commands/help.js

@@ -6,40 +6,41 @@ import { options } from "../constants.js";
 // ========================================================================== //
 
 export function getHelp(unknown_option = true) {
-    const msg = [
-        `${unknown_option && process.argv[2] ? `<$red:Unrecognized option$> <$blue: '${process.argv[2]}'$>` : ""}`,
-        "{N}<$yellow:Usage:$> <$blue:sommark [option]$>",
+	const msg = [
+		`${unknown_option && process.argv[2] ? `<$red:Unrecognized option$> <$blue: '${process.argv[2]}'$>` : ""}`,
+		"{N}<$yellow:Usage:$> <$blue:sommark [option]$>",
 
-        "{N}{N}<$yellow:Global Options:$>",
-        "{N}  <$green:-h, --help$>     <$cyan: Show help message$>",
-        "{N}  <$green:-v, --version$>  <$cyan: Show version information$>",
-        "{N}  <$green:init$>           <$cyan: Initialize global SomMark configuration directory$>",
-        "{N}  <$green:show config$>    <$cyan: Display the absolute paths to the active SomMark configuration files$>",
+		"{N}{N}<$yellow:Global Options:$>",
+		"{N}  <$green:-h, --help$>     <$cyan: Show help message$>",
+		"{N}  <$green:-v, --version$>  <$cyan: Show version information$>",
+		"{N}  <$green:init$>           <$cyan: Initialize global SomMark configuration directory$>",
+		"{N}  <$green:show config$>    <$cyan: Display the absolute paths to the active SomMark configuration files$>",
 
-        "{N}{N}<$yellow:Transpilation Options:$>",
-        "{N}<$yellow:Usage:$> <$blue:sommark [option] [targetFile] [option] [outputFile] [outputDir]$>",
-        "{N}  <$green:--html$>         <$cyan: Transpile to HTML$>",
-        "{N}  <$green:--markdown$>     <$cyan: Transpile to Markdown$>",
-        "{N}  <$green:--mdx$>          <$cyan: Transpile to MDX$>",
-        "{N}  <$green:--text$>         <$cyan: Transpile to plain text$>",
+		"{N}{N}<$yellow:Transpilation Options:$>",
+		"{N}<$yellow:Usage:$> <$blue:sommark [option] [targetFile] [option] [outputFile] [outputDir]$>",
+		"{N}  <$green:--html$>         <$cyan: Transpile to HTML$>",
+		"{N}  <$green:--markdown$>     <$cyan: Transpile to Markdown$>",
+		"{N}  <$green:--mdx$>          <$cyan: Transpile to MDX$>",
+		"{N}  <$green:--json$>         <$cyan: Transpile to json$>",
+		"{N}  <$green:--text$>         <$cyan: Transpile to plain text$>",
 
-        "{N}{N}<$yellow:Output Options:$>",
-        "{N}  <$green:-p, --print$>    <$cyan: Print output to console (stdout)$>",
-        "{N}  <$green:-o$>             <$cyan: Specify output filename (and optionally directory)$>",
+		"{N}{N}<$yellow:Output Options:$>",
+		"{N}  <$green:-p, --print$>    <$cyan: Print output to console (stdout)$>",
+		"{N}  <$green:-o$>             <$cyan: Specify output filename (and optionally directory)$>",
 
-        "{N}{N}<$yellow:Examples:$>",
-        "{N}  <$magenta:1. Basic usage:$> <$blue:sommark --html input.smark$>",
-        "{N}  <$magenta:2. Print to console:$> <$blue:sommark --html -p input.smark$>",
-        "{N}  <$magenta:3. Custom output:$> <$blue:sommark --html input.smark -o myOutput ./dist/$>"
-    ].join("");
-    const help_msg = formatMessage(msg);
+		"{N}{N}<$yellow:Examples:$>",
+		"{N}  <$magenta:1. Basic usage:$> <$blue:sommark --html input.smark$>",
+		"{N}  <$magenta:2. Print to console:$> <$blue:sommark --html -p input.smark$>",
+		"{N}  <$magenta:3. Custom output:$> <$blue:sommark --html input.smark -o myOutput ./dist/$>"
+	].join("");
+	const help_msg = formatMessage(msg);
 
-    if (!options.includes(process.argv[2]) && unknown_option) {
-        console.log(help_msg);
-        process.exit(0);
-    } else if (process.argv[2] === "-h" || process.argv[2] === "--help") {
-        console.log(help_msg);
-        process.exit(0);
-    }
-    return help_msg;
+	if (!options.includes(process.argv[2]) && unknown_option) {
+		console.log(help_msg);
+		process.exit(0);
+	} else if (process.argv[2] === "-h" || process.argv[2] === "--help") {
+		console.log(help_msg);
+		process.exit(0);
+	}
+	return help_msg;
 }

package/cli/constants.js

@@ -2,11 +2,12 @@
 //  CLI Constants                                                             //
 // ========================================================================== //
 
-export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "--text", "--print", "-p"];
+export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "json", "--text", "--print", "-p"];
 
 export const extensions = {
-    text: "txt",
-    html: "html",
-    markdown: "md",
-    mdx: "mdx"
+	text: "txt",
+	html: "html",
+	markdown: "md",
+	mdx: "mdx",
+	json: "json"
 };

package/core/lexer.js

@@ -289,7 +289,6 @@ function lexer(src) {
 				i += temp_str.length - 1;
 				// Update Metadata
 				updateMetadata(temp_str);
-				scope_state = true;
 				addToken(TOKEN_TYPES.OPEN_AT, temp_str);
 				// is next token end keyword?
 				const endKey = concatChar(src, i + 1, ["_"]);
@@ -330,7 +329,8 @@ function lexer(src) {
 					previous_value === at_value ||
 					previous_value === BLOCKCOLON ||
 					previous_value === ATBLOCKCOLON ||
-					previous_value === INLINECOLON)
+					previous_value === INLINECOLON) &&
+				!scope_state
 			) {
 				// Update Metadata
 				updateMetadata(current_char);
@@ -391,6 +391,7 @@ function lexer(src) {
 				// Update Metadata
 				updateMetadata(current_char);
 				addToken(TOKEN_TYPES.SEMICOLON, current_char);
+				scope_state = true;
 				previous_value = current_char;
 			}
 			// ========================================================================== //
@@ -574,10 +575,11 @@ function lexer(src) {
 				//  Token: Text                                                               //
 				// ========================================================================== //
 				else {
+					if (previous_value === "_@+") scope_state = true;
 					context = concatText(src, i, scope_state, [
 						[":", previous_value === inline_id_2],
 						[",", previous_value === block_value || previous_value === at_value || previous_value === inline_value],
-						[":", previous_value === "_@+" || previous_value === at_value],
+						[":", (previous_value === "_@+" && !scope_state) || previous_value === at_value],
 						[";", previous_value === at_value],
 						[")", previous_value === inline_value]
 					]);

package/core/transpiler.js

@@ -119,10 +119,11 @@ async function generateOutput(ast, i, format, mapper_file) {
 	const block_formats = [htmlFormat, mdxFormat, jsonFormat];
 	if (target) {
 		validateRules(target, node.args, "", node.type);
+		const placeholder = format === mdxFormat && node.body.length > 1 ? "\n<%smark>\n" : "<%smark>";
 		result += block_formats.includes(format)
-			? `${target.render({ args: node.args, content: "<%smark>", ast: expose_for_fmts.includes(format) ? ast[i] : null })}`
-      : target.render({ args: node.args, content: "" });
-    // Body nodes
+			? `${format === mdxFormat ? "\n" : ""}${target.render({ args: node.args, content: placeholder, ast: expose_for_fmts.includes(format) ? ast[i] : null }) + (format === mdxFormat ? "\n" : "")}`
+			: target.render({ args: node.args, content: "" }) + (format === mdxFormat ? "\n" : "");
+		// Body nodes
 		for (let j = 0; j < node.body.length; j++) {
 			const body_node = node.body[j];
 			switch (body_node.type) {
@@ -141,10 +142,11 @@ async function generateOutput(ast, i, format, mapper_file) {
 					target = matchedValue(mapper_file.outputs, body_node.id);
 					if (target) {
 						validateRules(target, body_node.args, body_node.value, body_node.type);
-						context += target.render({
-							args: body_node.args.length > 0 ? body_node.args : [],
-							content: format === htmlFormat || format === mdxFormat ? escapeHTML(body_node.value) : body_node.value
-						});
+						context +=
+							target.render({
+								args: body_node.args.length > 0 ? body_node.args : [],
+								content: format === htmlFormat || format === mdxFormat ? escapeHTML(body_node.value) : body_node.value
+							}) + (format === mdxFormat ? "\n" : "");
 					}
 					break;
 				// ========================================================================== //
@@ -159,7 +161,7 @@ async function generateOutput(ast, i, format, mapper_file) {
 						if (shouldEscape) {
 							body_node.content = escapeHTML(body_node.content);
 						}
-						context += target.render({ args: body_node.args, content: body_node.content });
+						context += target.render({ args: body_node.args, content: body_node.content }) + (format === mdxFormat ? "\n" : "");
 					}
 					break;
 				// ========================================================================== //

package/formatter/mark.js

@@ -1,5 +1,5 @@
 class MarkdownBuilder {
-	constructor() { }
+	constructor() {}
 	// ========================================================================== //
 	//  Headings                                                                  //
 	// ========================================================================== //
@@ -64,29 +64,23 @@ class MarkdownBuilder {
 	// ========================================================================== //
 	//  Code Block                                                                //
 	// ========================================================================== //
-	codeBlock(code, language) {
-		if (!code) {
-			return "";
-		}
-		const blocks = [];
-		if (Array.isArray(code)) {
-			for (const code_block of code) {
-				blocks.push(code_block);
-			}
-			if (!language) {
-				return "\n```" + "\n" + blocks.join("\n") + "\n```\n";
-			}
-			return "\n```" + language + "\n" + blocks.join("\n") + "\n```\n";
-		} else if (typeof code === "string") {
-			if (!language) {
-				return "\n```" + "\n" + code + "\n```\n";
-			}
-			return "\n```" + language + "\n" + code + "\n```\n";
-		}
-		if (!code && !language) {
+	codeBlock(code, language = "") {
+		if (!code) return "";
+
+		const normalizeContent = c => {
+			if (Array.isArray(c)) return c.join("\n");
+			if (typeof c === "string") return c;
 			return "";
-		}
+		};
+
+		const content = normalizeContent(code);
+
+		if (!content) return "";
+
+		const lang = language ? language : "";
+		return `\n\`\`\`${lang}\n${content}\`\`\`\n`;
 	}
+
 	// ========================================================================== //
 	//  Horizontal rule                                                           //
 	// ========================================================================== //
@@ -97,22 +91,13 @@ class MarkdownBuilder {
 	//  Escape                                                                    //
 	// ========================================================================== //
 	escape(text) {
-		const special_char = ["\\", "*", "_", "{", "}", "[", "]", "(", ")", "#", "+", "-", ".", "!", ">", "|"];
-		if (!text) {
-			return "";
-		}
+		if (!text) return "";
 
-		text = text
-			.split("")
-			.map(char => {
-				if (special_char.includes(char)) {
-					return `\\${char}`;
-				}
-				return char;
-			})
-			.join("");
-		return text;
+		const special = /[\\*_{}\[\]()#+\-.!>|]/g;
+
+		return text.replace(special, "\\$&");
 	}
+
 	// ========================================================================== //
 	//  Table                                                                     //
 	// ========================================================================== //
@@ -133,15 +118,15 @@ class MarkdownBuilder {
 			}
 			rows = rows.map(row => {
 				let columns;
-				if (typeof row === 'string') {
-					columns = row.split(',').map(c => c.trim());
+				if (typeof row === "string") {
+					columns = row.split(",").map(c => c.trim());
 				} else if (Array.isArray(row)) {
 					columns = row.map(c => String(c).trim());
 				} else {
 					return "";
 				}
 
-				if (columns.length > 0 && columns[0].startsWith('-')) {
+				if (columns.length > 0 && columns[0].startsWith("-")) {
 					columns[0] = `- ${columns[0].substring(1).trim()}`;
 				}
 

package/formatter/tag.js

@@ -38,16 +38,16 @@ class TagBuilder {
 	props(propsList) {
 		const list = Array.isArray(propsList) ? propsList : [propsList];
 		if (list.length > 0) {
-			for (const propEntry of list) {
+      for (const propEntry of list) {
 				if (typeof propEntry !== "object" || propEntry === null) {
-					throw new TypeError("prop expects an object with property { type }");
+					throw new TypeError("prop expects an object with property { __type__ }");
 				}
 
-				if (!Object.prototype.hasOwnProperty.call(propEntry, "type")) {
-					throw new TypeError("prop expects an object with property { type }");
+				if (!Object.prototype.hasOwnProperty.call(propEntry, "__type__")) {
+					throw new TypeError("prop expects an object with property { __type__ }");
 				}
 
-				const { type, ...rest } = propEntry;
+				const { __type__, ...rest } = propEntry;
 				const entries = Object.entries(rest);
 
 				if (entries.length === 0) {
@@ -56,7 +56,7 @@ class TagBuilder {
 
 				const [key, value] = entries[0];
 
-				switch (type) {
+				switch (__type__) {
 					case "string":
 						this.#attr.push(`${key}="${escapeHTML(String(value))}"`);
 						break;

package/mappers/mapper.js

@@ -27,7 +27,7 @@ class Mapper {
 		};
 
 		this.#customHeaderContent = "";
-
+		
 		this.highlightCode = null;
 		this.escapeHTML = escapeHTML;
 		this.styles = [];
@@ -358,5 +358,53 @@ class Mapper {
 
 		return fallBack;
 	};
+	makeFrontmatter = entries => {
+		if (!entries || typeof entries !== "object") {
+			console.warn(`From function: ${this.makeFrontmatter.name}: invalid entries, returning empty string.`);
+			return "";
+		}
+		const keys = Object.keys(entries);
+		if (keys.length === 0) {
+			console.warn(`From function: ${this.makeFrontmatter.name}: invalid entries, returning empty string.`);
+			return "";
+		}
+		const body = keys
+			.map(key => {
+				const value = entries[key];
+				if (Array.isArray(value)) {
+					const list = value.map(item => `  - ${JSON.stringify(item)}`).join("\n");
+					return `${key}:\n${list}`;
+				}
+				return `${key}: ${JSON.stringify(value)}`;
+			})
+			.join("\n");
+		return `---\n${body}\n---\n`;
+	};
+
+	raw_js_imports = imports => {
+		if (!Array.isArray(imports)) {
+			console.warn("raw_js_imports: imports must be an array");
+			return "";
+		}
+
+		if (imports.length === 0) {
+			console.warn("raw_js_imports: imports array is empty");
+			return "";
+		}
+
+		return imports
+			.map((imp, index) => {
+				if (!imp?.name || !imp?.path) {
+					console.warn(`raw_js_imports: invalid import entry at index ${index}`);
+					return "";
+				}
+
+				const path = JSON.stringify(imp.path);
+				const newline = index === imports.length - 1 ? "\n\n" : "\n";
+
+				return `import ${imp.name} from ${path};${newline}`;
+			})
+			.join("");
+	};
 }
 export default Mapper;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sommark",
-	"version": "2.2.0",
+	"version": "2.3.0",
 	"description": "SomMark is a structural markup language for writing structured documents and converting them into HTML or Markdown or MDX(only ready components).",
 	"main": "index.js",
 	"directories": {