Longform Markup Language

Whitespace

Whitespace is meaningful in Longform. Any markup indented two spaces out from an element will be outputted as a child of that element.

Some exceptions for this are when native markup of the output language and text are being processed. Or when in a preformatted block.

Declaring elements

Element tags

A sole element tag can be outputted using the element name followed by two colons ::.

div::

Element attributes

Element attributes are declared after the tag and are wrapped in square brackets [].

div[data-foo=bar][aria-describedby=#baz]::

Alternatively attributes can follow directly after the element tag with 1 level of indentation.

div::
  [data-foo=bar]
  [aria-describedby=#baz]

If an element is declared multiple times the content is concatenated into a single value. This behaviour does not apply to the element's id if it is defined using the attribute syntax. Classes will be concatenated with a space separating them.

meta::
  [name=description]
  [content=Lorem ipsum dolor sit amet, consectetur adipiscing elit.]
  [content=Quisque a sem et nisl mollis porttitor et sit amet neque.]
  [content=Maecenas suscipit nulla ac suscipit imperdiet. Quisque]
  [content=odio nisi, semper non dui quis, feugiat faucibus ipsum.]

Element output ids

The elements output markup id can be declared on the line before the tag at the same indentation level with the hash # symbol pre-fixing the id.

This form of giving an element an id also gives it a meaningful Longform identifier.

#element-id
div::

Alternatively the id can follow the tag name, before the closing semicolons. Again with a hash prefixing it. Unlike the form where the

div#element-id::

And finally the id can be declared using the attribute syntax.

div[id=element-id]::
<!-- or -->
div::
  [id=element-id]

If an element has an id declared for it twice only the first declaration is used.

Element classes

Classes can be defined following the element's tag declaration with a period . prefixing each tag.

div#element-id.class-1.class-2.class-3::

Alternatively classes can be defined using the attribute syntax on the lines following the tag definition.

div#element-id::
  [class=class-1]
  [class=class-2 class-3]

Element text and native markup content.

Elements can have text and native markup following the tag declaration with a space between the text and the double colons of the element definition.

div:: Text content with <em>some</em> native markup.

Alternatively, the text and native markup can follow the tag declaration with one extra indentation level.

div::
  Text content with <em>some</em> native markup.

Chained elements

Elements can be chained to create many elements in one line.

menu::
  li::a[href=/section1]::b:: Section 1
  li::a[href=/section2]::b:: Section 2
  li::a[href=/section3]::b:: Section 3

Preformatted blocks

Longform does not assign special meaning to any HTML tags so to retain formatting content can be wrapped in curly braces to create a preformatted block.

Escaped preformatted block

When an element is followed by a single curly brace, its content is HTML escaped and its whitespace is preserved at the children's indent level.

pre::
  code:: {
    div::
      <p>
        This content will preserve its formatting including
        the parent <code>div::</code>
      </p>
  }

Result

<pre><code>
  div::
    <p>
      This content will preserve its formatting including
      the parent <code>div::</code>
    </p>
</code></pre>

Un-escaped preformatted text

When an element is followed by a two curly braces, its formatting and content is kept intact.

script:: {{
  console.log('Hello, World!');
}}

style:: {{
  div {
    color: red;
  }
}}

Result

<script>
  console.log('Hello, World!');
</script><style>
  div {
    color: red;
  }
</style>

Comments

Comments can be written outside of a fragment using -- two hyphens. Within a fragment comments in the output markup language's syntax can be used but they will be written to the output alongside all other text in the native output markup.

Embedding fragments

Fragments can be embedded into other fragments as part of the Longform parsing allowing a full document to be created from many fragments. Fragments are embedded using the syntax #[fragment-id].

@root
@doctype:: html
html[lang=en]::
  body:: 
    header::
      menu::
        li::a[href=#section1]:: Section 1
        li::a[href=#section2]:: Section 2
    body::
      #[section1]
      #[section2]

#section1
section::
  ...

#section2
section::
  ...

Templating

Longform templates only allow key-value pairs inputed with the values being strings. The template is intended to be passed over to the client where the template might be rendered using client side state. It is assumed that the client has its own means to perform conditional statements and iterate, and is optimized to do so, so those functionalities are left to the scripting language to keep the templating logic lean.

@template
div::
  h3:: Recipe step #{position}

Templated markup

Arbitary Longform and HTML strings can be inserted in a template using the double hash variable expansion form. See content sanitization for rules on sanitizing untrusted input using this form.

@template
@allow-elements:: strong em
div::
  ##{markup}
  

Content sanitization

A Longform block can have sanitization rules applied to its content using the @allow-elements, @allow-attributes, @allow-data-attributes, @allow-all directives. These directives are designed to play well with the SanitizerConfig Web API, but for now a sanitizer library must be shiped with the parser to apply the directive rules on any content.

Sanitizer rules apply when expanding variables in a templating context using the double hash expansion syntax ##{var} and in situations where @patchable is used.

Sanitizer defaults

Longform cannot sanitize raw HTML without having a sanitizer library parsing HTML input and it cannot differenciate between text and HTML markup. If the double hash template expansion is used in a situation where no sanitizer is configured the variable expansion SHOULD be ignored by parser implementations. Parsers MAY support an option to bypass this default document level behaviour.

A document specifying no rules allowing elements, attributes or data attributes also SHOULD ignore all input using the double hash variable expansion. Again, a parser might allow equivilent options to the sanitizer directives to bypass this default behaviour.

Element specific sanitizer rules

A element can have rules applied allowing arbitary markup to be added to the document. Either @allow-elements or @allow-all must be used to allow any elements to persist.

@template
#embedding-content
section::
  header::
    h2:: #{header}
  @allow-elements:: strong em a[href target]
  @allow-attributes: class
  div::
    ##{markup}

Sanitization rules are inherited by child elements. So the following Longform would produce the same results.

@template
@allow-elements:: strong em a[href target]
@allow-attributes: class
#embedding-content
section::
  header::
    h2:: #{header}
  div::
    ##{markup}

Global settings

Settings can be configured document wide using the @global directive from the top level of the document.

@global::
  @allow-elements:: strong em a[href target]
  @allow-attributes: class
  
@template
#template1
section::
  ##{markup}

@template
#template2
section::
  ##{markup}

Directives

@url

Sets the URL of the Longform document. A HTTP Get request to the @url using the Accept header text/longform should produce the same document unless it has since been modified.

@url:: https://example.com/blog/article-1

@patchable

Asserts to the client that the document can be patched using a HTTP Patch request and the Content-Type header text/longform. The @patchable directive should be ignored unless the @url directive is used.

@url:: http://example.com/blog/longform-1
@patchable

@doctype

Inserts a doctype declaration at the beginning of a fragment.

@doctype:: html
html[lang=en]::
  head::
    ...
  body::
    ...

Result

<!doctype html>
<html lang="en">
  <head>...</head>
  <body>...</body>
</html>

@xml

Inserts an XML declaration at the beginning of a fragment.

@xml:: version="1.0" encoding="UTF-8"
html::
  [xmlns=http://www.w3.org/HTML/1998/html4]
  [xmlns:xdc=http://www.xml.com/books]
  body::
    ...

Result

<?xml version="1.0" encoding="UTF-8"?>
<html
  xmlns="http://www.w3.org/HTML/1998/html4"
  xmlns:xdc="http://www.xml.com/books"
>
  <body>
    ...
  </body>
</html>

@template

Marks a fragment as being a client side template. When a fragment is a template the Longform parser skips formatting the fragment and outputs it separately to the processed fragments to be passed through to the client. Client side logic can then pass the template into a special Longform template parser and have the HTML output returned.

@template
#button-text "
  Add new #{entityName}
"

@editable

Marks the children of an element as editable in a patch request. The element cannot be within a template and must have a Longform id set on it.

@editable
#edit-me
div::
  This content is editable.

@global

Applies directive rules to an entire Longform document. Directives applied before or within a fragment will typically override globally set rules.

@url:: https://example.com/pages/article-1
@patchable
@global::
  @allowed-elements:: h4 p strong em b i small hr br

@allow-elements

In a template this directive instructs the parser what elements can be rendered when applying non-escaped variable expansion within its scope. If used in a patchable document, client side editors should limit what elements can be edited in the editable element. The directive's rules should also be used to sanitize or reject input when merging edits from a HTTP Patch request into the document on the server.

Attributes can be allowed on specific elements by listing them in square brackets directly after the element in the directive's arguments.

If this or the @allow-all directives are not used all elements should be filtered or rejected when editing or applying variable expansion.

This directive can be applied in a @global directive block to set the default rules for a document. The directive applied closest to a template variable expansion or editable element takes precedence.

@editable
@allow-elements:: a[href target] p strong em
div::
  Edit me!

@allow-attributes

In a template this directive instructs the parser what attributes can be rendered when applying non-escaped variable expansion within its scope. If used in a patchable document client side editors can limit what attributes can be added to the markup. The directive's rules should be used to sanitize or reject input when merging edits from a HTTP Patch request into the document on the server.

If this or the @allow-all directives are not used all attributes should be filtered or rejected when editing or applying variable expansion.

This directive can be applied in a @global directive block to set the default rules for a document. The directive applied closest to a template variable expansion or editable element takes precedence.

@editable
@allow-attributes:: id name class
@allow-elements:: a[href target] p strong em form label[for] input button[submit]
div::
  Edit me...

@allow-data-attributes

In a template this directive instructs the parser to allow rendering of data-attributes when applying non-escaped variable expansion within its scope. If used in a patchable document client side editors can allow data-attributes to be added to the markup.

If this or the @allow-all directives are not used all data-attributes should be filtered or rejected when editing or applying variable expansion.

This directive can be applied in a @global directive block to set the default rules for a document. The directive applied closest to a template variable expansion or editable element takes precedence.

@editable
@allow-data-attributes
@allow-attributes:: id name class
@allow-elements:: a[href target] p strong em form label[for] input button[submit]
div::
  Edit me...

@allow-all

This directive instructs the parser to allow all elements, attributes and data-attributes when performing non-escaped variable expansion or when editing a patchable document.

This directive can be applied in a @global directive block to set the default rules for a document. The directive applied closest to a template variable expansion or editable element takes precedence.

@editable
@allow-all
body::
  Edit me...