Docs: Add Motoko.js, Embedded Motoko, Motoko formatter tools (#4537)

* Motoko tools docs

* Update embed-motoko.md

doc/md/base/_category_.yml

@@ -1,4 +1,4 @@
-position: 7
+position: 8
 label: 'Motoko base library'
 collapsible: true # make the category collapsible
 collapsed: true 

doc/md/migration-guides/_category_.yml

@@ -1,4 +1,4 @@
-position: 5
+position: 6
 label: 'Migration guides'
 collapsible: true # make the category collapsible
 collapsed: true 

doc/md/motoko-tools/_category_.yml

@@ -0,0 +1,4 @@
+position: 5
+label: 'Motoko tools'
+collapsible: true # make the category collapsible
+collapsed: true 

doc/md/motoko-tools/embed-motoko.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 1
+---
+
+# Embed Motoko
+
+## Overview
+
+The Embed Motoko tool enables Motoko smart contracts to be embedded in web pages such as a blog, web application, or even a Medium article. Simply insert your Motoko smart contract into the Embed Motoko tool and copy either the generated embedded URL or the HTML iframe to use in your web page.
+
+## Simple example
+
+Navigate to the [Embed Motoko web-based tool](https://embed.smartcontracts.org/).
+
+Insert your Motoko code into the web-based code editor. This example uses a simple 'Hello world!' example.
+
+![Embedded Motoko 1](./_attachments/embed-motoko-1.png)
+
+To get the embedded URL for this smart contract, click on the link icon in the top right corner:
+
+![Embedded Motoko 2](./_attachments/embed-motoko-2.png)
+
+The console output on the page will confirm that the embedded URL has been copied to your clipboard. The embedded URL will resemble the following:
+
+```
+https://embed.smartcontracts.org/motoko/g/RnWsYTzKuWEyzDDgFaFBJvYjkiAvqAQvqFBrkv4HLUUBkAQQSTWHz8NneJy4cRbJgS6NToPXdZxYo1YDGry7NDR9kYcFspuLMSNkXggQZMyB17YhUkMvYNp4HSF3Hoxewg4C8skNyaNhVhtifvKm3WypBcogAXJEccqQEAVz?lines=10
+```
+
+You can also get the HTML iframe code by clicking on the `</>` icon in the top right corner:
+
+![Embedded Motoko 1](./_attachments/embed-motoko-1.png)
+
+The console output on the page will confirm that the iframe code has been copied. The iframe will resemble the following:
+
+```
+<iframe src="https://embed.smartcontracts.org/motoko/g/RnWsYTzKuWEyzDDgFaFBJvYjkiAvqAQvqFBrkv4HLUUBkAQQSTWHz8NneJy4cRbJgS6NToPXdZxYo1YDGry7NDR9kYcFspuLMSNkXggQZMyB17YhUkMvYNp4HSF3Hoxewg4C8skNyaNhVhtifvKm3WypBcogAXJEccqQEAVz?lines=10" width="100%" height="360" style="border:0" title="Motoko code snippet" />
+```
+
+## Resources
+
+[Embed Motoko web-based tool](https://embed.smartcontracts.org/)
+
+
+

doc/md/motoko-tools/motoko-formatter.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 2
+---
+
+# Motoko formatting tools
+
+## Overview
+
+The Motoko Prettier plugin can be used to format and validate Motoko source code files. It can be used through the [Prettier CLI](https://prettier.io/docs/en/cli.html) or through VS Code.
+
+Alternatively, the Node.js package [`mo-fmt`](https://www.npmjs.com/package/mo-fmt) is a standalone Motoko formatter tool.
+
+## Motoko Prettier plugin
+
+### Installation
+
+To install the Motoko Prettier plugin, first download and install [Node.js](https://nodejs.org/en/download/).
+
+Then, create a new Motoko project or navigate into an existing project directory. [Learn more about creating a Motoko project](../getting-started/quickstart.md).
+
+Then, run the following command in the project directory:
+
+```sh
+npm install --save-dev prettier prettier-plugin-motoko
+```
+
+### Using the Prettier CLI
+
+You can format Motoko files through the Prettier CLI using the command:
+
+```sh
+npx prettier --write --plugin=prettier-plugin-motoko **/*.mo
+```
+
+To validate if your Motoko files are formatted properly, use the following command:
+
+```sh
+npx prettier --check --plugin=prettier-plugin-motoko **/*.mo
+```
+
+### Using VS Code
+
+The Motoko Prettier plugin works out of the box with the [Motoko extension for VS Code](https://marketplace.visualstudio.com/items?itemName=dfinity-foundation.vscode-motoko).
+
+It is also compatible with the the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
+
+### Ignoring code
+
+You can set code to be skipped from formatting or being validated by using a `prettier-ignore` comment:
+
+```motoko
+// prettier-ignore
+func ignored<A>(a:A){a};
+
+func formatted<B>(b : B) { b };
+```
+
+## `mo-fmt`
+
+### Installation
+
+To install `mo-fmt`, run the following command:
+
+```
+npm install mo-fmt
+```
+
+Then, format and validate the format of Motoko code files, run the commands:
+
+```
+mo-fmt **/*
+mo-fmt -c **/*
+```
+
+## References
+
+- [Motoko Prettier plugin GitHub repo](https://github.com/dfinity/prettier-plugin-motoko/)
+
+- [Motoko extension for VS Code](https://marketplace.visualstudio.com/items?itemName=dfinity-foundation.vscode-motoko)
+
+- [`mo-fmt`](https://www.npmjs.com/package/mo-fmt)

doc/md/motoko-tools/motoko-js.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 3
+---
+
+# Motoko.js
+
+## Overview
+
+The Motoko.js package can be used to compile and run Motoko smart contracts in a web browser or Node.js.
+
+## Installation
+
+To install the Motoko.js package, use `npm`:
+
+```
+npm i --save motoko
+```
+
+## Usage
+
+First, create a new Node.js project with the commands:
+
+```
+mkdir motoko-js-test
+cd motoko-js-test
+npm init
+```
+
+In the `package.json` file created by `npm init`, insert the following line:
+
+```
+  "type": "module",
+```
+
+Then, create and open an `index.js` file. In this new file, import the Motoko.js package into your source code file:
+
+```
+import mo from 'motoko';
+```
+
+Create a Motoko script using the Node.js virtual file system:
+
+```
+mo.write('Main.mo', `
+  actor Main {
+    public query func hello() : async Text {
+      "Hello, world!"
+    };
+  };
+`)
+console.log(mo.run('Main.mo'));
+```
+
+Next, add a final line to generate the corresponding Candid interface for the Motoko script:
+
+```
+console.log(mo.candid('Main.mo'));
+```
+
+Run this code with the command:
+
+```
+node index.js
+```
+
+The console will return the following output:
+
+```
+{
+  stdout: '`ys6dh-5cjiq-5dc` : actor {hello : shared query () -> async Text}\n',
+  stderr: '',
+  result: { error: null }
+}
+service : {
+  hello: () -> (text) query;
+}
+```
+
+
+## References
+
+- [npm documentation](https://www.npmjs.com/package/motoko)
+
+- [Load dependencies from GitHub](https://github.com/dfinity/node-motoko?tab=readme-ov-file#load-dependencies-from-github)
+
+- [Optimize for browsers](https://github.com/dfinity/node-motoko?tab=readme-ov-file#optimize-for-browsers)
+
+- [Top level API](https://github.com/dfinity/node-motoko?tab=readme-ov-file#top-level-api)
+
+- [File API](https://github.com/dfinity/node-motoko?tab=readme-ov-file#file-api)

doc/md/reference/_category_.yml

@@ -1,4 +1,4 @@
-position: 6
+position: 7
 label: 'References'
 collapsible: true # make the category collapsible
 collapsed: true