Documentation for Tolk written from scratch

.cspell.jsonc

@@ -83,6 +83,20 @@
         "!2lw-deny-list", // turns off the dictionary
       ]
     },
+    {
+      "filename": "languages/tolk/features/compiler-optimizations.mdx",
+      "ignoreWords": [
+        "fifting",
+      ]
+    },
+    {
+      "filename": "languages/tolk/from-func/tolk-vs-func.mdx",
+      "ignoreWords": [
+        "transpiles",
+        "Hindley",
+        "Milner",
+      ]
+    },
     {
       "filename": "**/api/**/*.{json,yml,yaml}",
       "ignoreWords": [
@@ -110,6 +124,7 @@
     "foundations/whitepapers/ton.mdx",
     "foundations/whitepapers/tvm.mdx",
     "languages/fift/whitepaper.mdx",
+    "languages/tolk/features/standard-library.mdx",
     // Generated files
     "tvm/instructions.mdx",
     // Binaries

contract-dev/first-smart-contract.mdx

@@ -118,7 +118,7 @@ First, we need a way to store the counter value. Tolk makes this simple with <To
 
 ```tolk title="./contracts/first_contract.tolk"
 struct Storage {
-    counter: uint64; // the current counter value
+    counter: uint64  // the current counter value
 }
 
 // load contract data from persistent storage
@@ -153,17 +153,17 @@ Tolk structures are also useful for defining message bodies. In our case, we’l
 Each structure has a unique prefix (`0x7e8764ef` and `0x3a752f06`), widely called opcodes, that lets the contract distinguish between them.
 
 ```tolk title="./contracts/first_contract.tolk"
-struct(0x7e8764ef) IncreaseCounter {
+struct (0x7e8764ef) IncreaseCounter {
     increaseBy: uint32
 }
 
-struct(0x3a752f06) ResetCounter {}
+struct (0x3a752f06) ResetCounter {}
 ```
 
 To group them together, we'll use a union. Unions allow multiple types to be bundled into a single type that can be serialized and deserialized automatically:
 
 ```tolk title="./contracts/first_contract.tolk"
-type AllowedMessage = IncreaseCounter | ResetCounter;
+type AllowedMessage = IncreaseCounter | ResetCounter
 ```
 
 Now we can write our message handler:
@@ -227,7 +227,7 @@ Here’s the full source code of `contracts/first_contract.tolk`:
 
 ```tolk title="./contracts/first_contract.tolk" expandable
 struct Storage {
-    counter: uint64;
+    counter: uint64
 }
 
 fun Storage.load() {
@@ -238,13 +238,13 @@ fun Storage.save(self) {
     contract.setData(self.toCell());
 }
 
-struct(0x7e8764ef) IncreaseCounter {
+struct (0x7e8764ef) IncreaseCounter {
     increaseBy: uint32
 }
 
-struct(0x3a752f06) ResetCounter {}
+struct (0x3a752f06) ResetCounter {}
 
-type AllowedMessage = IncreaseCounter | ResetCounter;
+type AllowedMessage = IncreaseCounter | ResetCounter
 
 fun onInternalMessage(in: InMessage) {
     val msg = lazy AllowedMessage.fromSlice(in.body);
@@ -292,7 +292,7 @@ npx blueprint build FirstContract
 
 Expected output:
 
-```
+```ansi
 Build script running, compiling FirstContract
 🔧 Using tolk version 1.1.0...
 

docs.json

@@ -396,21 +396,71 @@
             "tag": "recommended",
             "pages": [
               "languages/tolk/overview",
+              "languages/tolk/basic-syntax",
+              "languages/tolk/idioms-conventions",
               {
-                "group": "From FunC",
+                "group": "Type system",
                 "pages": [
-                  "languages/tolk/from-func/in-short",
-                  "languages/tolk/from-func/in-detail",
-                  "languages/tolk/from-func/mutability",
-                  "languages/tolk/from-func/stdlib",
-                  "languages/tolk/from-func/create-message",
-                  "languages/tolk/from-func/lazy-loading",
-                  "languages/tolk/from-func/pack"
+                  "languages/tolk/types/list-of-types",
+                  "languages/tolk/types/numbers",
+                  "languages/tolk/types/booleans",
+                  "languages/tolk/types/address",
+                  "languages/tolk/types/cells",
+                  "languages/tolk/types/strings",
+                  "languages/tolk/types/structures",
+                  "languages/tolk/types/aliases",
+                  "languages/tolk/types/generics",
+                  "languages/tolk/types/enums",
+                  "languages/tolk/types/nullable",
+                  "languages/tolk/types/unions",
+                  "languages/tolk/types/tensors",
+                  "languages/tolk/types/tuples",
+                  "languages/tolk/types/maps",
+                  "languages/tolk/types/callables",
+                  "languages/tolk/types/void-never",
+                  "languages/tolk/types/type-checks-and-casts",
+                  "languages/tolk/types/overall-tvm-stack",
+                  "languages/tolk/types/overall-serialization"
+                ]
+              },
+              {
+                "group": "Syntax details",
+                "pages": [
+                  "languages/tolk/syntax/variables",
+                  "languages/tolk/syntax/conditions-loops",
+                  "languages/tolk/syntax/exceptions",
+                  "languages/tolk/syntax/functions-methods",
+                  "languages/tolk/syntax/structures-fields",
+                  "languages/tolk/syntax/pattern-matching",
+                  "languages/tolk/syntax/mutability",
+                  "languages/tolk/syntax/operators",
+                  "languages/tolk/syntax/imports"
+                ]
+              },
+              {
+                "group": "Language features",
+                "pages": [
+                  "languages/tolk/features/message-handling",
+                  "languages/tolk/features/contract-storage",
+                  "languages/tolk/features/contract-getters",
+                  "languages/tolk/features/message-sending",
+                  "languages/tolk/features/auto-serialization",
+                  "languages/tolk/features/lazy-loading",
+                  "languages/tolk/features/jetton-payload",
+                  "languages/tolk/features/standard-library",
+                  "languages/tolk/features/asm-functions",
+                  "languages/tolk/features/compiler-optimizations"
+                ]
+              },
+              {
+                "group": "Migrating from FunC",
+                "pages": [
+                  "languages/tolk/from-func/tolk-vs-func",
+                  "languages/tolk/from-func/tolk-vs-tlb",
+                  "languages/tolk/from-func/stdlib-fc",
+                  "languages/tolk/from-func/converter"
                 ]
               },
-              "languages/tolk/environment-setup",
-              "languages/tolk/counter-smart-contract",
-              "languages/tolk/language-guide",
               "languages/tolk/changelog"
             ]
           },
@@ -924,52 +974,52 @@
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/environment-setup",
-      "destination": "/languages/tolk/environment-setup",
+      "destination": "contract-dev/first-smart-contract",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/counter-smart-contract",
-      "destination": "languages/tolk/counter-smart-contract",
+      "destination": "contract-dev/first-smart-contract",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/language-guide",
-      "destination": "languages/tolk/language-guide",
+      "destination": "languages/tolk/basic-syntax",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short",
-      "destination": "/languages/tolk/from-func/in-short",
+      "destination": "/languages/tolk/from-func/tolk-vs-func",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail",
-      "destination": "/languages/tolk/from-func/in-detail",
+      "destination": "/languages/tolk/from-func/tolk-vs-func",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability",
-      "destination": "/languages/tolk/from-func/mutability",
+      "destination": "/languages/tolk/syntax/mutability",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib",
-      "destination": "/languages/tolk/from-func/stdlib",
+      "destination": "/languages/tolk/from-func/stdlib-fc",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/pack-to-from-cells",
-      "destination": "languages/tolk/from-func/pack",
+      "destination": "languages/tolk/features/auto-serialization",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/create-message",
-      "destination": "languages/tolk/from-func/create-message",
+      "destination": "languages/tolk/features/message-sending",
       "permanent": true
     },
     {
       "source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/lazy-loading",
-      "destination": "languages/tolk/from-func/lazy-loading",
+      "destination": "languages/tolk/features/lazy-loading",
       "permanent": true
     },
     {
@@ -3201,6 +3251,56 @@
       "source": "/participate/run-nodes/full-node",
       "destination": "/v3/guidelines/nodes/running-nodes/full-node",
       "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/in-short",
+      "destination": "/languages/tolk/from-func/tolk-vs-func",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/in-detail",
+      "destination": "/languages/tolk/from-func/tolk-vs-func",
+      "permanent": true
+      },
+    {
+      "source": "/languages/tolk/from-func/mutability",
+      "destination": "/languages/tolk/syntax/mutability",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/stdlib",
+      "destination": "/languages/tolk/from-func/stdlib-fc",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/create-message",
+      "destination": "/languages/tolk/features/message-sending",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/lazy-loading",
+      "destination": "/languages/tolk/features/lazy-loading",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/from-func/pack",
+      "destination": "/languages/tolk/features/auto-serialization",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/environment-setup",
+      "destination": "/languages/tolk/overview",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/counter-smart-contract",
+      "destination": "/languages/tolk/overview",
+      "permanent": true
+    },
+    {
+      "source": "/languages/tolk/language-guide",
+      "destination": "/languages/tolk/overview",
+      "permanent": true
     }
   ]
 }

extra.css

@@ -75,3 +75,56 @@ table {
 div[data-component-part="callout-content"]>.code-block:last-child {
   margin-bottom: 0;
 }
+
+/*
+  A temporary solution syntax highlighting of Tolk snippets: invoke Prism.js on a client-side.
+  See `snippets/tolk-highlight.jsx`.
+  @link https://github.com/ton-org/docs/issues/1473
+ */
+
+:root {
+  --tolk-token-comment: #808080;
+  --tolk-token-type-hint: #D500EC;
+  --tolk-token-keyword: #0000FF;
+  --tolk-token-struct: #007EA2;
+  --tolk-token-variable: #444444;
+  --tolk-token-attr-name: #808000;
+  --tolk-token-function: #A82D2D;
+  --tolk-token-number: #0B9000;
+  --tolk-token-string: #008000;
+  --tolk-token-string-bg: #FAF9EF;
+  --tolk-token-operator: #A0A000;
+  --tolk-token-punctuation: #808000;
+  --tolk-token-three-dots: #999999;
+}
+
+.token.comment      { color: var(--tolk-token-comment); font-style: italic; }
+.token.type-hint    { color: var(--tolk-token-type-hint); }
+.token.boolean      { color: var(--tolk-token-keyword); }
+.token.keyword      { color: var(--tolk-token-keyword); }
+.token.self         { color: var(--tolk-token-variable); font-weight: bold; }
+.token.attr-name    { color: var(--tolk-token-attr-name); }
+.token.function     { color: var(--tolk-token-function); }
+.token.number       { color: var(--tolk-token-number); }
+.token.string       { color: var(--tolk-token-string); background-color: var(--tolk-token-string-bg); }
+.token.operator     { color: var(--tolk-token-operator); }
+.token.punctuation  { color: var(--tolk-token-punctuation); }
+.token.three-dots   { color: var(--tolk-token-three-dots); }
+.token.struct       { color: var(--tolk-token-struct); }
+.token.variable     { color: var(--tolk-token-variable); }
+
+html.dark {
+  --tolk-token-comment: #808080;
+  --tolk-token-type-hint: #DF90F8;
+  --tolk-token-keyword: #D75F02;
+  --tolk-token-struct: #56C1FF;
+  --tolk-token-variable: #C5D2E0;
+  --tolk-token-attr-name: #808000;
+  --tolk-token-function: #F9B900;
+  --tolk-token-number: #33A033;
+  --tolk-token-string: #33A033;
+  --tolk-token-string-bg: #1B1C1E;
+  --tolk-token-operator: #A0A000;
+  --tolk-token-punctuation: #85B2A0;
+  --tolk-token-three-dots: #777777;
+}