sommark 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2.2.0 (2026-02-23)
+## Features
+- Added JSON support
+- Added type rules to validate element type
+- Improved documentation
+- Improved mapper files
+- Removed **highlight.js** dependency
+- Added new CLI feature: automatic configuration file creation
+
+
 ## v2.1.2 (2026-02-09)
 ### Fixes
 -  Fixed cli print functionality

package/README.md

@@ -1,7 +1,7 @@
 <img width="2000" height="491" alt="SomMark Cover" src="https://raw.githubusercontent.com/Adam-Elmi/SomMark/master/assets/smark_bg.png" />
 
 <p align="center">
-  SomMark is a structural markup language designed for technical documentation. It focuses on explicit structure and flexibility.
+SomMark is a declarative, extensible markup language for structured content that can be converted to HTML, Markdown, MDX, JSON, and more. 
 </p>
 
 <p align="center">
@@ -11,6 +11,7 @@
 <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" />
 </p>
 
 # SomMark v2
@@ -18,118 +19,8 @@
 > [!WARNING]
 > Old version(v1) is no longer supported.
 
-SomMark provides a way to write structured content that can be converted into other formats like HTML or Markdown. It is different from standard Markdown because it uses explicit syntax for blocks and elements, which makes it easier to process and customize.
+**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.
 
