SML Textbook
SML Textbook { ❄ }
Welcome to the official SML (SNOWARE Markup Language) textbook.
This is a beginner-friendly, progressive book that also works as a reference. Whether or not you’ve used JSON / YAML / TOML, you can learn to write SML config and describe data from scratch.
In one sentence: SML is a declarative data / configuration format — write config like a sticky note: quotes optional, commas optional, structure delimited by braces
{}.
How to read this book
- Beginner: start from Chapter 1 and read chapter by chapter; each has a “try it” section.
- Experienced: jump to Chapters 4–5 for include / contracts.
- Lookup: use the TOC below or the appendix “cheatsheet / troubleshooting”.
Table of contents
| Chapter | Topic | You’ll learn |
|---|---|---|
| Preface | Why SML | what it solves, vs JSON/YAML |
| Ch1 | Your first SML file | key/value, comments, scalars |
| Ch2 | Blocks & nesting | object blocks, arrays, optional colon |
| Ch3 | Fragment inheritance | @base / &base reuse |
| Ch4 | include & namespaces | split files, as ns, import alias |
| Ch5 | Contract system | @contract / @is, types, defaults, enums, ranges |
| Ch6 | Env vars & escaping | $env, \u and \n |
| Ch7 | Multi-language usage | Rust / C / JS / Lua integration |
| Ch8 | Real project | a near-real deployment example |
| Ch9 | Advanced composition | include/contract/fragment/$env patterns |
| Ch10 | feature reference | every feature’s toggle, syntax, errors |
| Appendix | Cheatsheet & troubleshooting | vs JSON/YAML/TOML, common errors |
Note on translation
The full English translation of the 12 chapters is in progress. The Chinese edition (教科书) is the authoritative, complete version. The English pages above currently redirect to the Chinese text where translation is not yet ready — switch languages with the EN / 中文 button in the header.
Ready? Start from the Preface.