Tools

The playground, the extension, the command line, the libraries and the editor implement the same five specifications and report the same error codes.

Depending on the use:

Use Tool
Try the language without installing anything The playground
Write documents regularly The VS Code extension
Validate from a script, a Makefile or CI The stxt command line
Read or generate STXT from a program A library: TypeScript, Java or Python
Edit or highlight STXT in a web page The editor @stxt-lang/editor
Generate PDF from STXT documents stxt-pdf (Java library) or stxt-press (service)

Playground

play.stxt.dev is an editor in the browser: several documents at once, their schemas or templates next to them, syntax and validation errors while editing, grammar-driven autocompletion and hover with the definition of each node.

  • No installation and no account; the work is kept in the browser itself.
  • It includes a seed of example documents.
  • The whole workspace can be shared with a link that carries the content inside.

VS Code extension

The official extension is STXT Language (stxt-lang.stxt). It is installed from the extensions view, searching for stxt, or from the terminal:

code --install-extension stxt-lang.stxt

Features:

  • Syntax errors in real time, and schema errors; a namespace no level defines is flagged with SCHEMA_NOT_FOUND as a warning.
  • Semantic highlighting.
  • Completion with the nodes the schema allows and the values of an ENUM.
  • Hover information: the description given by the definition, the type and, in an ENUM, its values.
  • Go to definition (F12): from a node to the Node: of its schema, or to its line inside the Structure of its template.
  • Document formatting.
  • Schema and template resolution from the .stxt/ directories of the project, the user and the system, as described in the discovery reference.

Command line

The stxt command is published on npm as @stxt-lang/cli and requires Node 20 or newer.

npm install -g @stxt-lang/cli
stxt --version

Without installing, through npx:

npx @stxt-lang/cli validate --recursive docs/

The commands:

Command What it does
stxt validate Parses and validates one or more files or directories; no output when all pass
stxt format Reformats (--tabs / --spaces); --check for CI, --write to save
stxt describe Prints the logical tree of a document as JSON (STXT-TREE-SPEC)
stxt schemas Shows which schemas and templates apply in a directory, and from which level
stxt install Installs a definition into ./.stxt, ~/.stxt or the system level

The exit code distinguishes document errors (1) from command misuse (2). No command rewrites files without an explicit option. The options, outputs and exit codes are in the command-line reference.

Libraries

There are three official implementations: TypeScript/JavaScript, Java and Python. All three pass the conformance kit, which also serves to check a port to another language.

TypeScript / JavaScript

@stxt-lang/core on npm. It is the parser the extension, the command line and the playground use. The guide is in the TypeScript library. In the browser it also loads with a <script> from a CDN.

npm install @stxt-lang/core

A minimal example:

import { Parser, InlineNode } from '@stxt-lang/core';

const result = new Parser().parseResult(text);
for (const error of result.getErrors()) {
	console.error(`line ${error.line} [${error.code}]: ${error.message}`);
}
const root = result.getNodes()[0];
if (root instanceof InlineNode) {
	console.log(root.getChild('Title')?.getText());
}

Java

dev.stxt:stxt-core on Maven Central. Java 17 or newer; automatic module dev.stxt. The guide is in the Java library.

<dependency>
    <groupId>dev.stxt</groupId>
    <artifactId>stxt-core</artifactId>
    <version>1.0.4</version>
</dependency>

Or with Gradle:

implementation 'dev.stxt:stxt-core:1.0.4'

Python

stxt on PyPI. Pure Python, 3.10 or newer. The guide is in the Python library.

pip install stxt

A minimal example:

from stxt import Parser, InlineNode

result = Parser().parse_result(text)
for error in result.get_errors():
    print(f"line {error.line} [{error.code}]: {error.message}")
root = result.get_nodes()[0]
if isinstance(root, InlineNode):
    print(root.get_child("Title").get_text())

Editor for web pages

