Nodes

Nodes are the central building block of a GSP document. A node consists of a name, an optional series of attributes, and a node body. A meta tag detailing the document character set may look like so:

meta charset="UTF-8" {}

Nodes can be trivially nested within other nodes. The following shows the skeleton of a basic HTML document:

html lang="en" {
	head { ... }
	body { ... }
}

Some specific elements such as ‘br’, ‘meta’, and ‘link’ are defined as ‘void elements’ by the HTML living standard. Such elements are forbidden from having child nodes.

Note that attributes are not required to be space-separated, although it is considered good style to always space-separate them.

For details on what characters are allowed in node names, see Character Sets.

Comments

A node and all of its subnodes can be commented out by prefixing it with ‘/’ followed by zero or more spaces.

div {
	/ p {- I am commented out }
	p {- I am not commented out }
}

Classical line comments are not supported, but can be emulated by commenting out a dummy node:

/ _ {- TODO: Update the year }
footer {- © 2025 The GSP Developers }

Attributes

Attributes are optional components of a node. They take the form of an attribute name and an optional attribute value. To specify an attribute, simply write the attribute name:

name

If you want to provide a value, you must follow the name with an equals sign (‘=’) and then wrap the value in double quotes (‘"’):

name="value"

The same attribute may be specified multiple times, in which case its value will be the concatination of all specified values with a space (‘ ’). As as a result, the following two examples are equivalent:

blockquote
	data-author="~lmatei"
	data-author="~tvoss"
{- ... }

blockquote data-author="~lmatei ~tvoss" {- ... }

Backslashes (‘\’) can be used to escape quotation marks and other backslashes that appear in the value:

name="he said \"hello there\""

For details on what characters are allowed in attribute names, see Character Sets.

IDs and Classes

IDs and classes are typically the most common attributes you want to specify on a node, and as such there exists a shorthand syntax for specifying IDs and classes matching CSS selector syntax.

Since these are just shorthand syntaxes, the following examples are considered equivalent:

h1 #intro .bold .underline {- ...}

h1 id="intro" class="bold underline" {- ...}

When using this shorthand syntax, the ID and class names follow the same rules as attribute names. To define an ID or class that uses disallowed characters in its name, the longform syntax should be used:

h1 class="class#name#using#hashes" {- ...}

Document Types

There exists no syntax for declaring document types in GSP documents. Transpilers between GSP and HTML such as gsp(1) may decide how they wish to handle document types, if they wish to handle them at all.

Text

The follow subsection does not apply to the ‘style’ and ‘script’ nodes. Details regarding the special handling of those nodes, see CSS and JavaScript.

If a node body features either a minus or an equals-sign directly after the opening brace (‘{-’ or ‘{=’) then the contents of the node body are taken to be text as opposed to additional child nodes.

The difference between the two forms of text body revolves around whitespace handling. When opened with ‘{-’, all leading and trailing whitespace is removed. This includes not just ASCII spaces, but other forms of whitespace such as non-breaking spaces too. To avoid whitespace trimming and to manage whitespace manually, a text body can be opened via ‘{=’.

Within body text the following characters have special meaning which can be ignored by way of backslash-escaping:

@

Begins an embedded node (see Embedded Nodes)

\

Begins an escape sequence

{

Ignored for purposes of brace-balancing when escaped

}

Ignored for purposes of brace-balancing when escaped

When unescaped, braces are always balanced and as such rarely require manual escaping:

p {- GSP node bodies are delimited by ‘{’ and ‘}’. }

Embedded Nodes

Embedded nodes allow you to embed nodes within text. These nodes are exactly the same as regular nodes, but are prefixed by an at symbol (‘@’). Since embedded nodes behave identically to regular nodes, they can also be commented out:

p {-
	Kokkola (Swedish: @em{-Karleby}) is a town in Finland and the
	regional capital of Central Ostrobothnia.
	@/_{- TODO: Figure out the Finnish and Swedish names }
}

Macros

NOTE: This subsection only discusses the function and syntax of macros. For documentation on creating macros and how they operate, see gsp-macros(7).

Macros offer a means to dynamically generate output using external executables. There are two types of macros: regular macros, and verbatim macros. Regular macros are macros that output valid GSP markup, which is then reparsed and evaluated. Verbatim macros on the other hand do not have their output processed. This means that when transpiling GSP to HTML, special care must be taken to ensure that all verbatim macros output valid HTML markup.

Macros are syntactically identical to regular nodes, except that their names must be prefixed with a dollar sign (‘$’):

p {-
	Today’s date is @$date{}.
}

Verbatim macros are specified and used in the same manner, except that they must be prefixed with two dollar signs:

pre {
	$$syntax_highlight lang="c" {- $$include file="main.c" {} }
}

CSS and JavaScript

CSS and JavaScript can be included in GSP documents by way of the ‘style’ and ‘script’ nodes. Unlike other nodes, these nodes do not take text or node bodies, they instead take CSS markup in the case of ‘style’ and JavaScript code in the case of ‘script’. As these nodes do not take standard text-bodies and instead have their respective languages handled natively, metacharacters described in Text do not require escaping, and neither the CSS markup or JavaScript code undergoes any HTML escaping during transpilation by transpilation tooling.

To ease tooling implementation, full-blown CSS or JavaScript parsing is not required. The ‘style’ and ‘script’ tags instead simply need to handle brace nesting. This allows implementations to simply need to implement basic lexers for the two languages.

The following is an example of using CSS and JavaScript from within a GSP document:

head {
	style {
		.article-list li {
			font-weight: bold;
			text-decoration: underline;
			text-decoration-skip-ink: all;
		}
	}
	script {
		document.addEventListener("DOMContentLoaded", _ =>
			console.log("DOM fully loaded and parsed"));
	}
}

Character Sets

GSP defines 3 distinct sets of characters:

Identifier Starters

Characters which are legal as the first character in a node or attribute name.

This set is defined as the characters allowed as the first character in an XML tag name, plus the dollar sign (‘$’).

Identifier Continuers

Characters which are legal in a node or attribute name, but not necessarily in the first position.

This set is defined as the characters which are legal in an XML tag name, but not necessarily in the first position.

Whitespace

Characters which are recognized as whitespace and are ignored for parsing purposes, and which are trimmed by automatic whitespace trimming.

This set is defined as the set of all Unicode characters with the ‘White_Space’ property.