sommark 2.1.2 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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
+- 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,135 +1,47 @@
 <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">
+<!--License-->
+<a href="https://www.npmjs.com/package/sommark" target="_blank">
 <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
-<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" />
-</p>
-
-# SomMark v2
-
-> [!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.
-
-# 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.
+</a>
 
-## 1. Block
+<!--Npm Version-->
+<a href="https://www.npmjs.com/package/sommark" target="_blank">
+<img src="https://img.shields.io/npm/v/sommark?style=flat-square" />
+</a>
 
-A Block is a container that holds content. It can contain text or other nested blocks.
+<!--Language Type-->
+<img src="https://img.shields.io/badge/type-markup%20language-white?style=flat-square" />
 
-**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]
-```
+<!--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>
 
-## 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.
+## Try SomMark Playground
 
-**Without Arguments**
-```ini
-(Click here)->(Button)
-```
+Test SomMark features live here:
+[https://adam-elmi.github.io/SomMark-Playground/](https://adam-elmi.github.io/SomMark-Playground/)
 
-## 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.
+# SomMark v2
 
-**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_@
-```
+> [!WARNING]
+> Old version(v1) is no longer supported.
 
-## 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.
+**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
 
@@ -167,207 +79,28 @@ Hello World
 `;
 
 const smark = new SomMark({
-    src: source,
-    format: "html"
+	src: source,
+	format: "html"
 });
 
 console.log(await smark.transpile());
 ```
 
-# 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.
-
-
-
-# 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.
+## Supported Languages
 
-### Self-Closing Tags
+* HTML
+* Markdown
+* MDX (Only ready components)
+* JSON
 
-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
-```
---- 
+# Documentation
 
-# License
+Detailed guides and API references are available in the `docs/` directory:
 
-MIT
+- **[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/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/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,38 +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}{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/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/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"
 };