feat(docs): automatic links to Web IDE from code blocks in Cookbook

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docs: Added NFTs cookbook: PR [#958](https://github.com/tact-lang/tact/pull/958)
 - Ability to specify a compile-time method ID expression for getters: PR [#922](https://github.com/tact-lang/tact/pull/922) and PR [#932](https://github.com/tact-lang/tact/pull/932)
 - Destructuring of structs and messages: PR [#856](https://github.com/tact-lang/tact/pull/856)
+- Docs: automatic links to Web IDE from all code blocks: PR [#994](https://github.com/tact-lang/tact/pull/994)
 
 ### Changed
 

docs/astro.config.mjs

@@ -14,6 +14,9 @@ import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
 
+// Adds links to Web IDE from code blocks
+import remarkLinksToWebIDE from './links-to-web-ide';
+
 // Adds syntax highlighting for inline code blocks
 import rehypeInlineCodeHighlighting from './inline-code-highlighting';
 
@@ -26,7 +29,7 @@ export default defineConfig({
 	outDir: './dist', // default, just to be sure
 	site: 'https://docs.tact-lang.org',
 	markdown: {
-		remarkPlugins: [remarkHeadingId, remarkMath],
+		remarkPlugins: [remarkHeadingId, remarkMath, remarkLinksToWebIDE],
 		rehypePlugins: [
 			rehypeHeadingIds,
 			[rehypeAutolinkHeadings, {

docs/links-to-web-ide.js

@@ -0,0 +1,97 @@
+/**
+ * @import {Root} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import { visit } from 'unist-util-visit';
+
+/**
+ * Maximum allowed characters in a Chrome
+ * Firefox has more limit but we are using less for compatibility
+ */
+const maxAllowedCharacters = 32779;
+
+/**
+ * Adds links to every code block, allowing to open its contents in the Web IDE
+ *
+ * @returns Transform.
+ */
+export default function remarkLinksToWebIDE() {
+  /**
+   * @param tree {Root}
+   * @param file {VFile}
+   * @return {undefined}
+   */
+  return function(tree, file) {
+    // Specifying 'code' items guarantees non-inline code blocks
+    visit(tree, 'code', function(node, index, parent) {
+      // Only allow Tact code blocks
+      if (node.lang !== 'tact') { return undefined; }
+
+      // Only allow certain amount of characters
+      let src = node.value.trim();
+      if (src.length > maxAllowedCharacters) { return undefined; }
+
+      // Disallow single-line code blocks as they pose very little value and they're often represent function signatures in the Reference section
+      const lines = src.split('\n');
+      if (lines.length <= 1) { return undefined; }
+
+      // Only allow pages in the Cookbook
+      // NOTE: This limitation can be lifted in the future if there's popular demand
+      if (file.path.indexOf('docs/cookbook') === -1) { return undefined; }
+
+      // Detect module-level items
+      let hasModuleItems = false;
+      for (let i = 0; i < lines.length; i += 1) {
+        // Same regex as in scripts/check-cookbook-examples.js
+        const matchRes = lines[i].match(/^\s*(?:import|primitive|const|asm|fun|extends|mutates|virtual|override|inline|abstract|@name|@interface|contract|trait|struct|message)\b/);
+        // TODO: Unite the regexes when Tact 2.0 arrives (or if some new module-level item arrives, or via try/catch and re-using compiler's parser)
+
+        if (matchRes !== null) {
+          hasModuleItems = true;
+          break;
+        }
+      }
+
+      // Adjust the source code if the module-level items are NOT present
+      if (!hasModuleItems) {
+        src = [
+          'fun fromTactDocs() {',
+          lines.map(line => `    ${line}`).join('\n'),
+          '}',
+        ].join('\n');
+      }
+
+      // Encode to URL-friendly Base64
+      const encoded = Buffer.from(src).toString('base64url');
+
+      // Double-check the number of characters in the link
+      const link = `https://ide.ton.org?lang=tact&code=${encoded}`;
+      if (link.length > maxAllowedCharacters) { return undefined; }
+
+      /** @type import('mdast').Html */
+      const button = {
+        type: 'html',
+        value: [
+          // Constructing opening <a> tag
+          [
+            // Open the tag
+            '<a',
+            // Make links opened in new tab
+            'target="_blank"',
+            // Set styles
+            'class="web-ide-link"',
+            // Add hyperref with > to close the tag
+            `href="${link}">`,
+          ].join(' '),
+          // The text to click on
+          '<span class="web-ide-link-span">▶️ Open in Web IDE</span>',
+          // Closing </a> tag
+          '</a>',
+        ].join(''),
+      };
+
+      // Place the button after the code block
+      parent.children.splice(index + 1, 0, button);
+    });
+  }
+}

docs/package.json

@@ -14,14 +14,15 @@
     "lint:all": "yarn spell"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.3",
-    "@astrojs/markdown-remark": "^5.2.0",
-    "@astrojs/starlight": "^0.28.2",
-    "astro": "^4.16.1",
+    "@astrojs/check": "0.9.4",
+    "@astrojs/markdown-remark": "5.3.0",
+    "@astrojs/starlight": "0.28.4",
+    "astro": "4.16.7",
     "cspell": "^8.14.4",
     "hast-util-to-string": "^3.0.0",
     "rehype-autolink-headings": "7.1.0",
     "rehype-katex": "7.0.1",
+    "remark": "^15.0.1",
     "remark-custom-heading-id": "2.0.0",
     "remark-math": "6.0.0",
     "sharp": "^0.32.5",

docs/scripts/check-cookbook-examples.js

@@ -16,7 +16,6 @@ import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import {
   mkdtempSync,
-  mkdtemp,
   readFileSync,
   readdirSync,
   statSync,

docs/src/content/docs/book/message-mode.mdx

@@ -35,7 +35,7 @@ Alternatively, if you want to send the whole contract balance and destroy it imm
 Here's how the latter example would look in code:
 
 ```tact
-let to: Address = ...;
+let to: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     to: to,

docs/src/content/docs/book/send.mdx

@@ -46,7 +46,7 @@ send(SendParameters{
 Another example sends a message to the specified [`Address{:tact}`][p] with a `value` of $1$ TON and the `body` of a comment with a [`String{:tact}`][p] `"Hello, World!"{:tact}`:
 
 ```tact
-let recipient: Address = ...;
+let recipient: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     // bounce is set to true by default
@@ -64,7 +64,7 @@ The [optional flag](/book/message-mode#optional-flags) `SendIgnoreErrors{:tact}`
 To send a binary typed message you can use the following code:
 
 ```tact
-let recipient: Address = ...;
+let recipient: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     // bounce is set to true by default

docs/src/content/docs/ref/core-cells.mdx

@@ -22,7 +22,7 @@ import { Badge } from '@astrojs/starlight/components';
 ## beginCell
 
 ```tact
-fun beginCell(): Builder
+fun beginCell(): Builder;
 ```
 
 Creates a new empty [`Builder{:tact}`][builder].

docs/src/content/docs/ref/core-math.mdx

@@ -243,9 +243,9 @@ Returns `true{:tact}` if the signature is valid, `false{:tact}` otherwise.
 Usage example:
 
 ```tact
-let data: Slice = ...;
-let signature: Slice = ...;
-let publicKey: Int = ...;
+let data: Slice = some_data;
+let signature: Slice = some_signature;
+let publicKey: Int = 42;
 
 let check: Bool = checkSignature(data, signature, publicKey);
 ```

docs/src/starlight.custom.css

@@ -102,3 +102,34 @@ td>a>code {
 code:not(pre *) {
 	background-color: var(--sl-color-bg-inline-code) !important;
 }
+
+/* Stylizing <a> links to Web IDE */
+.web-ide-link {
+	display: flex;
+	justify-content: right;
+	text-decoration: none;
+	margin-top: 0.25rem;
+	margin-bottom: 1rem;
+}
+
+/* Stylizing <span> tags inside <a> links to Web IDE */
+.web-ide-link-span {
+	/* from .sl-badge */
+	display: inline-block;
+	border: 1px solid var(--sl-color-border-badge);
+	border-radius: 0.25rem;
+	font-family: var(--sl-font-system-mono);
+	line-height: normal;
+	color: var(--sl-color-text-badge);
+	background-color: var(--sl-color-bg-badge);
+	overflow-wrap: anywhere;
+
+	/* from .default */
+	--sl-color-bg-badge: var(--sl-badge-default-bg);
+	--sl-color-border-badge: var(--sl-badge-default-border);
+	--sl-color-text-badge: var(--sl-badge-default-text);
+
+	/* from .small */
+	font-size: var(--sl-text-xs);
+	padding: 0.125rem 0.25rem;
+}