SugarML

Install

npm i -S posthtml-sugarml

Usage

import { readFileSync } from 'fs'

import posthtml from 'posthtml'
import sugarml from 'posthtml-sugarml'

const html = readFileSync('./index.sml', 'utf8')

posthtml()
  .process(html, { parser: sugarml() })
  .then((result) => console.log(result.html))

This 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.

Indentation

This parser determines how tags are nested based on indentation. For example:

.first-level
  .second-level
    .third-level Hi!
  .second-level

This would be compiled into the following html output:

<div class="first-level">
  <div class="second-level">
    <div class="third-level">Hi!</div>
  </div>
  <div class="second-level"></div>
</div>

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.

Doctypes

The 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:

doctype html >>> <!DOCTYPE html>
doctype HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd" >>> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

Nested Tags

Sometimes 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:

ul
  li: a(href='#') link 1
  li: a(href='#') link 2

You 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:

.wrap: .wrap2: .wrap3 hello! // this works fine
.wrap hello!: .wrap2         // this doesn't work

Shorthands

There 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:

p#main => <p id="main"></p>
p.main => <p class="main"></p>
p#uid.app.active => <p id="uid" class="app active"></p>

You 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:

#main => <div id="main"></div>

Attributes

Attributes 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:

input(checked) => <input checked>
input(type='text') => <input type="text">
input(type='checkbox' checked) => <input type="checkbox" checked>

You can quote your attribute values or not, your choice (although we would recommend quoting). However, if the value contains a space, it must be quoted. For example:

div(class=foo) => <div class="foo"></div>
div(class=foo bar) => <div class="foo" bar></div>
div(class='foo bar') => <div class="foo bar"></div>

Attributes 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:

div(:bind='focus') >>> <div :bind="click"></div>
div(*ngFor='foo in bar') >>> <div *ngFor="foo in bar"></div>
div(@click='handleClick') >>> <div @click="handleClick"></div>

Content

If you need to mix up text content alongside inline tags and such, you can use the pipe character for this as such:

p
  | Here's some text
  strong And some bold text
  | ...and some more text

This would render as:

<p>Here's some text <strong>and some bold text</strong> ...and some more text</p>

For any type of content transforms that are more complex than this, we recommend checking out posthtml-content.

Comments

You can use buffered // and unbuffered //- comments. Only buffered comments would be compiled into the html output.

// just some text
p Paragraph after buffered comment

//- will not output within markup
p Paragraph after unbuffered comment

This would render as:

<!-- just some text -->
<p>Paragraph after buffered comment</p>
<p>Paragraph after unbuffered comment</p>

Example

doctype html
html
  head
    title Testing
  body#index
    h1 Hello world!
    p.intro Wow what a great little language! Some features:
    ul(data-list='yep' @sortable)
      li: a(href='#') whitespace significant!
      li: a(href='#') simple classes and ids!
    footer
      | Thanks for visiting
      span see you next time!

import { readFileSync } from 'fs'

import posthtml from 'posthtml'
import sugarml from 'posthtml-sugarml'

const html = readFileSync('./index.sml', 'utf8')

posthtml()
  .process(html, { parser: sugarml() })
  .then((result) => console.log(result.html))

<!DOCTYPE html>
<html>
  <head>
    <title>Testing</title>
  </head>
  <body id="index">
    <h1>Hello world!</h1>
    <p class="intro">Wow what a great little language! Some features:</p>
    <ul data-list="yep" @sortable>
      <li><a href="#">whitespace significant!</a></li>
      <li><a href="#">simple classes and ids!</a></li>
    </ul>
    <footer>
      Thanks for visiting
      <span>see you next time!</span>
    </footer>
  </body>
</html>

Maintainer

Jeff Escalante

Contributors

Ivan Voischev

Michael Ciniawsky

posthtml/sugarml