docs: troubleshooting, clarifications and wget tab installer

Co-authored-by: Tasos Bitsios <[email protected]>

docs/astro.config.mjs

@@ -2,6 +2,7 @@
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import tailwind from "@astrojs/tailwind";
+import mdx from '@astrojs/mdx';
 
 // https://astro.build/config
 export default defineConfig({
@@ -37,6 +38,7 @@ export default defineConfig({
       },
       customCss: ["./src/tailwind.css"],
     }),
+    mdx(),
     tailwind({ applyBaseStyles: true }),
   ],
 });

docs/ec.config.mjs

@@ -1,10 +1,9 @@
-import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
 import mocha from '@catppuccin/vscode/themes/mocha.json' with {type: 'json'}
 import latte from '@catppuccin/vscode/themes/latte.json' with {type: 'json'}
 import fs from 'node:fs';
 
 /** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */
 export default {
-  plugins: [pluginLineNumbers()],
+  plugins: [],
   themes: [latte, mocha],
 };

docs/package.json

@@ -9,15 +9,14 @@
     "preview": "astro preview",
     "astro": "astro"
   },
-  "engines" : {
-    "node" : ">=20.0.0"
+  "engines": {
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "@astrojs/starlight": "^0.30.3",
     "@astrojs/starlight-tailwind": "^3.0.0",
     "@astrojs/tailwind": "^5.1.3",
     "@catppuccin/vscode": "^3.16.0",
-    "@expressive-code/plugin-line-numbers": "^0.38.3",
     "astro": "^5.0.2",
     "sharp": "^0.32.5",
     "tailwindcss": "^3.4.4"

docs/src/content/docs/guides/bootstrap.md → docs/src/content/docs/guides/bootstrap.mdx

@@ -5,6 +5,8 @@ sidebar:
   order: 20
 ---
 
+import { Code } from '@astrojs/starlight/components';
+
 ## How to start the process
 
 The bootstrap process is automatically started after following the [NodeKit installation instructions](/guides/getting-started), but it can also be triggered manually by running this command:
@@ -19,19 +21,17 @@ The bootstrap process is automatically started after following the [NodeKit inst
 
 If there is none, it will ask if you want to start a node installation:
 
-> Installing A Node
->
-> It looks like you're running this for the first time. Would you like to install a node? (y/n)
+<Code showLineNumbers="no" wrap="no" code="Installing A Node
 
-You can respond by pressing the `Y` or `N` keys of your keyboard, for `Yes` and `No` respectively.
+It looks like you're running this for the first time. Would you like to install a node? (y/n)" />
 
 ---
 
 It will then ask if you want to perform a "fast-catchup" with the network:
 
-> Regular sync with the network usually takes multiple days to weeks. You can optionally perform fast-catchup to sync in 30-60 minutes instead.
->
-> Would you like to preform a fast-catchup after installation? (y/n)
+<Code showLineNumbers="no" wrap="no" code="Regular sync with the network usually takes multiple days to weeks. You can optionally perform fast-catchup to sync in 30-60 minutes instead.
+
+Would you like to preform a fast-catchup after installation? (y/n)" />
 
 Fast-catchup saves a lot of time, so we recommend responding Yes.
 
@@ -46,7 +46,12 @@ INFO Installing with apt-get
 [sudo] password for user:
 ```
 
-Your operating system requires this to allow NodeKit to install the Algorand node software. Enter your user password and press ENTER to proceed.
+<details>
+  <summary>Why is the installer asking for my password?</summary>
+  The installer will ask for your user password during the node installation process.
+
+  This is required by your operating system in order to install new software.
+</details>
 
 ## Installation
 
@@ -70,7 +75,28 @@ When the process is done, the Fast Catchup status information will disappear and
 
 ![](/assets/nodekit-state-running.png)
 
-:::note
-**Did you encounted any errors?**
-Check out the [Troubleshooting: Installing and bootstrapping the Algorand node](/troubleshooting#bootstrapping-the-algorand-node) section.
-:::
+<details>
+  <summary>Troubleshooting: Fast-catchup</summary>
+  If the fast catchup process does not complete within 1-2 hours, check the following:
+
+  **Your hardware meets the requirements**
+
+  Check that your node meets the [hardware requirements](https://developer.algorand.org/docs/run-a-node/setup/install/#hardware-requirements) for a participation node.
+
+  **Nodekit is in FAST-CATCHUP state**
+
+  The colored status at the top of Nodekit should be in a yellow `FAST-CATCHUP` state:
+
+  ![](/assets/nodekit-state-fast-catchup.png)
+
+  If not, exit nodekit with `Q` and run `./nodekit catchup` to start catching up. Then run `./nodekit` again to enter the user interface.
+
+  After fast-catchup completes successfully, it is normal for a node to be in a `SYNCING` state for a few minutes:
+
+  ![](/assets/nodekit-state-syncing.png)
+
+  During this the `Latest Round` number should be increasing rapidly.
+
+  If there is no progress for a while, or the Latest Round value is smaller than `46000000` (46 million) then you should start fast-catchup again.
+
+</details>

docs/src/content/docs/guides/generate-participation-keys.md

@@ -35,12 +35,27 @@ You can press the `S` key to cycle through duration modes in days / months / rou
 
 The longer your duration, the longer the participation key generation step will take to complete.
 
+We recommend a value between 30 and 90 days.
+
 ## Key generation
 
 After you have selected your key duration, nodekit will instruct your node to generate participation keys.
 
 The time required for this step will depend on your participation key duration. As an indicative wait time, a 30-day participation key should take between 4-6 minutes to generate.
 
+<details>
+  <summary>Troubleshooting: Failed to get participation keys</summary>
+  Occasionally, Nodekit may fall out of sync with the Algorand node while waiting for the participation keys to be generated. In this case this error message will be shown:
+
+  `failed to get participation keys`
+
+  You can:
+
+  - wait for the participation keys to appear in the Accounts list
+  - try to generate a participation key again
+    - If the key generation process is still running on the node, you will see a `Participation key generation already in progress` error
+</details>
+
 ![](/assets/nodekit-partkey-gen-3.png)
 
 ## Done
@@ -52,8 +67,3 @@ When your participation keys are ready, nodekit will display the key information
 You are now one step away from participating in Algorand consensus!
 
 As the on screen message indicates, you can press `R` to start [Registering your keys](/guides/register-online).
-
-:::note
-**Did you encounted any errors?**
-Check out the [Troubleshooting: Generating participation keys](/troubleshooting#generating-participation-keys) section.
-:::

docs/src/content/docs/guides/getting-started.md → docs/src/content/docs/guides/getting-started.mdx

@@ -5,6 +5,8 @@ sidebar:
   order: 10
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 Welcome to NodeKit, your command-line one-stop-shop for Algorand node running.
 
 NodeKit can help you with:
@@ -16,19 +18,37 @@ NodeKit can help you with:
 
 To get started with NodeKit, copy-paste this command in your terminal:
 
+<Tabs syncKey="os">
+<TabItem label="Linux" icon="linux">
+
 ```bash
+wget -qO- https://nodekit.run/install.sh | bash
+```
+</TabItem>
+<TabItem label="macOS" icon="apple">
+
+```sh
 curl -fsSL https://nodekit.run/install.sh | bash
 ```
 
+</TabItem>
+</Tabs>
+
+<details>
+  <summary>Troubleshooting: Command 'bash' not found</summary>
+  Some versions of Mac OS may not include the required `bash` executable that runs the installer.
+
+  If you get an error about `bash` not being available, please install bash on your system manually.
+
+  For Mac OS, a popular way to do this is to install [Homebrew](https://brew.sh/) and then install bash using:
+
+  ```bash
+  brew install bash
+  ```
+</details>
+
 This will detect your operating system and download the appropriate NodeKit executable to your local directory.
 
 It will then immediately start the bootstrap process to get your Algorand node up and running:
 
 ![Screenshot of a typical NodeKit installation process](/assets/nodekit-install.png)
-
-:::note
-**Did you encounter any errors?**
-Check out the [Troubleshooting: Getting Started](/troubleshooting#getting-started-with-nodekit) section.
-:::
-
-Otherwise, read on for guidance on the bootstrapping process.

docs/src/content/docs/guides/register-online.md

@@ -15,9 +15,7 @@ After you press `R`, you will see a link that you can follow to sign your key re
 
 ![](/assets/nodekit-keyreg-online.png)
 
-On most terminals, you can hold down Ctrl and click the link, which will open it in your default browser.
-
-If this does not work, copy the link and paste it into your browser.
+On most terminals, you can hold down `Ctrl` and click the link, which will open it in your default browser. If this does not work, copy the link and paste it into your browser.
 
 You will be taken to the Lora Transaction Wizard, where you should see the key information pre-filled:
 
@@ -39,6 +37,14 @@ NodeKit will detect the key registration and take you back to the Key informatio
 
 ![](/assets/nodekit-keyreg-success.png)
 
-You can press `ESC` to leave the key information modal.
+You can press `ESC` twice to get back to the home screen.
+
+To confirm that your account is online, review the `STATUS` of your account. Accounts with an `ONLINE` status are participating in consensus.
+
+That's it! If your account balance is over 30,000 ALGO, it will accumulate rewards for each block it proposes on the Algorand network.
+
+:::note
+The `Protocol Voting` label in the top right panel refers to the **consensus protocol upgrade process**, not your account participation.
 
-That's it! Your node is now participating in Algorand consensus. If your account balance is over 30,000 ALGO, it will accumulate rewards for each block it proposes on the Algorand network.
+![](/assets/note-protocol-voting.png)
+:::