{"id":21540948,"url":"https://github.com/reshape/sugarml","last_synced_at":"2025-04-10T04:11:09.348Z","repository":{"id":44143565,"uuid":"65311383","full_name":"reshape/sugarml","owner":"reshape","description":"a whitespace-significant html parser for reshape","archived":false,"fork":false,"pushed_at":"2022-02-11T21:37:32.000Z","size":981,"stargazers_count":37,"open_issues_count":14,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T05:26:46.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reshape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-09T16:38:25.000Z","updated_at":"2020-12-08T16:01:19.000Z","dependencies_parsed_at":"2022-09-17T17:10:10.125Z","dependency_job_id":null,"html_url":"https://github.com/reshape/sugarml","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fsugarml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fsugarml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fsugarml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fsugarml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reshape","download_url":"https://codeload.github.com/reshape/sugarml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154990,"owners_count":21056543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T05:00:37.115Z","updated_at":"2025-04-10T04:11:09.328Z","avatar_url":"https://github.com/reshape.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SugarML\n\n[![npm](https://img.shields.io/npm/v/sugarml.svg?style=flat-square)](https://npmjs.com/package/sugarml)\n[![tests](https://img.shields.io/travis/reshape/sugarml.svg?style=flat-square)](https://travis-ci.org/reshape/sugarml?branch=master)\n[![dependencies](https://img.shields.io/david/reshape/sugarml.svg?style=flat-square)](https://david-dm.org/reshape/sugarml)\n[![coverage](https://img.shields.io/coveralls/reshape/sugarml.svg?style=flat-square)](https://coveralls.io/r/reshape/sugarml?branch=master)\n\nA simple parser for whitespace-significant html, intended for use with [reshape](https://github.com/reshape/reshape).\n\n\u003e **Note:** This project is in early development, and versioning is a little different. [Read this](http://markup.im/#q4_cRZ1Q) for more details.\n\n## Why Should You Care?\n\nIf you are interested in using reshape, but enjoy whitespace-significant html syntax, like jade, slim, etc. You have come to the right place. Alternately, if you are simply looking for a strong alternative to jade for any other reason, read on.\n\nThis parser's syntax is heavily inspired by [jade/pug](http://jade-lang.com/). It is a much smaller and simpler version, containing only the bare minimum necessary to write clean whitespace-significant html. It is intended for use as a reshape plugin, and returns a [Reshape AST](https://github.com/reshape/reshape#reshape-ast), but could in theory be used for any other purpose as well.\n\nIf you are looking for the ability to add expressions, variables, loops, layouts, etc. you can implement them through other reshape plugins in addition to this parser. This type of functionality is outside the scope of this parser as it is intended to be light, simple, modular, and accessible to contributors.\n\nThe source is not very long or complicated and is heavily commented for clarity. Take a look and feel free to contribute!\n\n## Install\n\n```bash\nnpm install sugarml --save\n```\n\n\u003e **Note:** This project is compatible with node v6+ only\n\n## Usage\n\n```js\nconst {readFileSync} = require('fs')\nconst reshape = require('reshape')\nconst sugarml = require('sugarml')\n\nreshape({ parser: sugarml })\n  .process(readFileSync('./index.sgr', 'utf8'))\n  .then((result) =\u003e console.log(result.output()))\n```\n\nThis parser is very loose with its rules and standards. It is not responsible for enforcing good style or conventions, it's simply responsible for compiling your code. This means that you can use all sorts of invalid characters in attribute and tag names, and indentation rules are extremely loose.\n\n## Syntax Highlighting\n\nIf you're looking for beautiful syntax highlighting, look no further. Available plugins listed below:\n\n- [Atom](https://github.com/reshape/atom-sugarml)\n\nIf you made a plugin for another editor, please send in a pull request to have it featured here!\n\n## Features\n\n#### Indentation \u0026 Nesting\n\nThis parser determines how tags are nested based on indentation. For example:\n\n```sml\n.first-level\n  .second-level\n    .third-level hi!\n  .second-level-2\n```\n\nThis would be compiled into the following html output:\n\n```html\n\u003cdiv class=\"first-level\"\u003e\n  \u003cdiv class=\"second-level\"\u003e\n    \u003cdiv class=\"third-level\"\u003ehi!\u003c/div\u003e\n  \u003c/div\u003e\n  \u003cdiv class=\"second-level-2\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n```\n\n_As long as one line is indented with more characters than the last, it will be nested_. It doesn't matter if the number of characters that you use is consistent, or if they are spaces or tabs, or anything else. It's just the number of space characters used to indent, that's it. So you can get away with very messy code, if you want, but that's what linters are for.\n\n#### Tags\n\nA tag is written simply as the name of the tag. Tag names must start with a letter, then after that can contain any character other than `#`, `.`, `(`, `:`, or a space/tab. These character limitation are in place solely because of the language's syntax requirements.\n\nSo, for example, these tag names are valid and will compile correctly (although I would not advise using a tag with characters other than letters and hyphens personally):\n\n```sml\ndiv\ncustom-name\nwow@mytagiscool!\nhello___12world\n```\n\nHowever, these tag names will not compile into the results you expect:\n\n```sml\nfoo(bar\nhello.min.js\niam:atag\nmy cool tag\n```\n\nFortunately, it is not advisable to have custom html tags that look anything like these anyway, so you should be in the clear as long as you are writing reasonable html.\n\n#### Classes \u0026 IDs\n\nThere is a shorthand for adding classes and IDs to your tags, which is exactly the same as it is in just about every other whitespace-significant html parser, and the same as CSS. For example:\n\n```html\np#main \u003e\u003e\u003e \u003cp id=\"main\"\u003e\u003c/p\u003e\np.staff \u003e\u003e\u003e \u003cp class=\"staff\"\u003e\u003c/p\u003e\np#main.staff.active \u003e\u003e\u003e \u003cp id=\"main\" class=\"staff active\"\u003e\u003c/p\u003e\n```\n\nYou can chain as many classes and IDs in this manner as you want. If you do not use an element name, it will assume you want a div. For example:\n\n```html\n#main \u003e\u003e\u003e \u003cdiv id=\"main\"\u003e\u003c/div\u003e\n```\n\n#### Attributes\n\nAttributes fall between parentheses directly after a tag's name. They are space-separated and can be either boolean (key, no value), or key/value pairs. For example:\n\n```html\ninput(type='text') \u003e\u003e\u003e \u003cinput type=\"text\"\u003e\ninput(checked) \u003e\u003e\u003e \u003cinput checked\u003e\ninput(type='checkbox' checked) \u003e\u003e\u003e \u003cinput type=\"checkbox\" checked\u003e\n```\n\nYou can quote your attribute values or not, your choice (although we would recommend quoting). If you quote your attribute, it can contain any value other than an end-quote that matches the type of your starting quote (obviously). If you do not quote your attribute, it can contain any character other than a single or double quote, a close paren, or a space. As such, you are less likely to run into issues when quoting your attribute, which is why we recommend it. For example:\n\n```html\ndiv(class=foo) \u003e\u003e\u003e \u003cdiv class=\"foo\"\u003e\u003c/div\u003e\ndiv(class='foo bar') \u003e\u003e\u003e \u003cdiv class=\"foo bar\"\u003e\u003c/div\u003e\ndiv(class=foo bar) \u003e\u003e\u003e \u003cdiv class=\"foo\" bar\u003e\u003c/div\u003e\ndiv(class=\"foo('wow')\") \u003e\u003e\u003e \u003cdiv class=\"foo('wow')\"\u003e\u003c/div\u003e\ndiv(class=foo(\"wow\")) \u003e\u003e\u003e Syntax error\n```\n\nAttributes can contain any character other than `=` or a space. If you value is quoted, it can contain any value other than a quote (that will end the attribute), and if it's not quoted, it can contain any value other than a quote or space. So even attributes with special characters (found sometimes in certain front-end frameworks like vue and angular) work fine. For example:\n\n```html\ndiv(:bind='focus') \u003e\u003e\u003e \u003cdiv :bind=\"focus\"\u003e\u003c/div\u003e\ndiv(*ngFor='foo in bar') \u003e\u003e\u003e \u003cdiv *ngFor=\"foo in bar\"\u003e\u003c/div\u003e\ndiv(@click='doSomething') \u003e\u003e\u003e \u003cdiv @click=\"doSomething\"\u003e\u003c/div\u003e\n```\n\n#### Inline Nested Tags\n\nSometimes you don't really want to indent nested tags when they are short enough to be placed on one line. When this happens, you can use a colon instead of a newline and indent to nest. For example:\n\n```html\nul\n  li: a(href='#') link 1\n  li: a(href='#') link 2\n```\n\nYou can nest as many wrapper tags on a single line as you want, as long as they are all separated by a colon immediately following the tag. However If the tag has content, it cannot be nested with a colon. For example:\n\n```\n.wrap: .wrap2: .wrap3 hello! // this works fine\n.wrap hello!: .wrap2 // this does not\n```\n\n#### Nested Text Content\n\nIf you need to mix up text content alongside inline tags and such, you can use the pipe character for this as such:\n\n```\np\n  | Here's some text\n  strong And some bold text\n  | ...and some more text\n```\n\nThis would render as:\n\n```html\n\u003cp\u003eHere's some text \u003cstrong\u003eand some bold text\u003c/strong\u003e ...and some more text\u003c/p\u003e\n```\n\nFor any type of content transforms that are more complex than this, we recommend checking out [reshape-content](https://github.com/reshape/content).\n\n#### Text Block Content\n\nIf you have a block of text you don't really want to put pipes before, you can use a text block for this. Put a `.` after the end of the tag name, then indent the content in to the next line as such:\n\n```\np.\n  Here's some content\n  Split into multiple lines, wow!\n    span will render as text not a span\n  ok that's the end!\n```\n\nThis would render as:\n\n```html\n\u003cp\u003eHere's some content\nSplit into multiple lines, wow!\n  span will render as text not a span\nok that's the end!\u003c/p\u003e\n```\n\nNote that you will not be able to render any elements within a text block. The block continues until there's a line that is not indented at a greater level than the parent element.\n\n#### Doctypes\n\nThe doctype is a special tag, and is handled specially. If the first word on the first line of your template is `doctype`, it will be parsed as a doctype. Anything after this word will be added to the tag. So for example:\n\n```html\ndoctype html \u003e\u003e\u003e \u003c!DOCTYPE html\u003e\ndoctype HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\" \u003e\u003e\u003e \u003c!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\"\u003e\n```\n\n## Example\n\n**Input:**\n\n```html\ndoctype html\nhtml\n  head\n    title Testing\n  body#index\n    h1 Hello world!\n    p.intro Wow what a great little language! Some features:\n    ul(data-list='yep' @sortable)\n      li: a(href='#') whitespace significant!\n      li: a(href='#') simple classes and ids!\n    footer\n      | Thanks for visiting\n      span see you next time!\n```\n\n**Setup:**\n\n```js\n'use strict'\n\nconst {readFileSync} = require('fs')\n\nconst reshape = require('reshape')\nconst sugarml = require('sugarml')\n\nreshape({ parser: sugarml })\n  .process(readFileSync('./index.sgr', 'utf8'))\n  .then((result) =\u003e console.log(result.output()))\n```\n\n**Output:**\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eTesting\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody id=\"index\"\u003e\n    \u003ch1\u003eHello world!\u003c/h1\u003e\n    \u003cp class=\"intro\"\u003eWow what a great little language! Some features:\u003c/p\u003e\n    \u003cul data-list=\"yep\" @sortable\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003ewhitespace significant!\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003esimple classes and ids!\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n    \u003cfooter\u003e\n      Thanks for visiting\n      \u003cspan\u003esee you next time!\u003c/span\u003e\n    \u003c/footer\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## License \u0026 Contributing\n\n- Details on the license [can be found here](LICENSE.md)\n- Details on running tests and contributing [can be found here](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshape%2Fsugarml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freshape%2Fsugarml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshape%2Fsugarml/lists"}