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_FOUNDas 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 theStructureof 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.