@stxt-lang/editor on npm. It is the editor of the playground as a library: it turns a <textarea> into an editor with highlighting, errors while editing and grammar-driven completion. It includes a static highlighter for pages that only show STXT. The guide is in the editor for web pages.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stxt-lang/editor@0.4.0/dist/stxt-editor.css">
<script src="https://cdn.jsdelivr.net/npm/@stxt-lang/editor@0.4.0/dist/stxt-editor.js"></script>

<textarea id="doc"></textarea>

<script>
    StxtEditor.fromTextArea(document.getElementById('doc'));
</script>

PDF generation

Two projects generate PDF from documents with the namespace dev.stxt.pdf, which describes the pages, the content and its styles:

Document (dev.stxt.pdf):
	Language: en
	Title: Quarterly report
	Page:
		Paper: A4
		Margin: 50
	Styles:
		For element: Document
			Typography:
				Font: IBM Plex Sans
				Size: 10
	Section:
		Heading 1:
			Text: Quarterly report
		Paragraph: Sales grew by 12% compared with the previous quarter.

Both read the STXT with the Java library and are not implementations of the language. They are in 0.x: the namespace dev.stxt.pdf and its API may still change between minor versions. The guide is in PDF and Press.

stxt-pdf

stxt-pdf is the engine: a Java library that lays out the document, splits it into pages and writes the PDF, with embedded fonts, tagging for accessibility (PDF/UA) and PDF/A on request. It is published on Maven Central as dev.stxt:stxt-pdf and needs Java 17 or later. The manual, the reference and the examples, with their PDF, are in the repository.

<dependency>
    <groupId>dev.stxt</groupId>
    <artifactId>stxt-pdf</artifactId>
    <version>0.19.0</version>
</dependency>

Or with Gradle:

implementation 'dev.stxt:stxt-pdf:0.19.0'

A minimal example, which converts the document above:

import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;

import dev.stxt.InlineNode;
import dev.stxt.pdf.convert.Converter;
import dev.stxt.pdf.stxt.DocumentReader;

InlineNode doc = new DocumentReader().read(Path.of("report.stxt"));
try (OutputStream out = Files.newOutputStream(Path.of("report.pdf"))) {
    Converter.create().toPdf(doc, out);
}

Fonts and images are looked up in the folder resources/ of the working directory, in fonts/ and images/. Only the fonts of that folder are used, never those of the system. The repository includes IBM Plex Sans, Serif and Mono.

stxt-press

stxt-press is a service on stxt-pdf: it generates PDF and SVG from templates, with their Slots filled with JSON data, or from documents without data. It has an HTTP API, a web editor and a command line, in a single jar. It is published as a Docker image at ghcr.io/stxt-lang/stxt-press:

docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/stxt-lang/stxt-press:0.7.0

The index and the editor are at http://127.0.0.1:8080/, with example templates and documents. A template, filled with its sample data or with those of a JSON file:

curl -o invoice.pdf http://127.0.0.1:8080/print/examples/invoice
curl -o invoice.pdf -d @invoice.json http://127.0.0.1:8080/print/examples/invoice

Without Docker, the folder server/ of the repository is a whole server (the jar, its configuration, the fonts and the examples), started with server/start.sh and Java 17 or later.

Source code

The whole ecosystem lives in the stxt-lang organization on GitHub, under the MIT license:

Repository Contents
stxt-lang This site: the specifications, the conformance kit and the example corpus
stxt-js @stxt-lang/core, the TypeScript library
stxt-java dev.stxt:stxt-core, the Java library
stxt-python stxt, the Python library
stxt-cli @stxt-lang/cli, the command line
stxt-vscode The VS Code extension
stxt-play The playground
stxt-editor @stxt-lang/editor, the editor for web pages
stxt-pdf dev.stxt:stxt-pdf, the PDF engine
stxt-press The PDF and SVG service

Questions and ideas about the language go to the discussions of the organization; bugs, to the issues of the repository of the tool concerned.