marksafe

# Marksafe - Secure, Concise, and Flexible Markup Language Marksafe is a simple yet powerful syntax for writing HTML-like markup in a secure and concise way. It’s designed to make content authoring easier by providing a more flexible syntax and ensuring security by avoiding common pitfalls like XSS vulnerabilities. ## Features - **Concise Syntax:** Shorten your code with simplified tag names and structure. - **Security:** Prevent XSS vulnerabilities by avoiding angle brackets and special characters in HTML. - **Compatibility:** Easily convert Marksafe to HTML and Markdown. - **Shorthands:** Use shorthand notations for commonly used HTML elements, such as: - `[uli]` for `[ul][li]` (unordered list items) - `[oli]` for `[ol][li]` (ordered list items) - `[*]` for `[strong]` (bold text) - `[bq]` for `[blockquote]` (blockquote) ## Marksafe Syntax ### Basic Structure - Tags are enclosed in square brackets `[ ]`. - Closing tags are wrapped with `/` at the start: `[tag]` becomes `[/tag]`. - Inline elements (like links) and block elements (like paragraphs) are treated similarly but retain their block-level behavior. ### Basic Elements ```marksafe [h1]Heading[/h1] [p]This is a paragraph.[/p] [bq]This is a blockquote.[/bq] ``` ### Lists ```marksafe [uli]Item 1;;Item 2;;Item 3[/uli] [oli]First;;Second;;Third[/oli] ``` ### Links and Images ```marksafe [a]href=example.com,,Click here[/a] [img]src=example.jpg,,alt=An example image,,[/img] ``` ### Tables ```marksafe [table] [tr][th]Header 1;;Header 2;;Header 3[/th][/tr] [tr][td]Row 1 Col 1;;Row 1 Col 2;;Row 1 Col 3[/td][/tr] [tr][td]Row 2 Col 1;;Row 2 Col 2;;Row 2 Col 3[/td][/tr] [/table] ``` ### Example ```markdown [h1]Shopping List[/h1] [p]Here’s a list of things to buy:[/p] [uli]Apples;;Bananas;;Carrots [uli]Carrot A;;Carrot B [uli]Carrot B1;;Carrot B2[/uli] [/uli] ;;Dates[/uli] [p]For more details, visit [a]href=https://example.com,,Example[/a].[/p] [bq]This is a blockquote.[/bq] ``` ### Shorthands - **`[uli]`** for `[ul][li]` (unordered list items). - **`[oli]`** for `[ol][li]` (ordered list items). - **`[*]`** for `[strong]` (bold text). - **`[bq]`** for `[blockquote]` (blockquote). ### Self-closing Elements - For elements like `img`, the attributes and content are written inside the tag with a special delimiter `,,` to separate them. ```markdown [img]src=example.jpg,,alt=An example image,,[/img] ``` ### Key Conversion Points - The following tags are expanded for clarity: - `[uli]` expands to `[ul][li]`. - `[oli]` expands to `[ol][li]`. - `[*]` expands to `[strong]`. - `[bq]` expands to `[blockquote]`. ## Delimiters and Escaping - Consecutive elements of the same type can be separated by `;;`. - Attributes and content inside a tag are separated by `,,`. - If a delimiter (`;;` or `,,`) is intended to be part of the content or an attribute, it must be escaped using `\`. ## Customization Marksafe allows integrators to modify delimiters and add/remove shorthands as needed. ## Security Benefits Marksafe's design eliminates the need for angle brackets, making it safe for embedding content without the risk of cross-site scripting (XSS) attacks. All attributes are safely handled within the body of the tag. ## Converting to HTML Marksafe can be easily converted to valid HTML by replacing its syntax with standard HTML tags. Example: ```markdown [h1]Shopping List[/h1] [uli]Apples;;Bananas;;Carrots;;Dates[/uli] ``` Converts to: ```html <h1>Shopping List</h1> <ul> <li>Apples</li> <li>Bananas</li> <li>Carrots</li> <li>Dates</li> </ul> ``` ## Converting to Markdown You can also convert Marksafe to Markdown, which is useful for simpler content structures. Example: ```markdown [h1]Shopping List[/h1] [uli]Apples;;Bananas;;Carrots;;Dates[/uli] ``` Converts to: ```markdown # Shopping List - Apples - Bananas - Carrots - Dates ``` ## Installation To use Marksafe in your project: 1. Install via `npm`: ```bash npm install Marksafe ``` 2. Alternatively, clone the repository: ```bash git clone https://github.com/mksunny1/marksafe.git ``` Once installed, you can integrate Marksafe into your content authoring or markdown processing systems. ## Usage Marksafe currently only works in the browser. Here’s an example of how to process Marksafe code: import { Marksafe } from 'Marksafe'; const input = "[h1]Hello, World![/h1]"; const output = Marksafe.process(input); console.log(output); // Outputs: <h1>Hello, World!</h1> Customizing Marksafe Marksafe allows customization of default delimiters and shorthand syntax. For example, you can redefine the ,, delimiter or add/remove shorthand tags. ## Usage ### Input ```html <section id="ms"> [h3] This is escaped Marksafe text. "h1" tag is allowed [/h3] [p] This is the first paragraph. "p" tag is allowed ;; Links like [a]href=https://github.com/mksunny1/marksafe,,this[/a] can be present. [/p] [section] Althogh [b]section[/b] tag is allowed, this will not parse because the whole marksafe content is inside a [b]section[/b]. As a result, parts of the section outside the internal nodes will appear as [b]text[/b] nodes in the generated markup instead of being part of an output [b]section[/b] node. [/section] [footer] End of marksafe content [/footer] </section> ``` ```js Marksafe.process(document.querySelector('#ms')); ``` ### Output ```html <section id="ms"> <h3> This is escaped Marksafe text. "h3" tag is allowed </h3> <p> This is the first paragraph. "p" tag is allowed </p> <p> Links like <a href="https://github.com/mksunny1/marksafe2">this</a> can be present. </p> [section] Althogh <b>section</b> tag is allowed, this will not parse because the whole marksafe2 content is inside a <b>section</b>. As a result, parts of the section outside the internal nodes will appear as <b>text</b> nodes in the generated markup instead of being part of an output <b>section</b> node. [/section] <footer> End of marksafe2 content </footer> </section> ``` ## API Documention The complete API documentation can be found [here](https://github.com/mksunny1/marksafe/blob/main/docs/classes/Marksafe.md). ## Supporting Marksafe Marksafe is an open-source project aimed at providing a powerful, flexible, and safe alternative to HTML and Markdown. If you find Marksafe useful, you can support the project in the following ways: - **Give a Star** ⭐ on [GitHub](https://github.com/mksunny1/marksafe) to help increase its visibility. - **Share** Marksafe with your friends, colleagues, and communities. - **Provide Feedback** 💬 by reporting issues, suggesting improvements, or discussing ideas in the [GitHub Issues](https://github.com/mksunny1/marksafe/issues). - **Contribute** 💻 by submitting pull requests, improving documentation, or adding new features. --- ## Sponsoring Marksafe Developing and maintaining Marksafe takes time and effort. If you'd like to support the project financially, you can become a sponsor. Your contributions will help ensure continued development, improvements, and support for Marksafe. You can sponsor the project on [**GitHub Sponsors**](https://github.com/sponsors/mksunny1) Every bit of support counts and is greatly appreciated! ## License MIT License. See [LICENSE](LICENSE) for details.