QuantumJS
Home
Introduction
OverviewQuick StartThe Markup LanguageCore ConceptsUsing the CLI / APIQuantum vs Markdown
Config
quantum.config.js
Core Modules
quantum-corequantum-domquantum-html
Optional Modules
quantum-apiquantum-code-highlightquantum-diagramquantum-docsquantum-markdownquantum-templatequantum-version
Edit Page
quantum-html
A library for converting parsed Quantum AST to HTML.
About
This module is used to transform parsed quantum AST objects to virtual dom content using EntityTransform functions and then converting the output to html.
Entities
The below entities are provided by the entityTransforms function.
Standard HTML elements
aadded
Adds an <a> element 
# Create an <a> element
@a

# Create an <a> element with class='className'
@a .className

# Create an <a> element with id='idName'
@a #idName

# Create an <a> element with id='idName' and class='className'
@a #idName.className

# Chain multiple classes without spaces
@a #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
badded
Adds a <b> element 
# Create a <b> element
@b

# Create a <b> element with class='className'
@b .className

# Create a <b> element with id='idName'
@b #idName

# Create a <b> element with id='idName' and class='className'
@b #idName.className

# Chain multiple classes without spaces
@b #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
bradded
Adds a <br> element 
# Create a <br> element
@br

# Create a <br> element with class='className'
@br .className

# Create a <br> element with id='idName'
@br #idName

# Create a <br> element with id='idName' and class='className'
@br #idName.className

# Chain multiple classes without spaces
@br #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
buttonadded
Adds a <button> element 
# Create a <button> element
@button

# Create a <button> element with class='className'
@button .className

# Create a <button> element with id='idName'
@button #idName

# Create a <button> element with id='idName' and class='className'
@button #idName.className

# Chain multiple classes without spaces
@button #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
divadded
Adds a <div> element 
# Create a <div> element
@div

# Create a <div> element with class='className'
@div .className

# Create a <div> element with id='idName'
@div #idName

# Create a <div> element with id='idName' and class='className'
@div #idName.className

# Chain multiple classes without spaces
@div #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
formadded
Adds a <form> element 
# Create a <form> element
@form

# Create a <form> element with class='className'
@form .className

# Create a <form> element with id='idName'
@form #idName

# Create a <form> element with id='idName' and class='className'
@form #idName.className

# Chain multiple classes without spaces
@form #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h1added
Adds an <h1> element 
# Create an <h1> element
@h1

# Create an <h1> element with class='className'
@h1 .className

# Create an <h1> element with id='idName'
@h1 #idName

# Create an <h1> element with id='idName' and class='className'
@h1 #idName.className

# Chain multiple classes without spaces
@h1 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h2added
Adds an <h2> element 
# Create an <h2> element
@h2

# Create an <h2> element with class='className'
@h2 .className

# Create an <h2> element with id='idName'
@h2 #idName

# Create an <h2> element with id='idName' and class='className'
@h2 #idName.className

# Chain multiple classes without spaces
@h2 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h3added
Adds an <h3> element 
# Create an <h3> element
@h3

# Create an <h3> element with class='className'
@h3 .className

# Create an <h3> element with id='idName'
@h3 #idName

# Create an <h3> element with id='idName' and class='className'
@h3 #idName.className

# Chain multiple classes without spaces
@h3 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h4added
Adds an <h4> element 
# Create an <h4> element
@h4

# Create an <h4> element with class='className'
@h4 .className

# Create an <h4> element with id='idName'
@h4 #idName

# Create an <h4> element with id='idName' and class='className'
@h4 #idName.className

# Chain multiple classes without spaces
@h4 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h5added
Adds an <h5> element 
# Create an <h5> element
@h5

# Create an <h5> element with class='className'
@h5 .className

# Create an <h5> element with id='idName'
@h5 #idName

# Create an <h5> element with id='idName' and class='className'
@h5 #idName.className

# Chain multiple classes without spaces
@h5 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
h6added
Adds an <h6> element 
# Create an <h6> element
@h6

# Create an <h6> element with class='className'
@h6 .className

# Create an <h6> element with id='idName'
@h6 #idName

# Create an <h6> element with id='idName' and class='className'
@h6 #idName.className

# Chain multiple classes without spaces
@h6 #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
hradded
Adds an <hr> element 
# Create an <hr> element
@hr

# Create an <hr> element with class='className'
@hr .className

