Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview

I have completed a long effort to provide a from-scratch documentation for Tolk.

The previous version, which I had been incrementally maintaining since January, focused on "Tolk vs FunC" differences.

The new one does not require any prior knowledge of FunC. A reader approaches Tolk directly.

The documentation contains many examples, snippets, and real-world cases. Before starting this work, I reviewed the official docs for Rust, Go, and Kotlin — to absorb best practices for presenting a programming language.

What's inside: brief description

Every aspect of the Tolk language is covered:

• Type system — every type has its own page. Numbers, addresses, other atomics, structures and generics, nullable and union types, tuples, maps, callables, etc. Each page includes nuances and examples. Overall pages describing how each type is represented in TVM and serialized into cells are also included.
• Syntax details — how various language constructs look and what they are used for. Variables, conditions, loops, exceptions, functions, methods, imports, etc. Grouped into distinct pages, with examples and usage guidelines.
• Language features — how to use Tolk for TON smart contracts. Handling and sending messages, storage and get-methods, auto-serialization, lazy loading, etc. Every page focuses on a dedicated topic and provides a deep dive, including answers to common questions.
• Migrating from FunC — a fully redesigned set of pages for developers coming from FunC. No separate "in short" and "in detail" versions; instead, a single long-read with short examples and references to other pages.

Additionally, there are two entry-point pages:

• Basic syntax — to get an overall picture of how the language looks.
• Idioms and conventions — best practices for writing idiomatic Tolk code.

The english style used while writing

All pages are written in a short, formal style (as opposed to the PR descriptions I like to create).

• no introductory sentences, like "this page describes ..." or "here we will learn ..." — clear and to the point
• no second-person rule ("you", "we") — although in a few specific places I intentionally used "you"
• pixel-perfect rendering — I not only "just write" the content, but always check how it renders in a browser. The goal is to avoid hanging words, keep line lengths readable, keep bullets one-line where possible, etc. In many places, the English may be slightly incorrect — and most of those cases are intentional for shortening and precise rendering.

Syntax highlighting!

The current documentation lacks of syntax highlighing, because Mintlify does not support custom languages. FunC, Fift, etc. — all of them are rendered as black plain text.

Tolk documentation contains hundreds of snippets and looks too depressive without highlithing.

That's why I implemented a temporary solution — all snippets are now colorful, in both dark and light modes. Just take a look:

All ```tolk snippets are highlighted automatically: no changes in mdx markup is required.

The highlighing is client-side, via Prism.js, whose sources are embedded. See extra.js for implementation, and extra.css for coloring.

Hopefully, some day, Mintlify will introduce native server-side highlighing. Then, we can discuss across coloring. I fine-tuned grammar and palette the way I prefer it (for example, structures and variables have different colors, because of the capital letter). The current VS Code tmLanguage file is not suitable for this — it must be updated.

For reviewers

If anyone decides to review all the text in this PR, keep this in mind:

• ... three dots in code snippets are intentional; small snippets are not meant to be copy-pasted — they demonstrate a specific feature
• "you" is intentionally used in several (seldom) places, even though it formally breaks a no second-person rule, because in those places it sounds significantly better

About merging this PR

Git history is split into multiple sensible commits. For instance, a syntax highlighter is a separate commit.

It's up to you whether to "Squash and merge" all changes into a single commit or to "Rebase and merge" to preserve Git history. I do not see any disadvantages in having multiple commits.

For future changes

If anyone plans to modify the contents in the Tolk documentation, please remember:

• pixel-perfect rendering — do not change content (especially replacing short words with long ones) without checking how it renders with default settings (100% zoom, desktop). Avoid handing words, prefer one-line bullets, and double-check whether a particular word was chosen specifically to fit the line.
• syntax highlighting — described above

The documentation in numbers

All together, the new Tolk documentation contains:

• 46 pages
• 480 ```tolk snippets
• 40000 words
• 280000 characters

I invested ~200 hours developing the text and picking every word — exactly 14 days, about 14 hours a day.

I hope that, cumulatively, this documentation will save noticeably more time for all TON developers.

Closes #1473
Closes #1114
Closes #1128

Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview