Documentation Index

Fetch the complete documentation index at: https://docs.ton.org/llms.txt

Use this file to discover all available pages before exploring further.

​

TON documentation style guide

​

0. Purpose, scope, and normative terms

• Page — a single documentation article.
• Doc type — one of: Step by step, How‑to guide, Explanation, Reference (see §3).
• Snippet — any code or command block.
• Partial snippet — a focused excerpt that MAY be non‑runnable by itself and MUST be labeled as such (see §10).
• Placeholder — a value the reader must replace; formatted as <LIKE_THIS>.
• Admonition — a callout such as Note, Tip, Important, Caution, or Warning.
• Reference anchor — a deep link to a specific item in a reference page (flag, field, error code, and similar items).

​

Severity model (release‑blocking)

​

1. Goals and principles (reader‑first, answer‑first)

• Intent. Every page exists to help a developer finish a real task quickly and correctly.
• Pages MUST optimize for clarity, scannability, accuracy, and trust;
• Pages MUST NOT contain marketing language in technical sections. [HIGH]
• Pages SHOULD be answer‑first (solution before theory) and example‑first (real code before exposition). (Why: task‑focused, plain, and scannable pages help readers complete work on the first try; marketing copy and theory up front slow readers and reduce trust.)

1. Answer‑first. Open with purpose, outcome, and prerequisites. Then show the steps (or the API signature in reference). Background theory moves to its own Explanation page or a brief end section. (Why: leading with the solution shortens time‑to‑success; moving theory prevents detours for readers who just need to act.) Example (good): Goal: “Send a jetton from a web app.” Prerequisites: JS SDK, funded testnet wallet. Steps: 1–5. Verify: expected output. Troubleshoot: common errors.
2. Example‑first and precise. Provide copy‑pasteable snippets with expected output. Use <PLACEHOLDER> values and define them at first use. Avoid unnecessary narrative around code. (Why: runnable, minimal examples remove guesswork; placeholders prevent users from pasting unsafe, hard‑coded values.)
3. Minimal concepts in task pages. Do not front‑load long explanations in step-by-step/how‑tos. Link to a concept page instead. (Why: keeping theory separate avoids cognitive overload; readers can pull background only if they need it.)
4. Single source of truth. Don’t duplicate reference tables in guides. Summarize only what’s needed, then link to the reference anchor. (Why: duplication drifts and conflicts; deep links keep guides brief and ensure details stay correct in one place.)
5. Scannability. Prefer short paragraphs (≤ ~5 sentences) and short sentences (~15–20 words). Use headings, lists, and tables to chunk information. See §8 for norms and flexibility. (Why: short, well‑chunked text is faster to scan and reduces rereads and errors.)

​

2. Audience and assumptions

​

2.1 What belongs in Prerequisites

• Software already installed (not installed during the guide). Specify version and link to download page.
• Accounts or access already obtained: API keys, RPC endpoints, wallet accounts.
• Artifacts from prior work: "A deployed contract from [Deploy a counter](/path/to/guide)", "A funded testnet wallet".
• Funds or tokens: “Testnet TON from the faucet”.
• Unusual hardware (only when relevant): “A machine with at least 16 GiB RAM”.

​

2.2 What does not belong in Prerequisites

• Obvious assumptions. You MUST NOT list: internet connection, an operating system, a keyboard, a terminal/shell, a browser, a text editor, or similar universal tools. (Why: obvious items waste space and insult reader intelligence.) [HIGH]
• Things installed or created during the guide. If step 1 is “Install the SDK”, the SDK is NOT a prerequisite — the prerequisite is what is needed to install it (e.g., Node.js). You MUST NOT list items that the guide itself provides. (Why: listing in‑guide installations as prerequisites confuses readers about what they need beforehand.) [HIGH]
• Skills or knowledge. “Familiarity with TypeScript” or “Understanding of smart contracts” are audience statements, not prerequisites. Use a separate “Audience” note for these (e.g., “Audience: Intermediate. Assumes working knowledge of TypeScript and async/await.”). You MUST NOT mix skills into the Prerequisites list. (Why: skills cannot be “installed” or verified the same way; separating them clarifies what readers need to do vs. know.) [HIGH]
• Background reading or concept links. "Read the [Account model](/foundations/accounts) page first" belongs in prose or a “Background” section, not Prerequisites. If understanding a concept is truly required, state it as an audience assumption. You SHOULD NOT put learning links in Prerequisites. (Why: prerequisites are for artifacts and tools, not reading assignments.)

​

2.3 Version specifications

• Software prerequisites MUST specify at least the version tested in the guide. (Why: unversioned requirements cause “works on my machine” failures.) [HIGH]
• Software prerequisites SHOULD specify a supported range when known (e.g., “Node.js 20 or later LTS”, “Python 3.10+”). (Why: ranges tell readers whether their existing installation works.)
• You MUST NOT use vague terms like “latest” or “recent version”. (Why: “latest” changes over time and provides no actionable information.) [HIGH]

​

2.4 Links in Prerequisites

• Each software prerequisite MUST link to an official download or installation page, not to the project homepage or documentation root. (Why: readers need to act, not browse; download pages are actionable.) [HIGH]
• For tools with OS‑specific installers, you MAY link to a general downloads page that offers all variants.
• For TON‑ecosystem tools documented in these docs, link to the internal installation guide if one exists.

​

2.5 Prerequisite examples

Prerequisites:
- [Node.js](https://nodejs.org/en/download/) 20 or later LTS
- A funded testnet wallet (get testnet TON from the [faucet](https://t.me/testgiver_ton_bot))
- An RPC endpoint — use a public endpoint or get one from [TON Center](https://toncenter.com/)

Prerequisites:
- A computer with internet access  ← obvious
- Node.js  ← no version, no link
- Install the TON SDK  ← installed in the guide, not a prerequisite
- Familiarity with JavaScript  ← skill, not a prerequisite
- Read the [wallets overview](/wallets)  ← background reading, not a prerequisite

​

2.6 Audience and skill assumptions

Audience: Advanced. Assumes understanding of TVM exit codes and TL‑B schemas.
See: [TVM exit codes](/tvm/exit-codes), [TL‑B overview](/data-formats/tlb).

​

3. Documentation framework (content types)

​

3.1 What each type means (and looks like)

• Step by step (first success). Single happy path for newcomers. Hand‑holding is RECOMMENDED. (Why: one clear path gets novices to a working result quickly; branching early increases drop‑off.) Title style: “Deploy a counter contract on testnet”. (Why: action‑oriented titles set expectations and help search/TOC scanning.) Sections (suggested): Objective → Prerequisites → Steps → Verify → Troubleshoot → Next steps. Keep Next steps minimal (1–3 essential links) or omit when the path is linear. SHOULD avoid theory beyond two short bullets; link to an Explanation page. (Why: predictable structure reduces cognitive load; keeping theory brief prevents blocking progress.)
• How‑to guide (goal‑oriented procedure). A recipe to achieve a specific outcome. MUST be procedural and concise. (Why: readers come for a recipe; extra narrative slows execution and invites errors.) Title style: “How to mint a jetton with the CLI”. (Why: the “How to …” pattern matches search intent and signals page type while staying specific.) Rule: MUST NOT embed long background; link to concepts as needed. (Why: avoids duplication and keeps the guide focused; background stays current in one canonical place.)
• Explanation (concepts/why). Background, architecture, trade‑offs. SHOULD avoid step lists and commands. (Why: separating “why” from “how” improves comprehension and prevents pages from doing two jobs badly.) Title style: “Account model and messages in TON”. (Why: noun‑based titles signal conceptual content and improve browseability.)
• Reference (complete, factual). Exhaustive specs for APIs/CLI/SDK/types/errors. Non‑narrative tables and exact semantics. (Why: factual, uniform entries are scannable and machine‑linkable; narrative slows lookups.) Title style: “tvm.runvm — interface and exit codes”. (Why: placing the exact identifier in the title improves search and deep linking.) Rule: MUST be precise, consistent, and anchor‑linkable. (Why: deep anchors let guides link directly; precision prevents support churn and conflicting copies.)

​

4. Voice and tone

• Use present tense, active voice, and the imperative mood. Write steps as commands (e.g., “Run the validator.”), not future tense or passive voice. Avoid addressing the reader with “you”. (Why: imperative, active phrasing makes the action clear without personal address and reduces ambiguity in steps.)
• Be neutral and inclusive. Avoid slang, idioms, culture‑specific jokes, or hype. (Why: neutral language is easier for non‑native readers and translators, and avoids alienating parts of the audience.)
• MUST NOT use filler or patronizing words: simply, just, obviously, clearly, please note. Replace with exact instructions (Why: filler wastes time and can sound condescending; precise verbs tell the reader exactly what to do.)
• Emojis in prose and headings MUST NOT appear. Use clear text or an <Aside> when emphasis is needed. (Why: emojis are ambiguous, distract from procedures, and do not localize reliably.)
• Emojis in code/command blocks MAY appear only when they are part of runnable code or a literal command/output string. Do not add emojis for decoration; the snippet MUST remain copy‑pasteable and executable as shown. If quoting a UI/log message that contains an emoji, keep it verbatim inside quotes. (Why: runnable examples take precedence; avoiding decorative emojis preserves clarity and execution.)
• Emojis in compact tables MAY be used sparingly as visual indicators only when they follow a widely understood convention (for example, ✅ / ❌ for supported/not supported, or ★ to mark a recommended option) and MUST be paired with a text label in the same cell or a descriptive header (e.g., “Supported — Yes/No”). Do not rely on an emoji alone to convey meaning, and MUST NOT use decorative or non‑standard pictograms (for example, a play triangle to indicate videos). (Why: paired, conventional icons preserve clarity for screen readers, localization, and cases where emojis don’t render.)
• Even where emojis are technically allowed (code/output or compact tables), they SHOULD be rare and MUST have a clear purpose. If the same meaning is clear without the emoji, remove it. (Why: conventional text remains clearer for global readers and translators.)
• Use plain terms over legalese/Latinisms. “Use” not “utilize”; “before” not “prior to.” (Why: common words improve comprehension and reduce rereads; they are also translated more consistently.)
• Avoid first‑person pronouns (“we”, “I”, “our”). When an organization, product, or service is the actor, use its proper name (e.g., “Tonkeeper”, “TON”) or a neutral noun (“the node”, “the SDK”). Prefer imperative instructions without “you”. See §5.8 and §5.10. (Why: neutral, explicit actors read cleanly and translate reliably.)

• You MUST NOT use marketing‑style language anywhere in technical content, including titles, headings, steps, tables, references, and callouts. This includes: [HIGH]
  • Superlatives and hype: “blazingly fast”, “revolutionary”, “world‑class”, “seamless”, “best‑in‑class”, “powerful”, “cutting‑edge”.
  • Vague positive adjectives: “reliable”, “robust”, “essential”, “elegant”, “intuitive”, “flexible”, “comprehensive”, “scalable” (when used without measurable criteria).
  • Dramatic or emotional framing: “elusive”, “challenging”, “painful”, “frustrating”, “nightmare”, “perfectly”, “beautifully”. Technical writing states facts, not feelings.
  • Intensity words that exaggerate: “instantly”, “immediately” (unless literally true), “extremely”, “incredibly”, “massive”, “huge” (for non‑quantified values).
  • Storytelling openers: “Imagine…”, “Picture this…”, “Have you ever…”, “What if…”. Start with the task or fact instead.
  (Why: hype and drama erode trust, slow scanning, obscure required actions, and age poorly.)
• Replace subjective claims with measurable facts (numbers, constraints, conditions) or remove them entirely. If a claim cannot be tested or measured, delete it. (Why: facts enable correct implementation and reproducible results.) [HIGH]
• When describing benefits, state what happens and under what conditions, not how it feels. (Why: readers need actionable information, not emotional appeals.)
  • Bad: “This approach provides a robust and reliable solution.”
  • Good: “This approach retries failed requests up to three times with exponential backoff.”
  • Bad: “Tests catch issues instantly.”
  • Good: “Tests run in under 2 seconds and fail on the first assertion violation.”

• Bad: “We’ll just quickly configure the node; it’s super easy!” Good: “Configure the node.”
• Bad: “Let’s go ahead and utilize the script.” Good: “Run the script.”
• Bad: “Obviously, the transaction fails if the fee is low.” Good: “The transaction fails if the fee is too low.”

​

5. Grammar and usage

​

5.1 Voice, tense, and person

• You MUST use active voice by default. Passive voice MAY be used only when the actor is unknown or irrelevant. (Why: active voice makes who does what explicit; passive hides responsibility and confuses steps.)
  • Good: “The validator stops if the config is invalid.”
  • Bad: “The validator is stopped if the config is invalid.”
• You MUST use the present tense for general behavior and instructions; the future tense SHOULD be reserved for time‑dependent statements. (Why: present tense reads simpler and matches how‑to steps; future tense adds unnecessary words and ambiguity.)
  • Good: “The API returns JSON.”
  • Bad: “The API will return JSON.”
• Prefer imperative instructions without addressing the reader (“you”). Avoid first‑person pronouns (“we”, “I”, “our”); when an organization, product, or service is the actor, use its proper name (e.g., “TON Center”, “TON”). See §5.8 and §5.10. (Why: imperative, neutral phrasing keeps actors clear without personal address.)

​

5.2 Plain, precise wording

• You SHOULD prefer common words over legalese or Latinisms. (Why: familiar words are understood faster and translated more reliably.)
  • Use “use,” not “utilize.” Use “before,” not “prior to.”
• Hedging and filler MUST NOT appear: simply, just, obviously, clearly, please note. Replace with exact actions or facts. (Why: filler wastes time and can sound condescending; specifics tell readers exactly what to do.)

​

5.3 Acronyms and terms

• On first mention, you MUST spell out the term and follow with the acronym in parentheses. Use the acronym thereafter. (Why: defines terms once and keeps later text concise.)
  • Example: “The Open Network (TON)…”
• Project terminology MUST follow the term bank/glossary (see §13). Avoid introducing synonyms for the same concept. (Why: one canonical term prevents confusion and search/indexing issues.)

​

5.4 Audience calibration

• Assume developers are new to blockchain (but experienced in software). MUST NOT re‑teach generic developer skills unless a TON‑specific nuance requires it (see §2). Provide concise prerequisites when needed. (Why: focusing on TON reduces noise and keeps pages shorter and more relevant.)

​

5.5 Global and inclusive language

• You MUST avoid idioms, cultural references, and biased terms. Prefer neutral alternatives (e.g., allowlist/denylist). Use people‑neutral wording and accessible examples. (Why: idioms and bias exclude readers and harm translation; neutral wording is clearer for everyone.)

​

5.6 Spelling and contractions

• Spelling MUST follow American English (e.g., color, analyze). (Why: a single spelling standard prevents mixed variants and review churn.)
• Contractions (don’t, can’t) MAY be used when they improve flow and do not reduce clarity. (Why: natural phrasing is easier to read as long as the meaning stays clear.)

​

5.7 Avoid unfinished work

​

5.8 Don’t get personal

​

5.9 Avoid tautology, pleonasm, throat‑clearing, and circular references

​

Rules (normative)

• You MUST remove tautologies/pleonasms (duplicate meaning in different words). (Why: redundant pairs add length without adding meaning.)
  • Bad: “End result” → Good: “result”
  • Bad: “Advance planning” → Good: “planning”
  • Bad: “Free gift” → Good: “gift”
• You MUST NOT use throat‑clearing/circular openers that describe the doc instead of delivering value. (Why: readers come to act; meta‑introductions delay the task.) [HIGH]
  • Bad: “In this section, we will discuss how to…”, “This document aims to explain…”
  • Good: “Deploy a validator on testnet.” (start with the action)
• You SHOULD collapse wordy boilerplate into precise verbs. (Why: shorter, direct phrasing is faster to parse.)
  • Bad: “In order to” → Good: “To”
  • Bad: “For the purpose of” → Good: “To”
  • Bad: “Due to the fact that” → Good: “Because”
• You MUST avoid doublets/triplets (pairs that mean the same thing). (Why: repeating the same idea signals uncertainty and wastes space.)
  • Bad: “each and every”, “basic fundamentals”, “final outcome”, “past history”, “future plans going forward”, “merge together”, “close proximity”, “completely eliminate”
• You MUST avoid tautological logic and circular definitions. (Why: circular text doesn’t explain behavior and blocks understanding.)
  • Bad: “A jetton is a jetton if it conforms to the jetton standard.”
  • Good: “A jetton is a fungible token on TON defined by the Jetton standard, which specifies message formats for mint/transfer/burn.”
• You SHOULD replace hedges and intensifiers with facts. (Why: intensity words add emotion, not information; facts reduce ambiguity.) [HIGH]
  • Avoid: “basically”, “essentially”, “really”, “very”, “actually”, “literally” (unless literal).
  • If precision matters, give a number, constraint, or example instead.
• You MUST NOT use and/or. (Why: it is ambiguous; readers cannot tell if both are allowed or required.)
  • Write: “A, B, or both” or “A or B” (choose one).
• You SHOULD NOT use etc. in procedures or lists. (Why: open‑ended lists leave readers unsure what is required.)
  • Either complete the list or write “for example” and stop.
• You MUST avoid “as mentioned above/below”; link to the exact anchor instead (see §12). (Why: relative references break when pages change; links stay accurate.)
• You SHOULD simplify “whether or not” → “whether”; “the reason is because” → “because”; “not uncommon” → “common/often.” (Why: simpler forms are clearer and shorter.)

​

Before/after micro‑examples

• Throat‑clearing
  • Before: “In this guide, we will show you how to configure a validator.”
  • After: “Configure a validator.”
• Tautology
  • Before: “The final outcome of the deployment process…”
  • After: “The result of the deployment…”
• Wordy boilerplate
  • Before: “In order to reduce fees, you need to…”
  • After: “To reduce fees, …”
• Hedge + intensifier
  • Before: “It’s basically very important to verify the address.”
  • After: “Verify the address.”
• Circular reference
  • Before: “Sharding improves scalability because it shards the chain.”
  • After: “Sharding splits the chain into parallel shards that process transactions concurrently, increasing throughput.”

​

5.10 Pronouns and person references

• You MUST use gender‑neutral singular “they/them/their” when referring to an unspecified or generic person. MUST NOT use gendered or split forms such as “he”, “she”, “he/she”, “s/he”, or “(s)he” for generic subjects. [HIGH] (Why: singular “they” is inclusive, concise, and avoids awkward constructions.)
• Prefer imperative instructions or role nouns to avoid pronouns when possible (e.g., “Deploy the contract.” or “The operator updates the config.”). (Why: direct phrasing is clearer and reduces ambiguity.)
• When referring to a named individual who has stated pronouns, use that person’s pronouns; if unknown or irrelevant, default to “they”. (Why: respect individuals while keeping language inclusive.)
• Do NOT anthropomorphize software or networks with gendered pronouns. Use neutral nouns or “it” (e.g., “the node restarts”, “it fails to start”). (Why: avoids confusion and maintains technical tone.)
• For organizations, products, and services, use the proper name (e.g., “TON”, “Tonkeeper”) or the neutral “it”; do not use “we/I/our” in documentation. (Why: consistent, neutral references read cleanly and translate reliably.)

​

5.11 Parentheses

• Parentheses MAY be used for short clarifications and abbreviation expansions (for example, “The Open Network (TON)”) but SHOULD NOT be used for extended side remarks. (Why: side remarks buried in parentheses are easy to miss and hard to translate.)
• When a parenthetical includes an extra idea, condition, or step, split the sentence into two sentences or move the extra idea into its own sentence or list item instead of nesting it in parentheses. (Why: one idea per sentence is easier to parse and localize.)
• Where a parenthetical is necessary for precision, keep it short and avoid chaining more than one set of parentheses in the same sentence. (Why: multiple nested asides make sentences hard to read.)

​

6. Punctuation and mechanics

​

6.1 Commas, colons, semicolons

• The Oxford (serial) comma MUST be used in lists of three or more items: “nodes, wallets, and explorers.” (Why: prevents ambiguity about whether the last two items are grouped.)
• Comma splices MUST NOT occur. If two clauses can stand alone, use a period or a coordinating conjunction. (Why: run‑on sentences are hard to scan; separating clauses improves clarity.)
  • Bad: “The node restarts, it begins syncing.”
  • Good: “The node restarts. It then begins syncing.”
• Colons SHOULD introduce lists or explanations after a complete clause. Semicolons SHOULD be rare. Prefer shorter sentences. (Why: correct colon use signals structure; semicolons slow scanning and can often be replaced by periods.)

​

6.2 Quotation marks and emphasis

• Quotation marks MUST be used only for actual quotations or literal UI text/messages, not for emphasis. (Why: quotes indicate exact strings; using them for emphasis misleads readers and translators.)
  • Good: The error message “Account not found” appears.
  • Bad: The “validator” node… (do not quote terms)
• House rule — quoting style: Use the international style with American spelling. Quotation punctuation MUST remain outside closing quotes unless it is part of the quoted text. This differs from American book style; keep it consistent. (Why: keeps code‑adjacent strings accurate and avoids adding punctuation that isn’t part of the literal.) [HIGH]
• Use double quotation marks for log/error strings and other literal UI text when quoting it as text; place punctuation outside unless it is part of the string. (Why: quotes remain the convention for messages/text and keep literals copyable.)
• This rule applies to quoted UI/log/error strings only; it does not apply to code spans or headings. (Why: code spans and headings have their own styling rules.)
• Log messages and error strings MUST appear verbatim in quotation marks; MUST NOT add emphasis or change casing/punctuation. (Why: exact copying/grepping depends on matching strings.) [HIGH]
• When referencing interactive controls or keyboard keys that the reader should click or press, you MUST use <kbd>Label</kbd> for the control or key name. You MUST NOT use quotation marks, bold, or italics to style controls in instructions. (Why: <kbd> is designed for controls/keys and keeps actions easy to scan and copy.)
  • Good: Click <kbd>Settings</kbd>, then select <kbd>Network</kbd>.
  • Bad: Click “Settings” or Settings.
• UI or menu labels that appear in screenshots or descriptive text but are not being presented as actions MAY be written in quotes. Avoid mixing <kbd> and quoted labels arbitrarily; prefer one style consistently within a page/section. For quoted UI strings, follow the house quoting style above. Punctuation follows normal sentence rules outside <kbd>. (Why: consistent styling keeps text readable and copyable.)
• Error codes/identifiers MUST use code formatting: ERR_FEE_TOO_LOW, EADDRINUSE, ENOENT. (Why: code styling distinguishes tokens from prose and aids scanning and copy/paste.)
• When paraphrasing behavior, you MUST NOT alter message semantics; label paraphrases clearly and avoid quotation marks. (Why: altered wording leads to mismatches during troubleshooting.)

​

Emphasis (bold and italics)

• Bold and italics SHOULD be used sparingly in body text. Prefer structure (headings, lists), precise wording, or an admonition over visual emphasis. (Why: heavy emphasis reduces scan speed and harms raw‑Markdown readability.)

Bold

• Bold SHOULD mark scan points: a skimming reader should be able to bounce between bolded words and still understand the key actions or constraints in a section. (Why: using bold as a scan path keeps pages easy to scan.)
• Use bold for a few critical words in a heading or paragraph, not whole sentences. If the paragraph still communicates the same information when bold is removed, prefer plain text and drop the bold. (Why: unnecessary bold increases noise without adding meaning.)
• You MUST NOT bold entire sentences, paragraphs, or whole list items. If a label is needed, use a heading or an appropriate callout instead. (Why: large bold blocks create visual noise and duplicate heading semantics.) [HIGH]
• You MUST NOT use bold to style tokens, flags, filenames, or UI/log messages; use code font for tokens, quotation marks for log/error strings and UI text, and <kbd> for UI/menu labels and key names. (Why: consistent, literal styling keeps examples copy‑pasteable, searchable, and accessible.) [HIGH]
• Within a paragraph, you SHOULD NOT use more than one short bold span (≤ 3 words). Reserve it for rare emphasis that clarifies meaning, not for decoration. (Why: limiting emphasis keeps true highlights noticeable.)

Italics

• Italics MAY be used for first‑mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension.)
• When introducing an important concept on a concept or explanation page and a glossary link is not attached, you MAY italicize the first meaningful mention to signal definition, then stop italicizing later mentions. (Why: one highlighted introduction is enough to draw attention without cluttering the scan path.)
• Use italics for subtle emphasis that matters in sentence context but should not become a scan target. Use bold when the reader should find a word while scanning quickly. (Why: separating roles for bold and italics keeps both predictable.)
• Link text MUST NOT be styled with bold or italics. Do not wrap links in emphasis (for example, **[Foo](/foo)**, _ [Foo](/foo)_) and do not put bold or italic markup inside the link label. When the link label is a code identifier, use inline code as the label (for example, [`foo_bar`](/ref/foo_bar)). (Why: links are already visually distinct; extra emphasis adds noise and makes scanning harder.) [HIGH]

​

6.3 Code styling

• Code, filenames, paths, API endpoints, flags, and literals MUST use code formatting (inline backticks or fenced blocks). MUST NOT add punctuation inside code that isn’t part of the code. (Why: visual separation prevents misreading and keeps examples copy‑pasteable without edits.) [HIGH]

​

6.4 Lists

• Use numbered lists for procedures and bulleted lists for unordered sets. If list items are full sentences, SHOULD end with periods; otherwise, omit terminal punctuation consistently. (Why: matching list type to purpose improves comprehension; consistent punctuation keeps visual noise low.)
• Unordered list markers MUST be - (hyphen). MUST NOT use * or +. (Why: a single marker keeps diffs cleaner and avoids mixed styles.)
• Ordered lists MUST use 1. for every item; let the MDX parser auto‑number in the rendered output. (Why: auto‑numbering prevents renumber churn when inserting/reordering steps.)

​

6.5 Thematic breaks

• Thematic breaks / horizontal rules (---, ***, ___, or HTML <hr>) MUST NOT be used. Use headings, whitespace, or an admonition to separate sections. (Why: horizontal rules fragment structure, reduce screen‑reader/navigation cues, and add noise in raw Markdown.)
• You MUST NOT simulate separators with repeated characters or ASCII art (e.g., =====, -----). (Why: pseudo‑rules create the same problems and look like code noise.)
• This rule does not apply to YAML frontmatter delimiters --- at the top of a file. Frontmatter MAY use --- as required by the site generator. (Why: frontmatter is metadata, not content.)

​

6.6 Blockquotes

• Blockquotes MUST be reserved for literal quotations from a source (another page in these docs or an external source). Include attribution inline or in the sentence introducing the quote; internal quotes SHOULD link to the exact anchor; external quotes SHOULD link to the canonical HTTPS source. (Why: clear attribution preserves trust and lets readers verify context.)
• Blockquotes MUST NOT be used for callouts/admonitions, warnings, tips, examples, emphasis, or general instructions. Use the <Aside> component for callouts (see §11.2, Appendix A) and headings/lists for structure. (Why: misusing blockquotes harms structure, accessibility, and localization.)
• Visual callouts (Note/Tip/Caution/Warning) MUST use only the <Aside> component. The only supported type values are "note", "tip", "caution", and "danger"; do NOT use other components or type values. [HIGH] (Why: a single component and fixed types keep rendering, accessibility, and localization consistent.)
• Short phrases or UI/log strings SHOULD use inline quotation marks instead of a blockquote. Tokens and identifiers MUST use code font, not blockquotes. (Why: inline quotes and code font are more precise and copy‑friendly.)
• Keep quotations brief (prefer ≤ two sentences or one short paragraph). For longer material, summarize in your own words and link to the source. (Why: long quotes impede scanning and duplicate external content.)
• Nested blockquotes MUST NOT be used. Quoted code or output SHOULD appear in fenced code blocks with attribution above the block, not inside a blockquote. (Why: fenced blocks remain copy‑pasteable and render consistently.)

​

7. Headings and titles

​

7.1 Case and form

• Site‑managed H1. Pages MUST NOT include an in‑body H1. The page title is provided by the site generator/frontmatter. The first visible heading in the page content MUST be an H2. (Why: the template renders the title; omitting an in‑body H1 avoids duplicate titles and keeps a consistent heading hierarchy.)
• In MDX content, you MUST NOT write # (H1), <h1>, or use components that render an H1. Start headings at ## (H2). (Why: syntax‑level bans prevent accidental H1s in raw Markdown/MDX and keep navigation consistent.)
• Imported snippets/partials MUST NOT emit H1 headings; they MUST begin at H2 or lower within the host page’s hierarchy. (Why: embedded content inherits the page’s structure and must not reset the heading level.)
• All headings MUST use sentence case (capitalize only the first word and proper nouns). (Why: sentence case is easier to read, avoids random capitalization, and localizes more reliably.) [HIGH]
• Task (procedure) headings MUST start with an imperative verb; concept headings SHOULD be noun phrases. (Why: imperatives signal actions the reader takes; noun phrases signal explanatory content, improving navigation and search relevance.)
  • Task: “Deploy a validator.”
  • Concept: “Validator architecture.”
• How‑to titles. For the How‑to doc type, the page title MUST follow “How to X”. Internal section headings (H2/H3) remain imperative. (Why: the pattern clarifies page type and improves discoverability without changing procedural heading style.)

​

7.2 Gerunds and labels

• For task/procedure headings (H2/H3), gerunds (e.g., “Creating…”, “Configuring…”) SHOULD NOT be used. Prefer imperative verbs. (Why: gerunds are vague about action vs. state; imperatives are clearer and translate better.)
• Concept headings MAY use concise noun phrases (e.g., “Naming”, “Spelling”, “Versioning”). (Why: short labels act as clear section tags and improve scan speed.)
• Fixed labels like Troubleshooting, Changelog, or FAQ are acceptable. Imperatives read cleaner and translate better in procedural sections. (Why: common labels match user expectations and TOC patterns; imperatives keep steps actionable.)
• House default: use “Troubleshoot” by default; “Troubleshooting” is acceptable when aligning with established ecosystem conventions. (Why: one default reduces variance; allowing the alternate keeps external consistency where needed.)

​

7.3 Uniqueness and linkability

• Headings MUST be unique at the same nesting level within a page and MUST make sense out of context (as TOC/sidebar links). Avoid repeated “Introduction” sections; prefer specific names. (Why: unique, descriptive headings prevent anchor collisions and make links meaningful in search and sharing.)

​

7.4 Formatting restrictions

• Headings MUST NOT contain styling other than text: no bold, italics, code, quotes, or ALL CAPS (acronyms permitted). Keep headings clean; use formatting in body text only. (Why: extra styling harms scannability, clutters the TOC, and causes inconsistent rendering.)
• Exceptions:
  • Reference pages only: Headings MAY include code font for identifiers (API names, flags, error codes), e.g., tvm.runvm — interface and exit codes. (Why: monospaced identifiers preserve exact casing and aid search/copy.)
  • When the heading contains a literal UI/log/error message, quotation marks MAY be included (e.g., Fix “Account not found”). (Why: quoting exact strings shows what to grep or match without altering punctuation.)

​

7.5 Practical length norms

• Headings SHOULD be concise. As a norm, Page title (site/frontmatter) ≤ ~60 characters; H2/H3 ≤ ~70 characters. Exceed only for clarity. (Why: concise titles fit sidebars and search results without truncation; brevity improves scanning.)

• “Run a validator on testnet” (H2, imperative)
• “Account model and messages in TON” (H2, concept) Examples (bad):
• “Running and configuring the validator” (gerunds)
• “How the validator works” (code in heading)

​

8. Readability and scannability

​

8.1 Paragraphs and sentences

• One idea per paragraph. Paragraphs SHOULD be ≤ 5 sentences; single‑sentence paragraphs are acceptable for emphasis. These are recommended norms, not hard caps—exceed only when clarity requires it. (Why: tight, focused paragraphs are easier to scan; short norms keep pages consistent without blocking necessary detail.)
• Each sentence SHOULD convey one main idea. If a sentence starts to describe two distinct actions or conditions, split it into two sentences or convert the extra actions into a list. (Why: one‑idea sentences are easier to scan and translate; lists make multi‑step actions obvious.)
• Sentences SHOULD average 15–20 words. Long, multi‑clause sentences SHOULD be split. Front‑load key points. (Why: mid‑length sentences reduce cognitive load; splitting prevents misreads; leading with the main point speeds understanding.)

​

8.2 Structure for scanning

• Use subheadings, lists, and tables to break up dense text. Provide breathing room around code, tables, and images (blank lines before/after blocks). (Why: chunking and whitespace make structure visible and stop content from blending together.)
• Highlight critical notes with admonitions (Note/Tip/Important/Caution/Warning) sparingly so they retain impact. (Why: overuse causes readers to ignore callouts; sparing use signals importance.)
• This guidance does not limit required safety callouts in §11; when in doubt, include the safety callout. (Why: preventing harm overrides brevity and visual economy.)

​

8.3 Micro‑examples

• Verify fees before deploying.
• If the transaction fails with FEE_TOO_LOW:
  1. Update the fee policy.
  2. Retry the deployment.
• The node logs a warning on failure.

​

9. Recommended page structures (by type)

​

9.1 Step by step (first success)

• Objective: “Deploy a counter contract on testnet.”
• Prerequisites: Node.js 20+, TON SDK JS, funded testnet wallet, <RPC_URL>.
• Steps: 1) Initialize project … 2) Compile … 3) Deploy …
• Verify: “Expected output” block showing successful deployment.
• Troubleshoot: INSUFFICIENT_FUNDS, INVALID_WORKCHAIN fixes.
• Next steps: Link to contract upgrades guide.