# Create an <hr> element with id='idName'
@hr #idName

# Create an <hr> element with id='idName' and class='className'
@hr #idName.className

# Chain multiple classes without spaces
@hr #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
iadded
Adds an <i> element 
# Create an <i> element
@i

# Create an <i> element with class='className'
@i .className

# Create an <i> element with id='idName'
@i #idName

# Create an <i> element with id='idName' and class='className'
@i #idName.className

# Chain multiple classes without spaces
@i #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
imgadded
Adds an <img> element 
# Create an <img> element
@img

# Create an <img> element with class='className'
@img .className

# Create an <img> element with id='idName'
@img #idName

# Create an <img> element with id='idName' and class='className'
@img #idName.className

# Chain multiple classes without spaces
@img #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
inputadded
Adds an <input> element 
# Create an <input> element
@input

# Create an <input> element with class='className'
@input .className

# Create an <input> element with id='idName'
@input #idName

# Create an <input> element with id='idName' and class='className'
@input #idName.className

# Chain multiple classes without spaces
@input #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
labeladded
Adds a <label> element 
# Create a <label> element
@label

# Create a <label> element with class='className'
@label .className

# Create a <label> element with id='idName'
@label #idName

# Create a <label> element with id='idName' and class='className'
@label #idName.className

# Chain multiple classes without spaces
@label #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
liadded
Adds an <li> element 
# Create an <li> element
@li

# Create an <li> element with class='className'
@li .className

# Create an <li> element with id='idName'
@li #idName

# Create an <li> element with id='idName' and class='className'
@li #idName.className

# Chain multiple classes without spaces
@li #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
linkadded
Adds a <link> element 
# Create a <link> element
@link

# Create a <link> element with class='className'
@link .className

# Create a <link> element with id='idName'
@link #idName

# Create a <link> element with id='idName' and class='className'
@link #idName.className

# Chain multiple classes without spaces
@link #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
metaadded
Adds a <meta> element 
# Create a <meta> element
@meta

# Create a <meta> element with class='className'
@meta .className

# Create a <meta> element with id='idName'
@meta #idName

# Create a <meta> element with id='idName' and class='className'
@meta #idName.className

# Chain multiple classes without spaces
@meta #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
oladded
Adds an <ol> element 
# Create an <ol> element
@ol

# Create an <ol> element with class='className'
@ol .className

# Create an <ol> element with id='idName'
@ol #idName

# Create an <ol> element with id='idName' and class='className'
@ol #idName.className

# Chain multiple classes without spaces
@ol #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
optionadded
Adds an <option> element 
# Create an <option> element
@option

# Create an <option> element with class='className'
@option .className

# Create an <option> element with id='idName'
@option #idName

# Create an <option> element with id='idName' and class='className'
@option #idName.className

# Chain multiple classes without spaces
@option #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
padded
Adds a <p> element 
# Create a <p> element
@p

# Create a <p> element with class='className'
@p .className

# Create a <p> element with id='idName'
@p #idName

# Create a <p> element with id='idName' and class='className'
@p #idName.className

# Chain multiple classes without spaces
@p #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
preadded
Adds a <pre> element 
# Create a <pre> element
@pre

# Create a <pre> element with class='className'
@pre .className

# Create a <pre> element with id='idName'
@pre #idName

# Create a <pre> element with id='idName' and class='className'
@pre #idName.className

# Chain multiple classes without spaces
@pre #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
selectadded
Adds a <select> element 
# Create a <select> element
@select

# Create a <select> element with class='className'
@select .className

# Create a <select> element with id='idName'
@select #idName

# Create a <select> element with id='idName' and class='className'
@select #idName.className

# Chain multiple classes without spaces
@select #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
spanadded
Adds a <span> element 
# Create a <span> element
@span

# Create a <span> element with class='className'
@span .className

# Create a <span> element with id='idName'
@span #idName

# Create a <span> element with id='idName' and class='className'
@span #idName.className

# Chain multiple classes without spaces
@span #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
styleadded
Adds a <style> element 
# Create a <style> element
@style

# Create a <style> element with class='className'
@style .className

# Create a <style> element with id='idName'
@style #idName

# Create a <style> element with id='idName' and class='className'
@style #idName.className

# Chain multiple classes without spaces
@style #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
tableadded
Adds a <table> element 
# Create a <table> element
@table

# Create a <table> element with class='className'
@table .className