-# Features
-
-*   **Explicit Syntax**: Every element has a clear start and end, which reduces parsing errors.
-*   **Customizable Mappers**: You can convert SomMark content into any format (HTML, Markdown, JSON, etc.) by using Mappers.
-*   **Validation**: You can define rules to check your content, such as limiting the number of arguments or requiring specific keys.
-*   **MDX Support**: SomMark can map to existing React components ("Only Ready Components").
-> [!NOTE]
-> SomMark does not parse raw JSX. It only maps to ready components.
-
-# Syntax
-
-SomMark uses three main types of elements: Blocks, Inline Statements, and At-Blocks.
-
-## 1. Block
-
-A Block is a container that holds content. It can contain text or other nested blocks.
-
-**With Arguments**
-You can pass data to a block using arguments. Arguments can have keys.
-```ini
-[Alert = urgent, title: Warning]
-System maintenance in 10 minutes.
-This block uses a flag (urgent) and a key-value pair (title).
-[end]
-```
-> [!NOTE]
-> The colon `:` separates keys and values.
-> Keys are optional.
-
-**Without Arguments**
-```ini
-[Note]
-This is a simple block.
-[end]
-```
-
-## 2. Inline Statement
-
-Inline Statements are used to format specific parts of text.
-
-**With Arguments**
-```ini
-This text is (bold)->(bold) and this is (red)->(color: red).
-```
-> [!NOTE]
-> Inline arguments are values only. Keys are not supported.
-
-**Without Arguments**
-```ini
-(Click here)->(Button)
-```
-
-## 3. At-Block
-
-At-Blocks are used for specific content like code snippets or tables. The content inside an At-Block is treated as plain text and cannot contain other SomMark elements.
-
-**With Arguments**
-```ini
-@_Code_@: javascript;
-console.log("This is raw code.");
-@_end_@
-```
-> [!NOTE]
-> You must use a semi-colon `;` to end the argument list.
-
-**Without Arguments**
-```ini
-@_Raw_@
-Raw content here.
-@_end_@
-```
-
-## General Rules
-* SomMark Top-Level Rules:
-  - Only Blocks and comments are allowed at the top level.
-  - Inline Statements, Atblocks, and text cannot appear at the top level. They must be inside a Block, or it is invalid.
-  **Invalid Top-Level:**
-  ```ini
-  Hello world             ❌  (Text cannot be at top level)
-  
-  Welcome to (SomMark)->(Bold)         ❌  (Inline statement cannot be at top level)
-  
-  @_Code_@: js;
-  function add(a, b) {
-    return a + b;
-  }
-  @_end_@                 ❌  (Atblock cannot be at top level)
-  ```
-  
-  **Valid Top-Level:**
-  ```ini
-  [Block]
-    Hello world 
-    Welcome to (SomMark)->(Bold)          # Inline statement inside block is valid
-  
-    @_Code_@: js;
-    function add(a, b) {
-      return a + b;                        # Treated as plain text
-    }       
-    @_end_@
-  
-  [end]
-  ```
-
-
-*   **Identifiers**: Names can only contain letters and numbers.
-*   **Escape Character**: Use the backslash `\` to escape special characters (like colons or commas) inside arguments.
-*   **Colons**: inside Block and At-Block arguments, the colon (`:`) separates names from values.
-*   **Semi-Colons**: The semi-colon (`;`) is only used in At-Blocks to assert the end of the argument list.
-*   **Whitespace**: SomMark ignores extra spaces and newlines, so you can format your code however you like.
 
 # Installation
 
@@ -184,190 +75,3 @@ Detailed guides and API references are available in the `docs/` directory:
 *   **[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.
-
-
-
-# Configuration (Only for CLI)
-
-You can create a `smark.config.js` file to configure the CLI.
-
-```javascript
-/* smark.config.js */
-import myMapper from "./my-mapper.js";
-
-export default {
-    outputFile: "output",    // Default output filename
-    outputDir: "./dist",     // Where to save files
-    mappingFile: myMapper    // Use a custom mapper by default
-};
-```
-
-# Creating Custom Mappers
-
-Mappers tell SomMark how to convert your content. You can define rules, options, and how arguments are handled.
-
-## Basic Structure
-
-```javascript
-import { Mapper } from "sommark";
-const myMapper = new Mapper();
-const { tag } = myMapper;
-
-// Define a Block
-myMapper.register("Alert", ({ args, content }) => {
-    // Access arguments by index or name
-    const type = args[0] || args.type || "info"; 
-    
-    // Use TagBuilder to create HTML elements safely
-    return myMapper.tag("div")
-        .attributes({ class: `alert ${type}` })
-        .body(content);
-});
-
-export default myMapper;
-```
-> [!WARNING]
-> The `.body()` and `.selfClose()` methods return the final HTML string. You must treat them as the end of the builder chain. If you forget to call them, you will return a builder object instead of a string.
-
-You also skip tag builder and use raw HTML.
-
-```javascript
-import { Mapper } from "sommark";
-const myMapper = new Mapper();
-
-myMapper.register("Alert", ({ args, content }) => {
-    // Access arguments by index or name
-    const type = args[0] || args.type || "info"; 
-    
-    // Use raw HTML
-    return `<div class="alert ${type}">${content}</div>`;
-});
-```
-
-## Mapping Multiple Identifiers
-
-You can use an array of strings to map multiple names to the same output function.
-
-```javascript
-import { Mapper } from "sommark";
-const myMapper = new Mapper();
-const { tag } = myMapper;
-
-// Both [code] and [Code] will use this mapper
-myMapper.register(["code", "Code"], ({ content }) => {
-    return tag("pre").body(tag("code").body(content));
-});
-```
-
-## Reusing Existing Mappers
-
-You can borrow rules from default mappers to avoid rewriting them.
-
-```javascript
-import { Mapper, HTML } from "sommark";
-const myMapper = new Mapper();
-
-// Reuse the "Code" block from the default HTML mapper
-const codeOutput = HTML.get("Code");
-if (codeOutput) {
-    myMapper.register(codeOutput.id, codeOutput.render, codeOutput.options);
-}
-
-// Add your own custom blocks...
-myMapper.register("MyBlock", ({ content }) => {
-    return content;
-});
-
-export default myMapper;
-```
-
-## Using Rules (Validation)
-
-You can force strict rules on your content. If a rule is broken, SomMark will stop and show an error.
-
-### Argument Validation (`args`)
-
-Validates the arguments passed to the tag.
-
-```javascript
-myMapper.register("User", ({ args }) => {
-    return tag("div").body(`User: ${args[0]}`);
-}, {
-    rules: {
-        args: {
-            min: 1,           // Must have at least 1 argument
-            max: 3,           // Cannot have more than 3 arguments
-            required: ["id"], // The "id" named key is required
-            includes: ["id", "role", "age"] // Only these keys are allowed
-        }
-    }
-});
-```
-
-- **`min`**: Minimum number of arguments required.
-- **`max`**: Maximum number of arguments allowed.
-- **`required`**: Array of keys that MUST be present in the arguments.
-- **`includes`**: Whitelist of allowed argument keys. Any key not in this list will trigger an error.
-
-### Content Validation (`content`)
-
-Validates the inner content (body) of the block.
-
-```javascript
-myMapper.register("Summary", ({ content }) => {
-    return tag("p").body(content);
-}, {
-    rules: {
-        content: {
-            maxLength: 100 // Content must be 100 characters or less
-        }
-    }
-});
-```
-
-- **`maxLength`**: Maximum length of the content string.
-
-### Self-Closing Tags
-
-Ensures a tag is used without content or children.
-
-```javascript
-myMapper.register("Separator", () => {
-    return tag("hr").selfClose();
-}, {
-    rules: {
-        is_Self_closing: true
-    }
-});
-```
-
-- **`is_Self_closing`**: If `true`, SomMark will throw an error if the tag contains any content.
-
-*Example input that passes:* `[Image = src: image.png, alt: Image][end]`
-
-## Using Options
-
-Options change how SomMark processes the content inside the block.
-
-```javascript
-import { Mapper } from "sommark";
-const myMapper = new Mapper();
-const { tag } = myMapper;
-
-myMapper.register("Code", ({ content }) => {
-    return tag("pre").body(content);
-}, {
-    escape: false,
-    rules: {
-        args: {
-            min: 1,           
-            required: ["id"]
-        }
-    }
-    }); // options
-```
---- 
-
-# License
-
-MIT

package/cli/cli.mjs

@@ -3,6 +3,8 @@ import { getHelp } from "./commands/help.js";
 import { printVersion, printHeader } from "./commands/version.js";
 import { runBuild } from "./commands/build.js";
 import { printOutput } from "./commands/print.js";
+import { runInit } from "./commands/init.js";
+import { runShow } from "./commands/show.js";
 import { extensions } from "./constants.js";
 
 // ========================================================================== //
@@ -33,7 +35,19 @@ async function main() {
 		return;
 	}
 
-	// 4. Print to Console ( -p or --print )
+	// 4. Init
+	if (command === "init") {
+		await runInit();
+		return;
+	}
+
+	// 5. Show
+	if (command === "show") {
+		await runShow(args[1]);
+		return;
+	}
+
+	// 6. Print to Console ( -p or --print )
 
 	const format = command ? command.replace(/^--/, "") : "";
 

package/cli/commands/help.js

@@ -13,6 +13,8 @@ export function getHelp(unknown_option = true) {
         "{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]$>",

package/cli/commands/init.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { cliError, formatMessage } from "../../core/errors.js";
+
+// ========================================================================== //
+//  Init Command                                                              //
+// ========================================================================== //
+
+export function getConfigDir() {
+    const homeDir = os.homedir();
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA || path.join(homeDir, "AppData", "Roaming"), "sommark");
+    } else if (process.platform === "darwin") {
+        return path.join(homeDir, "Library", "Application Support", "sommark");
+    } else {
+        return path.join(process.env.XDG_CONFIG_HOME || path.join(homeDir, ".config"), "sommark");
+    }
+}
+
+export async function runInit() {
+    try {
+        const configDir = getConfigDir();
+        const pluginsDir = path.join(configDir, "plugins");
+        const configFilePath = path.join(configDir, "smark.config.js");
+
+        // ======================================================
+        // Create directories
+        // ======================================================
+
+        await fs.mkdir(pluginsDir, { recursive: true });
+
+        // ======================================================
+        // Default configuration content
+        // ======================================================
+
+        const defaultConfigContent = `export default {
+    outputDir: "",
+    outputFile: "output",
+    mappingFile: "",
+};
+`;
+
+        // ======================================================
+        // Check if config file already exists
+        // ======================================================
+
+        try {
+            await fs.access(configFilePath);
+            console.log(formatMessage(`<$yellow:Configuration already exists at:$> <$cyan:${configFilePath}$>`));
+        } catch {
+            // ======================================================
+            // Create default config file if it doesn't exist
+            // ======================================================
+
+            await fs.writeFile(configFilePath, defaultConfigContent, "utf-8");
+            console.log(formatMessage(`<$green:Initialized SomMark configuration at:$> <$cyan:${configFilePath}$>`));
+        }
+    } catch (error) {
+        cliError([
+            `{line}<$red:Failed to initialize SomMark configuration:$> <$magenta:${error.message}$>{line}`
+        ]);
+    }
+}

package/cli/commands/show.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { cliError, formatMessage } from "../../core/errors.js";
+import { getConfigDir } from "./init.js";
+
+// ========================================================================== //
+//  Show Command                                                              //
+// ========================================================================== //
+
+export async function runShow(target) {
+    if (target === "config") {
+        try {
+            const configDir = getConfigDir();
+            const configFilePath = path.join(configDir, "smark.config.js");
+            const pluginsDir = path.join(configDir, "plugins");
+            //========================================================================== //
+            //  Helper to check existence and format message                               //
+            //========================================================================== //
+            const checkPath = async (itemPath, isDir = false) => {
+                try {
+                    await fs.access(itemPath);
+                    return `<$green:${itemPath}$> <$cyan:(Exists)$>`;
+                } catch {
+                    return `<$red:${itemPath}$> <$yellow:(Not Found)$>`;
+                }
+            };
+
+            const configStatus = await checkPath(configFilePath);
+            const pluginsStatus = await checkPath(pluginsDir, true);
+
+            console.log(formatMessage(`{N}<$yellow:SomMark Configuration Files:$>{N}`));
+            console.log(formatMessage(`  <$magenta:Config File:$>    ${configStatus}`));
+            console.log(formatMessage(`  <$magenta:Plugins Dir:$>    ${pluginsStatus}{N}`));
+
+        } catch (error) {
+            cliError([
+                `{line}<$red:Failed to retrieve configuration paths:$> <$magenta:${error.message}$>{line}`
+            ]);
+        }
+    } else {
+        cliError([
+            `{line}<$red:Invalid target for 'show' command:$> <$blue:'${target || ""}'$> `,
+            `<$yellow:Usage:$> <$cyan:sommark show config$>{line}`
+        ]);
+    }
+}

package/cli/commands/version.js

@@ -14,7 +14,7 @@ export function printHeader() {
     console.log(
         [
             `SomMark-${projectJson.version}`,
-            "SomMark is a structural markup language for writing structured documents.",
+            "SomMark is a structural markup language for writing structured content.",
             "Copyright (C) Adam Elmi",
             "Github: https://github.com/Adam-Elmi/SomMark"
         ]

package/cli/helpers/config.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { isExist } from "./file.js";
+import { getConfigDir } from "../commands/init.js";
 
 // ========================================================================== //
 //  Configuration Loader                                                      //
@@ -8,7 +9,7 @@ import { isExist } from "./file.js";
 
 const CONFIG_FILE_NAME = "smark.config.js";
 const currentDir = process.cwd();
-const configPath = path.join(currentDir, CONFIG_FILE_NAME);
+const localConfigPath = path.join(currentDir, CONFIG_FILE_NAME);
 
 // ========================================================================== //
 //  Default Configuration                                                     //
@@ -16,7 +17,6 @@ const configPath = path.join(currentDir, CONFIG_FILE_NAME);
 let config = {
     outputFile: "output",
     outputDir: "",
-    mode: "default",
     mappingFile: ""
 };
 
@@ -24,13 +24,22 @@ let config = {
 //  Load Configuration                                                        //
 // ========================================================================== //
 export async function loadConfig() {
-    if (await isExist(configPath)) {
+    const userConfigPath = path.join(getConfigDir(), CONFIG_FILE_NAME);
+    let targetConfigPath = null;
+
+    if (await isExist(userConfigPath)) {
+        targetConfigPath = userConfigPath;
+    } else if (await isExist(localConfigPath)) {
+        targetConfigPath = localConfigPath;
+    }
+
+    if (targetConfigPath) {
         try {
-            const configURL = pathToFileURL(configPath).href;
+            const configURL = pathToFileURL(targetConfigPath).href;
             const loadedModule = await import(configURL);
             config = loadedModule.default || loadedModule;
         } catch (error) {
-            console.error(`Error loading configuration file ${CONFIG_FILE_NAME}:`, error.message);
+            console.error(`Error loading configuration file ${targetConfigPath}:`, error.message);
         }
     } else {
         // console.log(`${CONFIG_FILE_NAME} not found. Using default configuration.`);

package/core/formats.js

@@ -2,8 +2,9 @@ const formats = {
   textFormat: "text",
 	htmlFormat: "html",
 	markdownFormat: "markdown",
-	mdxFormat: "mdx"
+	mdxFormat: "mdx",
+	jsonFormat: "json"
 };
 
-export const {textFormat, htmlFormat, markdownFormat, mdxFormat} = formats;
+export const {textFormat, htmlFormat, markdownFormat, mdxFormat, jsonFormat} = formats;
 export default formats;

package/core/lexer.js

@@ -67,7 +67,9 @@ function concatText(input, index, scope_state, extraConditions = []) {
 			text += char;
 		}
 		if (!text) {
-			sommarkError([`{line}<$red:Concatenation failed:$> string value is  <$yellow:'${text}'$>{line}`]);
+			sommarkError([
+				`{line}From: <$magenta:concatText function:$>{N}<$red:Concatenation failed:$> string value is  <$yellow:'${text}'$>{line}`
+			]);
 		}
 		return text;
 	} else {
@@ -117,7 +119,9 @@ function concatEscape(input, index) {
 			sommarkError(["{line}<$red:Next character is not found:$> <$yellow:There is no character after escape character!$>{line}"]);
 		}
 		if (!str) {
-			sommarkError([`{line}<$red:Concatenation failed:$> string value is  <$yellow:'${str}'$>{line}`]);
+			sommarkError([
+				`{line}From: <$magenta:concatEscape function:$>{N}<$red:Concatenation failed:$> string value is  <$yellow:'${str}'$>{line}`
+			]);
 		}
 		if (WHITESPACE_SET.has(str[1])) {
 			const matchedCharacter = Array.from(WHITESPACE_SET).find(ch => ch === str[1]);
@@ -158,7 +162,9 @@ function concatChar(input, index, stop_at_char) {
 			]);
 		}
 		if (!str) {
-			sommarkError([`{line}<$red:Concatenation failed:$> string value is  <$yellow:'${str}'$>{line}`]);
+			sommarkError([
+				`{line}From: <$magenta:concatChar function:$>{N}<$red:Concatenation failed:$> string value is  <$yellow:'${str}'$>{line}`
+			]);
 		}
 		return str;
 	} else {
@@ -185,10 +191,10 @@ function lexer(src) {
 			tokens.push({ type, value, line, start, end, depth: depth_stack.length });
 		}
 
-		const updateMetadata = (text) => {
+		const updateMetadata = text => {
 			const newlines = updateNewLine(text) || 0;
 			if (newlines > 0) {
-				const lines = text.split('\n');
+				const lines = text.split("\n");
 				const lastLineLength = lines[lines.length - 1].length;
 				start = end + 1;
 				end = lastLineLength;
@@ -431,7 +437,13 @@ function lexer(src) {
 				// ========================================================================== //
 				//  Token: Block Value                                                        //
 				// ========================================================================== //
-				else if ((previous_value === "=" || previous_value === BLOCKCOMMA || previous_value === BLOCKCOLON || previous_value === block_value) && !scope_state) {
+				else if (
+					(previous_value === "=" ||
+						previous_value === BLOCKCOMMA ||
+						previous_value === BLOCKCOLON ||
+						previous_value === block_value) &&
+					!scope_state
+				) {
 					temp_str = concatChar(src, i, ["]", "\\", ",", ":"]);
 					i += temp_str.length - 1;
 					const nextToken = peek(src, i, 1);
@@ -484,12 +496,7 @@ function lexer(src) {
 						previous_value === inline_value) &&
 					!scope_state
 				) {
-					temp_str = concatChar(src, i, [
-						")",
-						"\\",
-						",",
-						previous_value === INLINECOLON ? ":" : null
-					]);
+					temp_str = concatChar(src, i, [")", "\\", ",", previous_value === INLINECOLON ? ":" : null]);
 					i += temp_str.length - 1;
 					// Update Metadata
 					updateMetadata(temp_str);
@@ -588,7 +595,7 @@ function lexer(src) {
 		return tokens;
 	} else {
 		lexerError([
-			`{line}<$red:Invalid SomMark syntax:$> <$yellow:Expected source input to be a string, got$> <$blue: '${typeof src}'$>{line}`
+			`{line}<$red:Invalid SomMark syntax:$> ${src === "" ? "<$yellow: Got empty string '' $>" : `<$yellow:Expected source input to be a string, got$> <$blue: '${typeof src}'$>`}{line}`
 		]);
 	}
 }