​

9.2 How‑to guides (goal‑oriented procedures)

​

9.3 Explanations (concepts/why)

​

9.4 Reference (complete, factual)

​

10. Code and command examples

​

10.1 General rules

• Examples MUST be copy‑pasteable. MUST NOT include shell prompts ($, >) in command blocks. (Why: prompts get copied accidentally and break commands.) [HIGH]
• Command and expected output MUST be presented as separate fenced blocks. (Why: mixing them causes copy errors and makes results hard to recognize.) [HIGH]
• Placeholders MUST use <ANGLE_CASE> (e.g., <RPC_URL>, <LEDGER_DIR>), and each placeholder MUST be defined on first use. (Why: a consistent, visible pattern prevents pasting unsafe hard‑coded values.) [HIGH]
• Fenced code blocks MUST specify a language (```bash, ```rust, ```json, …). (Why: language tags enable correct highlighting and tooling.)
• Filenames shown in examples MUST be realistic and kebab‑case (e.g., wallet-config.json, not MyConfig.json). (Why: examples should model the conventions we require elsewhere.)
• Long commands MUST NOT be hard‑wrapped. Prefer UI soft wrap. If a tool supports safe line continuation (e.g., \ in POSIX shells), continuation MAY be used and must be copy‑pasteable as shown. (Why: hard wraps break execution; soft wrap or continuations keep commands runnable.)
• You SHOULD favor examples that run end‑to‑end on testnet by default. (Why: safer defaults reduce risk and support quick validation.)
• Inside language code, placeholders SHOULD be neutral (e.g., UPPER_SNAKE inside strings or comments) when angle brackets would clash with language syntax; in commands and prose, placeholders MUST use <ANGLE_CASE>. (Why: avoids syntax errors in code while keeping a single placeholder style in prose/CLI.)
• In runnable examples, configuration values and other parameters that the reader is expected to change MUST be collected in one clearly visible block near the top of the snippet. When the language allows top‑level declarations, this block MUST use top‑level constants instead of redefining values inside the entry function or helpers; when the language forbids top‑level declarations, group these parameters at the start of the entry function. (Why: collecting adjustable values in one visible place makes examples easier to understand and update.) [HIGH]

​

Error and log style

• Quoted UI/log messages MUST appear verbatim in quotation marks. (Why: exact strings are searchable and prevent confusion.)
• Error codes and identifiers MUST be rendered in code font (e.g., ERR_FEE_TOO_LOW). (Why: monospace distinguishes tokens and aids copy/paste.)
• When summarizing behavior instead of quoting, MUST NOT change semantics and avoid using quotes; indicate that it is a summary. (Why: paraphrases should not be mistaken for literal messages and must stay accurate.)

ton-node start --ledger <LEDGER_DIR> --network testnet

Node started. Workchain: 0  Shard: -1  Status: running

$ ton-node start --ledger /home/bob/ledger --network mainnet  # includes prompt, hard-coded values

​

10.2 Partial snippets

• Partial snippets (focused excerpts) MAY be used when teaching a narrow concept, even if not runnable alone. (Why: small, targeted examples clarify one idea without setup noise.)
• Partial snippets MUST be labeled clearly above the block: “Not runnable”. (Why: prevents readers from attempting to execute incomplete code.)
• Partial snippets SHOULD link to a full runnable example or reference entry showing complete context. (Why: gives readers a path to working code.)

let to = Address::from_str("EQC_REPLACE_WITH_ADDRESS").unwrap();
let amount = Coins::from_nano(1_000_000_000);
let body = build_transfer_body(to, amount);

​

10.3 Safety and secrets in code

• Secrets (keys, mnemonics, API tokens) MUST NOT appear in examples. Use placeholders or test keys that are clearly invalid. (Why: prevents accidental leaks and unsafe copying.) [HIGH]
• Commands that could cause loss of funds or data MUST be guarded by a Warning/Caution per §11 and SHOULD default to testnet. (Why: explicit risk labeling and safe defaults protect readers.) [HIGH]

​

10.4 OS and language variants

• When steps differ by OS or language, you SHOULD provide tabs or distinct subsections (e.g., Linux / macOS / Windows; JS / Python / Rust). (Why: separates platform differences so readers don’t mix instructions.)
• If only one variant is provided, the page MUST state that limitation. (Why: sets expectations and avoids readers searching for missing variants.)

​

10.5 Comments and omissions

• Use language‑appropriate comments to mark omissions (// …); MUST NOT use literal ellipses that change syntax. (Why: literal ellipses can create invalid code.) [HIGH]
• Explanatory comments in examples MUST appear on their own line immediately above the code they describe; MUST NOT use trailing end‑of‑line comments such as foo(42); // sends a test message in documentation snippets. (Why: stacked comment‑then‑code is easier to scan and keeps copy‑pasted lines clean.) [HIGH]
• Exception: Fift and TVM assembly stack comments MAY appear as trailing end‑of‑line comments to show the stack state at that point (e.g., 1 2 + // 3). This is idiomatic in stack‑based languages and aids comprehension. (Why: stack comments are a well‑established convention in Fift and TVM assembly; forcing them to a separate line would harm readability.)
• Keep comments minimal and instructional; avoid commentary or humor. (Why: extraneous remarks distract from the task and age poorly.)

​

11. Safety‑critical content (blockchain‑specific)

​

11.1 When a safety callout is required

• moves funds or changes fee/withdrawal behavior; (Why: users can lose money or block withdrawals.) [HIGH]
• exposes, stores, or transmits private keys/mnemonics; (Why: leaked secrets allow account takeover and theft.) [HIGH]
• modifies validator configuration, networking, or consensus‑affecting parameters; (Why: misconfiguration can halt or fork nodes and degrade the network.) [HIGH]
• performs chain‑affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) [HIGH]

​

11.2 How to write the callout

1. Risk (what can go wrong), (Why: sets severity and helps decide whether to proceed.)
2. Scope (what the command affects), (Why: clarifies blast radius—single node, wallet, or network.)
3. Rollback/mitigation steps where feasible, and (Why: gives a path to recovery or damage control.)
4. Environment label (testnet vs mainnet) with safer default instructions first. (Why: testnet reduces harm; explicit labels prevent accidental mainnet use.)

• These elements describe the information the reader needs; they are NOT required as literal labels such as “Risk:” or “Scope:”. Safety callouts SHOULD read as concise, natural prose rather than templated checklists. (Why: natural language is easier to read and avoids robotic, placeholder‑style warnings.)

• Page‑level safety summary. Place a single <Aside> near the top of the guide that describes overall risk, scope, rollback/mitigation strategy, and testnet/mainnet expectations for the full set of commands. (Why: one visible summary prevents readers from missing critical context.)
• Local step‑level warnings. Add short <Aside> elements next to each hazardous step that call out the specific risk or environment for that step and, when needed, refer back to the page‑level summary instead of repeating full details (for example, “See the safety note at the top of this page before running this on mainnet.”). (Why: local notes tie the warning to the exact action without duplicating the whole summary.)

• Safety callouts MUST use the <Aside> component; MUST NOT use Markdown blockquotes (>) or headings to simulate warnings. (Why: a single component keeps appearance, accessibility, and behavior consistent.)
• Mapping: use type="caution" for Caution; use type="danger" for Warning. Set an explicit title when needed (e.g., title="Funds at risk"). (Why: consistent severity mapping aligns wording with visual severity.)
• Allowed types: The only supported <Aside> type values are "note", "tip", "caution", and "danger". Do not use other values (e.g., "important", "warning"). To display those labels, set title (e.g., title="Important") while keeping a supported type. (Why: keeping to the supported set ensures consistent rendering and avoids runtime fallbacks.)

import { Aside } from '/snippets/aside.jsx';

<Aside type="danger" title="Funds at risk">
  Sending TON on mainnet is irreversible. Start with a small transfer on TON Testnet, then repeat on TON Mainnet only after checking the address and network carefully; there is no rollback on mainnet.

  ```bash
  jetton transfer --to <ADDR> --amount <AMOUNT> --network testnet
  ```
</Aside>

​

11.3 Safer defaults

• Task pages SHOULD use testnet endpoints by default and mention the switch to mainnet explicitly. (Why: safe defaults prevent costly mistakes.)
• Destructive flags (e.g., --purge, --force) MUST be opt‑in and accompanied by a callout. (Why: explicit opt‑in and warnings reduce accidental data loss.) [HIGH]

​

11.4 Key handling and storage

• Keys MUST be represented as placeholders or generated ephemeral testing artifacts. (Why: prevents real secrets from being copied into scripts or screenshots.) [HIGH]
• In guides, prefer environment variables or keystores; never inline secrets. (Why: avoids persisting secrets in history, logs, or source control.) [HIGH]
• Reference pages MAY document secure storage options but MUST NOT encourage unsafe patterns. (Why: guidance is helpful, but normalizing bad practices leads to leaks.) [HIGH]

​

12. Links and cross‑references

​

12.1 Link text

• Link text MUST be descriptive and indicate the destination. You MUST NOT use generic labels like “click here”, “here”, “this”, “this link”, “this page”, or bare URLs as link text. [HIGH] (Why: meaningful text lets readers scan quickly to determine where a link leads; generic labels force readers to examine surrounding context.)
• You MUST NOT use mechanics‑focused verbs like “click”, “tap”, “follow”, or “go to” as part of link text. Focus on content, not interaction mechanics. [HIGH] (Why: drawing attention to the clicking action distracts from the content; not all users click — some tap, use keyboards, or use assistive technology.)
• Link text SHOULD describe the destination, not the action of navigating. One effective technique: use the title or topic of the target page as the link text and integrate it into the sentence.
  • Bad: "To learn about fees, click [here](/fees)."
  • Bad: "Click [here](/fees) for fee information."
  • Bad: "[This page](/fees) explains fees."
  • Good: "The [fee structure](/fees) determines transaction costs."
  • Good: "Transaction costs depend on the [fee structure](/fees)."
• When a link must stand alone (e.g., at the end of a sentence or after a colon), make the link text self‑explanatory:
  • Bad: "For more details, see [here](/validator-setup)."
  • Good: "For more details, see [Validator setup](/validator-setup)."
  • Good: "Related guide: [Set up a validator](/validator-setup)."
• Link labels SHOULD be plain text or inline code for identifiers (see §6.2 for emphasis restrictions on link text). (Why: unstyled labels keep links readable and avoid redundant visual emphasis.)
• Standalone “stub” sentences whose only job is to say “See …” or “Read here …” followed by a link (for example, [Read here](/standard/wallets/mnemonics) to learn more. or See [mnemonics](/standard/wallets/mnemonics) for more details.) MUST NOT appear in running prose. Instead, attach the link to the relevant term or phrase in a normal sentence (for example, The [mnemonics guide](/standard/wallets/mnemonics) explains why.). (Why: inline links keep the text flowing and avoid postponing useful links to trailing meta‑sentences.) [HIGH]
• Accessibility and SEO note: Screen readers often present links out of context (e.g., a list of all links on a page). Generic link text like “here” or “click here” becomes meaningless when read in isolation. Search engines also use link text to understand page relationships. Descriptive link text improves both accessibility and discoverability. (Why: links must make sense without surrounding prose.)

​

12.2 What to link (and what not)

• In a guide, the first useful mention of a flag, parameter, error code, or data type on the page MUST link to the canonical reference anchor. You MAY also link its first mention in other H2/H3 sections on long pages that are frequently deep‑linked or read out of order. (Why: readers see the spec at the moment they need it, even when entering mid‑page.) [HIGH]
• This rule explicitly includes TVM exit codes (e.g., -13, 37), send modes (e.g., mode 64, mode 128), reserve modes, and similar numeric constants that have documented meanings. These MUST be linked to their corresponding reference anchors on first mention, not left as bare code spans. (Why: numeric constants are opaque without context; links let readers understand them instantly.) [HIGH]
• Within a single H2/H3 section, link only the first meaningful mention of an important term or reference target. When the same term appears in a different H2/H3 section, you MAY link its first mention again there. Avoid linking every occurrence inside one section; add a repeated link only when separated by many screens and it clearly helps the reader. (Why: per‑section first links help when deep‑linking to a subsection without turning the page into a link farm.)
• Link concepts judiciously: if the reader is likely to wonder “what does that mean?”, link the term on its first useful mention in that H2/H3 section. Subsequent mentions in the same section SHOULD be plain text unless the gap is large and a repeated link clearly helps. (Why: section‑local first links help readers who land on a deep link without over‑linking common words.)
• On the first useful mention of a core TON term on a page, you SHOULD link to the Glossary (Foundations → Glossary), unless the page itself defines it. On long pages, you MAY also link the first mention of that term in other H2/H3 sections, following the per‑section rules above. (Why: keeps definitions consistent and easy to find while still helping readers who enter mid‑page.)
• Over‑linking common words is discouraged; link what is plausibly useful. (Why: excessive links slow reading and distract from the task.)
• Guides MUST NOT duplicate reference tables; summarize and link instead. (Why: duplication drifts and creates conflicting sources of truth.)
• Internal first. When both an internal TON Docs page and an external source exist, you MUST link the internal page by default (including instead of the TEPs repository). Exception: pages whose purpose is to document a standard contract/TEP MAY also link the corresponding TEP as the canonical spec. If no relevant internal page exists, linking to the external source is acceptable. (Why: internal pages are newcomer‑friendly; TEPs are normative but hard to parse for new readers.)

​

12.3 Link targets and format

• Internal links MUST be root‑absolute and stable (start with /); anchors MUST resolve correctly. MUST NOT use relative segments like ./ or ../ in Markdown/MDX link URLs or HTML/JSX. (Why: files and folders move frequently; root‑absolute links remain correct across moves; relative segments are brittle and costly to maintain.) [HIGH]
• Cross‑section links SHOULD deep‑link to the exact section or anchor instead of the page top. (Why: deep links land readers on the exact answer.)
• A See also section MAY close a page with 1–3 essential links; prefer a linear path that needs none. (Why: minimal exits keep readers on task while still offering critical follow‑ups.)
• When linking to the same internal target multiple times on a page, you SHOULD prefer reference‑style Markdown links so the URL appears once in a shared definition block. For example:
  Use the [jetton wallet][jetton-wallet] contract where applicable; the [jetton wallet reference][jetton-wallet] describes all fields.
  
  [jetton-wallet]: /standard/jettons/wallet
  
  This keeps body text readable and makes URL updates cheaper, while still requiring root‑absolute URLs in the reference definition. (Why: shared link definitions reduce visual noise and simplify maintenance.)

​

12.4 Avoid circularity and drift

• Each fact MUST have a single canonical home. If you need the same fact elsewhere, link to it. (Why: one source avoids conflicting copies and simplifies updates.)
• MUST NOT link to outdated or superseded pages except when documenting historical behavior. (Why: stale links propagate errors and erode trust.) [HIGH]

​

12.5 Images and media

• Images MUST be embedded using the <Image> MDX component. Markdown image syntax ![...](...) and raw <img ...> are PROHIBITED. (Why: the component provides dark‑theme control, consistent sizing/zoom, and stable rendering.) [HIGH]
• Image sources MUST be root‑absolute and live under /resources/images/ (for example, <Image src="/resources/images/<GROUP>/<FILE>.png" />, where <GROUP> is the logical image category and <FILE> is the filename). MUST NOT use relative src such as ./ or ../. (Why: content moves often; root‑absolute paths remain valid.) [HIGH]
• Provide a darkSrc when contrast or readability differs in dark mode. Keep aspect ratios consistent across a page to avoid layout shift. (Why: visual stability improves reading flow.)
• SVG note: if src points to an SVG and darkSrc is omitted, the dark‑theme image is auto‑inverted. Supply an explicit darkSrc when inversion is not desired. (Why: ensures accurate colors and legibility.)
• Provide meaningful, non‑empty alt text for every image; alt MUST NOT be empty. (Why: screen readers rely on alt to convey image meaning; empty alt hides content from assistive tech.) [HIGH]
• When using <Image>, prefer the width/height props for predictable layout; avoid arbitrary inline styling. (Why: predictable dimensions prevent layout shift and maintain consistency.)

​

12.6 External references

• Authority order. You MUST prefer: (1) official project documentation/specs/standards (link internal TON Docs when available before external repos); (2) vendor documentation for tools used; (3) primary sources (RFCs, papers). Community wikis/blogs MAY be linked only when no official source exists and MUST be labeled as background. (Why: authoritative sources change less and carry clearer guarantees; internal docs are optimized for comprehension.)
• Wikipedia and crowd‑edited sources. Wikipedia MAY be linked for general, well‑known non‑TON concepts when the link is informational and not supporting a requirement or API/behavior semantics. For normative claims or when precision matters, MUST link a spec or official docs (e.g., RFC 8032 for Ed25519). (Why: Wikipedia is useful for broad context; specs are stable for requirements.)
• Q/A forums and social posts. Stack Overflow, Reddit, and personal blogs MUST NOT be used as normative references. They MAY appear as background in the Explanation pages when no official source exists. (Why: anecdotal content is volatile and easily outdated.)
• TEPs specifics. Prefer the internal TON Docs page that explains a standard over linking directly to the TEPs repository. On pages that are themselves standards or reference docs (e.g., standard contracts), you MAY include a precise deep link to the corresponding TEP as the canonical spec. Avoid linking the repository root; link the exact TEP and section. (Why: TEPs are normative but difficult for newcomers; internal docs provide context while still letting experts reach the spec.)
• Stable permalinks (situation‑aware). When linking to specific code/files/lines or exact doc sections where content must remain reproducible, you SHOULD use a versioned or permanent URL (e.g., GitHub tag/commit permalink; versioned docs; DOI). If a versioned URL exists and the reference is normative or precision‑critical, you MUST NOT link to moving targets like “main”, “HEAD”, or “latest”. For general project references (homepage or repo root), you MAY use the canonical current URL. (Why: permalinks keep exact references stable; simple links are fine when versioning adds no value.) [HIGH]
• Deep links. You SHOULD link to the exact section/anchor that holds the needed fact, not the page top. (Why: deep links land readers on the answer and reduce scanning.)
• Clean URLs. Links MUST use HTTPS, MUST NOT include shorteners or tracking parameters (e.g., utm_*), and MUST NOT point to unofficial mirrors/gists when an official location exists. (Why: clean, canonical URLs are trustworthy and durable.) [HIGH]
• Language and availability. Link to the English source by default. If the authoritative page is non‑English, MUST label the link with the language (e.g., “(in Russian)”). Avoid paywalled sources as primary; if unavoidable, SHOULD provide an open alternative or summarize key facts locally. (Why: sets expectations and preserves access.)

​

13. Terminology and naming

​

13.1 Term bank (canonical source)

• A project term bank MUST define canonical terms, spellings, hyphenation, casing, and banned variants with replacements (e.g., allowlist/denylist for whitelist/blacklist). (Why: clear entries stop ad‑hoc wording and mixed casing from spreading.)
• You MUST consult the term bank before introducing new names; additions SHOULD be reviewed by editors. (Why: gatekeeping new terms prevents drift and conflicting synonyms.)
• The term bank SHOULD mark which terms are link‑worthy for first‑use cross‑links and record their canonical doc URLs. First‑use linking rules in §12.2 SHOULD apply only to terms above this importance threshold to avoid over‑linking minor notions. (Why: a curated set of link‑worthy terms keeps pages readable while still making key concepts discoverable.)
• Flags, parameters, error codes, and data types documented in guides MUST be included in this link‑worthy set so first‑use links in §12.2 always have a canonical target. This includes TVM exit codes, send modes, reserve modes, and other numeric constants with documented semantics. (Why: treating these technical items as link‑worthy ensures readers can jump straight to their reference definitions.) [HIGH]

​

13.2 General casing rules

• Generic concepts MUST NOT be capitalized mid‑sentence (use “smart contract,” not “Smart Contract”). (Why: random caps imply proper nouns and slow reading.) [HIGH]
• Proper nouns and official product/feature names MUST follow the term bank (e.g., TON, TON Connect). (Why: consistent branding and accurate references.)
• Code identifiers (types, fields, flags) MUST appear in code font with exact case. (Why: preserves copy/paste fidelity and distinguishes code from prose.) [HIGH]

​

13.3 Hyphenation and abbreviations

• Multi‑word mechanism names are common nouns and SHOULD be hyphenated: proof‑of‑stake, zero‑knowledge. (Why: hyphenation clarifies compounds and matches industry norms.)
• Abbreviated forms MUST follow the project style: ZK‑proof, ZK‑rollup (uppercase ZK, hyphenated compound). (Why: consistent abbreviation improves recognition and search.)
• Use mainnet as a common noun; use TON Mainnet when referring to the proper name of the network. (Declare this explicitly in the term bank.) (Why: distinguishes generic network type from the named network.)
• Use testnet as a common noun; use TON Testnet when referring to the proper name of the network. (Why: same distinction as mainnet; avoids mixed casing.)

​

13.4 TON‑specific examples

• TON, TON Blockchain, TON Ecosystem (proper nouns).
• smart contract, wallet, account, message, jetton, nominator, validator, collator, node, liteserver (common nouns, lowercase mid‑sentence).
• accountchain, shardchain, workchain, masterchain, basechain — common nouns; use lowercase mid‑sentence. MUST NOT use CamelCase forms (ShardChain, WorkChain, MasterChain, BaseChain, AccountChain) or spaced variants (e.g., “Shard Chain”).
• BoC (abbrev.) / bag of cells (common noun). Abbreviation MUST be “BoC” (not “BOC”). Note: Do NOT introduce “master/slave” metaphors in new text; use primary/replica or similar. (Why: maintains inclusive language.)

​

13.5 Placeholder names

• In commands and prose, placeholders MUST be <ANGLE_CASE> with descriptive names: <WALLET_ADDR>, <AMOUNT_TON>, <RPC_URL>. (Why: a single, visible pattern reduces copy/paste mistakes.)
• In programming‑language code, placeholders MAY use UPPER_SNAKE without angle brackets when < > would clash with syntax (see §10.1). (Why: avoids syntax errors while keeping placeholders obvious.)
• MUST NOT use {curly} or [square] placeholder syntax in copy‑pasteable commands, as they are easy to misread as literal characters. (Why: braces/brackets are often treated as literals by shells and new users.) [HIGH]

​

13.6 Banned and preferred terms

• Banned (inclusive/biased): whitelist/blacklist; master/slave; sanity check. [HIGH]
• Banned (filler/tone): simply, just, obviously, clearly, please note.
• Preferred: (omit filler); allowlist/denylist; primary/replica; smoke check or basic check. Rationale: clarity, inclusivity, and reduced ambiguity.

​

14. Numbers, units, date, and time

​

14.1 Numerals and separators

• You MUST use numerals for all technical quantities (latency, memory, fees, block heights, versions, ports), regardless of size. (Why: digits are faster to scan and less ambiguous than words in technical contexts.)
  • Good: “Set the fee to 0.2 TON.”
• For general prose without units, you MAY spell out zero–nine and use numerals for 10+, but prefer numerals whenever a value matters to a task. (Why: numbers highlight actionable values and make comparisons obvious.)
• You SHOULD use thousands separators for numbers ≥ 10,000: 10,000, 1,234,567. (Why: separators improve readability and reduce digit‑counting mistakes.)
• MUST NOT add separators to codes/IDs (e.g., block hashes, transaction IDs, addresses), even if they contain digits; keep copyable values intact. (Why: added punctuation breaks copy/paste and changes identifiers.) [HIGH]
• Decimal separator MUST be a dot: 3.1415. (Why: a single convention avoids comma/dot confusion across locales and matches most APIs.)

​

14.2 Units and conventions

• Use binary units (KiB, MiB, GiB) for memory/storage sizes and SI units (kB, MB, Gbps, ms) for network throughput, latency, and timing. Be consistent within each category. (Why: binary vs SI units have different meanings; consistency prevents 2× errors.)
• Currency amounts MUST specify the unit (e.g., TON, USDT). When precision matters, show decimals explicitly (e.g., 0.000001 TON). (Why: omitting units or precision leads to costly misinterpretation.) [HIGH]
• Address/hash values MUST NOT be silently truncated. If truncation aids readability, use a consistent truncation pattern (e.g., first 4 / last 4 with an ellipsis: EQC…9gA) and state clearly that the value is truncated. (Why: silent truncation causes copy/paste failures and verification mistakes.) [HIGH]

​

14.3 Dates and times

• Dates MUST use ISO‑8601 format YYYY‑MM‑DD (e.g., 2025‑02‑11). (Why: ISO is unambiguous and sorts correctly.)
• Times SHOULD be 24‑hour and, where relevant, UTC (e.g., 14:30 UTC). (Why: avoids AM/PM ambiguity and timezone drift.)
  • Use UTC for timestamps that might be compared across regions (e.g., transactions, block times, cron examples). (Why: a single timezone ensures consistent ordering and comparison.)
• Ranges MUST be explicit: 2025‑02‑11 14:30–15:00 UTC. (Why: clear start/end with timezone prevents misaligned windows.)
• MUST NOT use ambiguous forms like 11/2/2025. (Why: day/month order varies by locale and leads to errors.)
• Changelogs SHOULD include a date stamp in ISO format. (Why: stable, sortable dates aid release tracking.)

​

14.4 Magnitudes and math

• Prefer engineering prefixes for readability: 1.2 GiB, 250 ms, 500 kB/s. (Why: normalized units make scale comparisons quick and reduce cognitive load.)
• Inline math SHOULD use KaTeX/LaTeX components when formulas help clarity. (Why: consistent rendering and accessibility across themes and locales.)

​

15. Accessibility and internationalization

​

15.1 Language and reading

• Content MUST use plain, international English; avoid idioms, slang, and culture‑specific metaphors. (Why: idioms and slang do not translate well and confuse global readers.)
• Link text and headings MUST be descriptive (screen‑reader friendly). Avoid “click here” (see §12). (Why: descriptive text improves scanning and is meaningful when read aloud by assistive tech.)
• Avoid gendered or ableist terms; use inclusive alternatives (see Appendix B). (Why: inclusive language prevents exclusion and avoids unnecessary friction.)

​

15.2 Structure and tables

• Tables SHOULD include header rows; keep cell content short and scannable. (Why: headers provide context for readers and screen readers; brief cells are easier to parse.)
• Units MUST be shown in headers or cells (e.g., “Latency (ms)”, “Size — MiB”). (Why: explicit units prevent misinterpretation of values.)
• Columns whose cells are primarily numeric values (for example, counts, sizes, fees, percentages, timings) MUST be right‑aligned so digits line up vertically. (Why: aligned digits make numeric comparisons easier and reduce misreads.) [HIGH]
• Columns whose cells contain identifiers such as addresses, hashes, transaction IDs, or error codes are not numeric columns and MAY remain left‑aligned. (Why: identifier strings are scanned, copied, and compared differently than numeric quantities.)
• Cells SHOULD NOT contain multi‑paragraph text; move extended explanations below the table. (Why: long prose in tables is hard to read and harms accessibility/layout.)
• Long lists inside cells SHOULD be converted to bullet lists placed below the table. (Why: lists outside tables are easier to scan and navigate.)
• Provide text alternatives for complex figures when feasible. (Why: alt or adjacent text lets screen‑reader users and translators access the content.)
• Keyboard‑only navigation SHOULD be considered when adding interactive elements. (Why: some users cannot use a mouse; keyboard support is a basic accessibility need.)
• Emojis MAY appear in compact tables as secondary indicators only when they follow a widely understood convention (e.g., ✅ Supported, ❌ Not supported) and are paired with clear text in the same cell. MUST NOT rely on emojis alone to encode meaning or status, and MUST NOT use decorative pictograms or one‑off icons that do not have a clear, conventional meaning. (Why: paired, conventional indicators remain accessible and understandable when emojis do not render or in translation.)

​

15.3 Localization readiness

• Prefer stable terminology from the term bank (Appendix B references) to minimize translation drift. (Why: consistent terms reduce rework and inconsistent translations.)
• Dates/times already follow ISO conventions (see §14.3), which SHOULD simplify localization. (Why: ISO formats are unambiguous across locales and require minimal adaptation.)

​

16. File, navigation, and frontmatter conventions

​

16.1 Sidebar groups and ordering

• The onboarding path SHOULD be a dedicated “Step by step” group near the top of the sidebar. Keep it linear and link out for depth. (Why: newcomers progress faster with one clear path.)
• Within every topical group (e.g., Ecosystem, Language reference, Standard contracts, TVM, Foundations, Smart‑contract patterns, Contribute; Integrate when present), pages MUST be ordered: Explanation → How‑to → Reference. (Why: readers scan “why” first, then “how”, then exact details.)
• The Explanation page SHOULD be the group’s overview (often overview.mdx). Keep it conceptual and brief, and link to How‑to/Reference as needed. (Why: one conceptual entry frames the section and reduces duplication.)
• Reference pages MUST be the canonical source for flags/fields/errors/types. Guides MUST NOT duplicate tables; they SHOULD deep‑link to anchors. (Why: single source of truth stays accurate and reduces maintenance.)

​

16.2 Files and titles

• Filenames MUST use kebab‑case.md or kebab‑case.mdx (e.g., validator-setup.mdx). (Why: kebab‑case avoids case‑sensitivity bugs, reads well in URLs, and is easy to grep.) [HIGH]
• Filenames MUST NOT have uppercase characters, i.e. foo-bAR.mdx. [HIGH]
• Filenames MUST NOT have cyrillic characters, i.e. сhoice.mdx. [HIGH]

​

16.3 Navigation labels

• Sidebar and nav labels SHOULD be short (2–4 words), unique, and mirror in‑page headings. (Why: short, unique labels prevent truncation and speed scanning.)
• Sidebar labels MAY be concise aliases of the page title; they SHOULD preserve the title’s meaning even if wording is shortened. (Why: sidebars have less space; preserving meaning avoids confusion.)
• Child pages inside a sidebar group MUST NOT repeat the group name in sidebarTitle when that word adds no new meaning. Rely on the group label as context and choose a short, distinct label instead. (Why: avoiding redundant group nouns keeps nested labels concise and scannable.) [HIGH]
  • Example: in a group Addresses, prefer sidebarTitle: "Overview" or sidebarTitle: "Deriving" over sidebarTitle: "Addresses overview" or sidebarTitle: "Deriving addresses".
• Avoid duplicate “Introduction” labels—make them specific (e.g., “Intro to sharding”). (Why: generic labels create indistinguishable TOC items and weak deep links.)
• Frontmatter keys. Use only page metadata supported by Mintlify (see project docs) and noindex: true when a page must be excluded from search indexing. MUST NOT introduce custom frontmatter keys for internal taxonomy (e.g., doc_type, audience, custom status). Represent such information in the page content or navigation instead. (Why: unsupported keys add maintenance burden, break tooling, and confuse contributors.)
• Length cap. If the frontmatter title exceeds 30 characters, the page MUST set sidebarTitle, and the sidebarTitle MUST be ≤ 30 characters. If the title is ≤ 30 characters, sidebarTitle is OPTIONAL; when provided, it SHOULD be ≤ 30 characters. Prefer removing non‑essential words over truncation; labels MUST NOT end with ellipses; preserve meaning and proper‑noun/case accuracy. (Why: short, clear labels fit sidebars and remain scannable.) Example
  ---
  title: "How to troubleshoot validator connectivity issues on restrictive firewalls"
  sidebarTitle: "Validator connectivity"
  ---
  
• How‑to frontmatter pattern. How‑to pages MUST set title: "How to X" and MUST set sidebarTitle to either X or a shorter alias of X that relies on the sidebar group for context and does not repeat the group name needlessly, where X is the task phrased in sentence case. If X begins with a letter, capitalize its first character; preserve exact casing for proper nouns and code tokens inside X. (Why: consistent titles match “how to …” searches; concise sidebar labels aid scanning while avoiding redundant group nouns and keeping identifiers accurate.) [HIGH]
• Title vs sidebar semantics. The frontmatter title MUST be context‑free and self‑describing for search and deep links; the sidebarTitle SHOULD be concise and rely on the current navigation context. One‑word generic titles (e.g., “Overview”, “Introduction”) MUST NOT be used as title except on top‑level pages (/the-page) or when the page is a proper name/term (e.g., “Tonkeeper”, “TON Center”). In those cases, a one‑word title MAY be used. Otherwise, the title SHOULD replicate or expand the section/folder name (e.g., “Sharding overview”), and the sidebarTitle MAY be “Overview”. (Why: descriptive titles improve discoverability and stand alone; short sidebar labels read better in context.) Example
  ---
  title: "Sharding overview"
  sidebarTitle: "Overview"
  ---
  
  Example
  ---
  title: "How to get testnet Toncoin"
  sidebarTitle: "Get testnet Toncoin"
  ---
  

​

16.4 Links and anchors

• Internal links MUST be root‑absolute (start with /) and MUST NOT include ./ or ../; ensure anchors are stable. (Why: root‑absolute links survive file moves and changes to the information architecture; relative segments break during reorganizations.) [HIGH]
• Trailing slashes: Follow a single repo‑wide policy set by the site generator, and apply it consistently across all internal links. (Why: consistency prevents duplicate routes, cache misses, and SEO issues.)
• Cross‑section links SHOULD target specific anchors rather than page tops. (Why: deep links land readers directly on the needed detail.)

​

16.5 Status labels

• Pages and features MAY declare a status in content at the top of the page using an <Aside> with a clear title (e.g., title="Deprecated" or title="Experimental"). Do not introduce custom frontmatter keys for status. (Why: status is visible to readers and does not require unsupported metadata.)
• If deprecated, the page MUST include the replacement (link to successor) and the removal timeline (date or version) in the callout. You MAY set noindex: true in frontmatter to exclude the page from search when appropriate. (Why: clear migration guidance reduces breakage; de‑indexing avoids surfacing outdated pages.)
• If experimental, briefly state scope and limitations; link to the stable alternative when available. (Why: scope limits misuse and points to the dependable path.)
• Status labels (experimental/deprecated) are independent of safety callouts (see §11). Apply both when applicable. (Why: status communicates lifecycle; safety communicates risk—readers need both.)

​

16.6 Components used in content

• On normal documentation pages, SHOULD NOT use <Card> components; prefer headings, lists, and inline links for navigation and structure. (Why: cards add visual chrome that is rarely needed for comprehension.)
• Existing <Card> usages SHOULD be confined to top‑level index or overview pages where the card layout clearly improves navigation. Over time, simplify or remove cards that do not provide a clear navigation benefit. (Why: keeping cards to a few deliberate entry pages avoids fragmenting the visual style.)
• When an index‑style page genuinely needs card‑like tiles, you MAY use <Card>; keep the content inside each card minimal and avoid duplicating information from the linked pages. (Why: cards should support navigation, not introduce a second layer of prose.)
• More generally, follow the “minimal styling” workflow from §6.2: components such as <Card>, <Aside>, <Image>, or tab containers SHOULD appear only when they improve comprehension or navigation, not as decoration. (Why: reduced decorative chrome makes structure and behavior stand out.)

​

17. Content hygiene and timeless writing

​

17.1 Single source of truth

• Each fact MUST have a canonical home. If you need the same fact elsewhere, link to it (see §12). (Why: one source prevents contradictions and simplifies updates.)
• Guides MUST NOT replicate reference tables; summarize and link. (Why: duplicated tables drift and become incorrect.)

​

17.2 Timelessness

• You SHOULD NOT use words like “currently”, “new”, or “soon”. (Why: time‑relative words stale quickly and lose meaning.)
• Prefer durable phrasing: “Since v2.3, X is supported,” not “newly added.” (Why: version‑based phrasing stays accurate over time.)
• Remove version qualifiers once they’re no longer useful. (Why: eliminates outdated noise and keeps prose evergreen.)

​

17.3 Freshness and updates

• When behavior changes, the relevant pages MUST be updated promptly. (Why: outdated steps cause failures and support load.)
• Large refactors SHOULD include redirects and update cross‑links. (Why: preserves deep links and prevents 404s.)
• Avoid re‑documenting external tools; link to official docs and focus on TON‑specific usage. (Why: external details change often; linking reduces churn.)

​

17.4 Proofread

• Read aloud or skim with a “scanner’s eye”; long sentences SHOULD be split (see §8). (Why: catches awkward phrasing and improves scannability.)
• Check terms against the term bank; enforce casing and spelling consistently. (Why: consistent terminology improves comprehension and search.)

​

18. Style exceptions and edge cases

• Any deviation from this guide MUST document: the rule being overridden, the reason, the scope (pages affected), the owner, and an expiry or review date. (Why: documentation, ownership, and a sunset make exceptions accountable and reversible.)
• Exceptions SHOULD be rare, time‑boxed, and revisited. (Why: scarcity prevents precedent; time limits force cleanup.)
• For audience‑critical reasons (e.g., highly advanced research notes), a page MAY relax sentence‑length norms (§8) or include extra theory in a how‑to (§3), but the page MUST clearly state the rationale at the top (e.g., Audience: Advanced). (Why: transparency lets readers self‑select and prevents surprise.)
• When quoting external code or configuration verbatim for legal or technical reasons, formatting MAY violate some house rules if changing it would misrepresent the original. Such cases SHOULD be rare and, for large or recurring examples, SHOULD be documented as style exceptions with scope and owner. (Why: fidelity to external sources sometimes takes priority over local formatting rules.)
• A safety requirement (§11) MUST NOT be waived. (Why: reader safety outweighs convenience.) [HIGH]

​

19. Appendices

​

A. Admonition levels and usage

• On pages with multiple hazardous actions, combine a page‑level safety <Aside> at the top (describing overall risk, scope, rollback/mitigation where feasible, and environment) with short local <Aside> elements near each dangerous step that can refer back to the summary instead of repeating it. (Why: the combination keeps risks visible without duplicating long warnings at every step.)

• Important — prerequisite “This guide requires a funded testnet wallet.”
• Caution — data loss “--purge-ledger removes local data. Back up <LEDGER_DIR> before running.”
• Warning — funds at risk “Transfers on mainnet are final.”
• Warning — page with many risky steps “Read the safety note at the top of this page before running any mainnet commands.”

​

B. Banned and preferred terms

• Banned: simply, just, obviously, clearly, please note, super‑, ASAP
• Use instead: omit or state the concrete action/effect

• Banned superlatives: blazingly fast, revolutionary, world‑class, seamless, best‑in‑class, powerful, cutting‑edge, game‑changing, next‑generation
• Banned vague adjectives (without measurable criteria): reliable, robust, essential, elegant, intuitive, flexible, comprehensive, scalable, efficient, optimal, superior
• Banned dramatic/emotional words: elusive, challenging (as drama), painful, frustrating, nightmare, perfectly, beautifully, amazing, incredible, stunning
• Banned intensity words: instantly (unless literal), immediately (unless literal), extremely, incredibly, massive, huge (for non‑quantified values)
• Banned storytelling openers: “Imagine…”, “Picture this…”, “Have you ever…”, “What if…”
• Use instead: measurable facts, specific numbers, concrete conditions, or omit entirely

• Banned: whitelist/blacklist → Preferred: allowlist/denylist
• Banned: master/slave → Preferred: primary/replica (or leader/follower, depending on context)
• Banned: sanity check → Preferred: basic check / smoke check
• Banned: dummy value → Preferred: sample value / placeholder
• Banned: crazy/insane → Preferred: unexpected / invalid

• Avoid: utilize → Use: use
• Avoid: prior to → Use: before
• Avoid: in order to → Use: to
• Avoid: leverage (as verb) → Use: use/apply
• Avoid: handle → Use: process/manage (be specific)

• Correct: TON, TON Mainnet; smart contract; bag of cells; BoC; accountchain, shardchain, workchain, masterchain, basechain; ZK‑proof, ZK‑rollup.
• Incorrect: Ton; ton mainnet; Smart Contract; BOC; ShardChain; Shard Chain; WorkChain.