# Create a <table> element with id='idName'
@table #idName

# Create a <table> element with id='idName' and class='className'
@table #idName.className

# Chain multiple classes without spaces
@table #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
tbodyadded
Adds a <tbody> element 
# Create a <tbody> element
@tbody

# Create a <tbody> element with class='className'
@tbody .className

# Create a <tbody> element with id='idName'
@tbody #idName

# Create a <tbody> element with id='idName' and class='className'
@tbody #idName.className

# Chain multiple classes without spaces
@tbody #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
tdadded
Adds a <td> element 
# Create a <td> element
@td

# Create a <td> element with class='className'
@td .className

# Create a <td> element with id='idName'
@td #idName

# Create a <td> element with id='idName' and class='className'
@td #idName.className

# Chain multiple classes without spaces
@td #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
textareaadded
Adds a <textarea> element 
# Create a <textarea> element
@textarea

# Create a <textarea> element with class='className'
@textarea .className

# Create a <textarea> element with id='idName'
@textarea #idName

# Create a <textarea> element with id='idName' and class='className'
@textarea #idName.className

# Chain multiple classes without spaces
@textarea #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
thadded
Adds a <th> element 
# Create a <th> element
@th

# Create a <th> element with class='className'
@th .className

# Create a <th> element with id='idName'
@th #idName

# Create a <th> element with id='idName' and class='className'
@th #idName.className

# Chain multiple classes without spaces
@th #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
theadadded
Adds a <thead> element 
# Create a <thead> element
@thead

# Create a <thead> element with class='className'
@thead .className

# Create a <thead> element with id='idName'
@thead #idName

# Create a <thead> element with id='idName' and class='className'
@thead #idName.className

# Chain multiple classes without spaces
@thead #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
tradded
Adds a <tr> element 
# Create a <tr> element
@tr

# Create a <tr> element with class='className'
@tr .className

# Create a <tr> element with id='idName'
@tr #idName

# Create a <tr> element with id='idName' and class='className'
@tr #idName.className

# Chain multiple classes without spaces
@tr #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
uladded
Adds a <ul> element 
# Create a <ul> element
@ul

# Create a <ul> element with class='className'
@ul .className

# Create a <ul> element with id='idName'
@ul #idName

# Create a <ul> element with id='idName' and class='className'
@ul #idName.className

# Chain multiple classes without spaces
@ul #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
vradded
Adds a <vr> element 
# Create a <vr> element
@vr

# Create a <vr> element with class='className'
@vr .className

# Create a <vr> element with id='idName'
@vr #idName

# Create a <vr> element with id='idName' and class='className'
@vr #idName.className

# Chain multiple classes without spaces
@vr #idName.className.otherClassName
Child Entities
attr
Sets an attribute property to a value
class
Sets the class attribute property to a value
id
Sets the id attribute property to a value
Other entites
cssadded
Adds some styles to be applied to the page (adds a <style> element to the <head>
Example
Quantum
@css
  .some-class {
    display: none;
}
htmladded
Adds some html directly to the page
Example Markup
Quantum
@html
  <b>Bold</b> <i>Italic</i> <u>Underlined</u>
Example Result
Bold Italic Underlined
hyperlinkadded
Adds an <a> element, with the href set to the link specified in the parameters.
Example Markup
Quantum
@hyperlink(path/to/somewhere)[Link Text]
Example Result
Link Text
jsadded
Adds some javascript to be executed on the page (adds a <script> element to the <body>) It is not placed at the end of the body like the @script entity
Example
Quantum
@js
  const a = 1
  alert(a)
scriptadded
Adds a link to a javascript file to the bottom of the <body>
Example
Quantum
@script [http://example.com/script.js]

@script [/path/to/script.js]
stylesheetadded
Adds a link to a css file to the bottom of the <head>
Example
Quantum
@stylesheet [http://example.com/style.css]

@stylesheet [/path/to/style.css]
titleadded
Sets the page title (adds a <title> element to the <head>
Example
Quantum
@title [Page Title]
API
Below are all the properties of the object returned from require('quantum-html'). For information about different versions, see the Changelog
Prototypes
HTMLPageadded
A prototype for storing transformed pages.
This type is created by the buildDOM function. It is designed to be used in the buildHTML function to convert from the transformed Array[Element] into stringified html content.
Properties
elementsArray[Element]
a virtual dom representation of a transformed File
contents
Functions
buildDOMoptionsObjectFileTransformadded
Returns the FileTransform function that converts parsed quantum source to virtual dom ( HTMLPage) pages using a series of EntityTransform functions.
Arguments
options
The options to use when building the virtual dom
Properties
defaultTransformEntityTransform
The default EntityTransform to use for entities that do not have a transform defined.
Default: 
const quantum = require('quantum-core')
function (selection) {
  return quantum.isSelection(selection) ? selection.cs() : selection
}
entityTransforms
Default: 
require('quantum-html').entityTransforms()
includeCommonMetaTagsBoolean
Whether to add the common meta tags to pages: 
<meta name="viewport" content="width=device-width, initial-scale=1">
Default: true
meta
An object containing data that is accessible in all EntityTransform functions as a third argument.
It is mainly useful for custom entity transforms, it should never be used in quantum modules.
Returns
FileTransform
buildHTMLoptionsObjectFileTransformadded
A function for converting a HTMLPage (the output of the buildDOM) function to HTML.
It converts the file objects content to an HTML string and gives the dest of the file the .html extension.
Arguments
options
The options to use when building the HTML
Properties
assetPathString
The path to output assets and resources to to.
By default, this will output to the same directory that the file including it was output to.
baseUrlString
The baseUrl to prefix assets with. This is passed to quantum-dom when stringifying content to make sure files are included from the correct folder.
Default: undefined
embedAssetsBoolean
Whether to embed assets that are embeddable on the page itself or include them in the assetPath directory.
When this is false, all assets will be output to the asset directory and linked.
Default: true
Returns
FileTransform
entityTransformsObject[EntityTransform]added
A function that returns a set of EntityTransform functions for use when rendering a page.
Returns
Object[EntityTransform]
The entity transforms to use in fileTransform to define the entities that can be rendered.
fileTransformoptionsObjectFileTransformadded
Builds a file transform that takes a File, converts it to HTML and then renames files to make a sensible directory structure for the site.
It applies the buildDOM, the buildHTML and then the htmlRenamer file transforms in sequence.
Arguments
options
buildDOM Options
The options to pass to the buildDOM function.
defaultTransformEntityTransform
entityTransforms
includeCommonMetaTagsBoolean
meta
buildHTML Options
The options to pass to the buildHTML function.
assetPathString
embedAssetsBoolean
resourcesTargetString
Returns
FileTransform
htmlRenamerFileTransformadded
Returns a file transform that renames name.html to name/index.html and leaves index.html as it is.
This is to provide a better URL structure for sites so all html files are called index.html and therefore don't need to be directly referenced (e.g. example.com/my-page/ instead of example.com/my-page.html
Returns
FileTransform
paragraphTransformselectionSelectiontransformerEntityTransformArray[Element]added
An EntityTransform that converts the text in an entity into paragraphs.
This is mostly useful when writing content with a word-wrap column limit as you can break content onto multiple lines in the source whilst having it render as paragraphs on the page.
Example Markup
customTransform.js (Javascript)
const html = require('quantum-html')
function customTransform (selection, transformer) {
  return html.paragraphTransform(selection, transformer)
}
Quantum
@customTransform
  Content separated with a single
  newline will
  be grouped
  into
  a single
  paragraph.

  Whereas content

  Separated by multiple newlines

  Will be made into separate paragraphs
Example Result
Content separated with a single newline will be grouped into a single paragraph.
Whereas content
Separated by multiple newlines
Will be made into separate paragraphs
Arguments
selectionSelection
transformerEntityTransform
Returns
Array[Element]
An array containing an Asset (for styling the paragraphs) and <p> elements (represented in quantum-dom)
prepareTransformsentityTransformsObjectObject[EntityTransform]added
A function that flattens out namespaced entity transforms into a single object.
Example Markup
Javascript
const entityTransforms = {
  aNamespace: {
    aTransform: aFunction,
    bNamespace: {
      bTransform: bFunction
}
},
bTransform: lastDefinedFunction
}

const flattenedTransforms = prepareTransforms(entityTransforms)
Example Result
{
  'aTransform': aFunction,
  'aNamespace.aTransform': aFunction,
  // The last defined function with a given namespace will be used as the 'top level' transform
  'bTransform': lastDefinedFunction,
  'bNamespace.bTransform': bFunction
}
Arguments
entityTransforms
The object of nested Transform functions to flatten.
Returns
Object[EntityTransform]