docs: minor tweaks and fixes (#740)

* docs: enable math via KaTeX

* docs: move getting started to first pos

* docs: remove IP prefix from docker compose ports

* docs: improve wording for describing volumes key

* docs: update links

* docs: more codeblock highlights

* chore: updated dictionary.txt

* chore: nix fmt

* chore: nix fmt

* chore: updated npmDepsHash

dictionary.txt

@@ -183,6 +183,7 @@ cpufeatures
 cratedir
 crisiskeeper
 crisistypes
+crossorigin
 ctypes
 dasel
 dataconnector
@@ -316,6 +317,7 @@ journalctl
 jsonschema
 jwtsecret
 karel
+katex
 keccak
 keepertest
 keybase
@@ -459,6 +461,7 @@ reentrancy
 reflectionv
 regclass
 regen
+rehype
 repr
 reqwest
 ripemd

docs/docs.nix

@@ -1,7 +1,7 @@
 { ... }: {
   perSystem = { pkgs, lib, ... }:
     let
-      npmDepsHash = "sha256-0uH8gSnftFGVQfdoj8jxbxMhQb+/FTmrbQb+E0qfS68=";
+      npmDepsHash = "sha256-sNrhY5+/xtMpfmqbb8JlCWaktewOgZ6q8sGJ0fNL5kc=";
       src = ../.;
       pname = "docs";
       version = "0.0.1";

docs/docs/04_infrastructure/01_node_operators/docker-compose.md

@@ -18,13 +18,13 @@ services:
     image: ghcr.io/unionlabs/uniond:latest
     volumes: ~/.uniond:/root/.uniond
     ports:
-      - "127.0.0.1:26657:26657"
+      - "26657:26657"
       - "1317:1317"
       - "9093:9093"
     restart: unless-stopped
 ```
 
-The only section of significance is the `volumes` key. Here we map an already initialized `~/.uniond` directory to the `node` service. The `~/.uniond` directory should contain a `config` and `data` directory. To properly set these up, check out the [validator guide](./getting-started#initialization).
+Pay special attention to the `volumes` key. Here we map an already initialized `~/.uniond` directory to the `node` service. The `~/.uniond` directory should contain a `config` and `data` directory. To properly set these up, check out the [validator guide](./getting-started#initialization).
 
 ## Monitoring
 

docs/docs/04_infrastructure/01_node_operators/getting-started.md

@@ -1,5 +1,6 @@
 ---
 title: "Getting Started"
+sidebar_position: 0
 ---
 
 This guide is intended for validators running on bare-metal servers and explains how Union releases work. Check out the [NixOS](./nixos) and the [kubernetes](./kubernetes) guide for more production-ready deployments.
@@ -10,8 +11,14 @@ Validators are the backbone of the network. Becoming one requires significant to
 
 You can obtain `uniond` from a recent [release](https://github.com/unionlabs/union/releases/latest).
 
+:::note
+
+Double check the version and architecture in the link before downloading.
+
+:::
+
 ```sh
-curl -L -o uniond https://github.com/unionlabs/union/releases/download/v0.5.0-rc1/uniond-x86_64-linux
+curl -L -o uniond https://github.com/unionlabs/union/releases/download/v0.13.0/uniond-x86_64-linux
 ```
 
 Verify that the binary works on your server by running:
@@ -31,7 +38,7 @@ mv ./uniond /usr/bin/
 We also provide containers in our [package registry](https://github.com/unionlabs/union/pkgs/container/uniond).
 
 ```sh
-docker pull ghcr.io/unionlabs/uniond:v0.5.0-rc1
+docker pull ghcr.io/unionlabs/uniond:v0.13.0
 ```
 
 When running the container, make sure to map a volume to the path passed in `--home` options to ensure data persistence. From here on the guide assumes the usage of a regular binary. The [docker-compose](./docker-compose) section is more suited for docker users.
@@ -42,7 +49,7 @@ When running the container, make sure to map a volume to the path passed in `--h
 
 ## Initialization
 
-We'll need to set up a few configuration files and obtain the [genesis.json] before we can run the node.
+We'll need to set up a few configuration files and obtain the [genesis.json](https://raw.githubusercontent.com/unionlabs/union/e1f9a3e3b84a8c39faf7046931159eda3e95fdb2/networks/genesis/union-testnet-3/genesis.json) before we can run the node.
 
 First, set some environment variables, which are used throughout initialization.
 
@@ -55,7 +62,7 @@ export GENESIS_URL="https://raw.githubusercontent.com/unionlabs/union/e1f9a3e3b8
 
 Then we'll have `uniond` initialize our data and configuration directories. By default `/User/{USER}/.uniond` is used.
 
-```
+```sh
 uniond init $MONIKER "bn254" --chain-id $CHAIN_ID
 ```
 
@@ -73,9 +80,9 @@ seeds = "b4d587b3d3666d52df0cd43962080fd164568fe0@union-testnet.cor.systems:2665
 
 ### Genesis Configuration
 
-Download the [genesis.json] and copy it to your `uniond` home directory.
+Download the [genesis.json](https://raw.githubusercontent.com/unionlabs/union/e1f9a3e3b84a8c39faf7046931159eda3e95fdb2/networks/genesis/union-testnet-3/genesis.json) and copy it to your `uniond` home directory.
 
-```
+```sh
 curl $GENESIS_URL > ~/.union/config/genesis.json
 ```
 
@@ -85,7 +92,7 @@ To join as a validator, you need to submit a registration transaction. You can d
 
 First, add a wallet that holds Union tokens.
 
-```
+```sh
 uniond keys add $KEY_NAME --recover
 ```
 
@@ -115,7 +122,7 @@ uniond tx staking create-validator \
 
 We recommend running `uniond` as a systemd service. Create a file in `/etc/systemd/system` called `uniond.service`. Make sure to replace $USER with your username.
 
-```
+```systemd
 [Unit]
 Description=uniond
 [Service]
@@ -131,13 +138,11 @@ WantedBy=multi-user.target
 
 You should be able to view the node logs by executing
 
-```
+```sh
 sudo journalctl -f -u uniond
 ```
 
 It's then recommended to back up these files from `~/.union/config` in a secure location:
 
 - `priv_validator_key.json`
 - `node_key.json`
-
-[genesis.json] https://raw.githubusercontent.com/unionlabs/union/e1f9a3e3b84a8c39faf7046931159eda3e95fdb2/networks/genesis/union-testnet-3/genesis.json

docs/docs/04_infrastructure/01_node_operators/nixos.mdx

@@ -23,15 +23,15 @@ import CodeBlock from "@theme/CodeBlock";
 
 You can then deploy the configuration by running
 
-```
+```sh
 GIT_LFS_SKIP_SMUDGE=1 nixos-rebuild switch --flake .#testnet-validator --target-host user@validator.domain -L
 ```
 
 ## Upgrading
 
 To upgrade to newer versions, simply run
 
-```
+```sh
 nix flake update
 GIT_LFS_SKIP_SMUDGE=1 nixos-rebuild switch --flake .#testnet-validator --target-host user@validator.domain -L
 ```

docs/docusaurus.config.js

@@ -3,6 +3,8 @@
 
 const lightCodeTheme = require("prism-react-renderer/themes/github");
 const darkCodeTheme = require("prism-react-renderer/themes/dracula");
+const math = require("remark-math");
+const katex = require("rehype-katex");
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -38,6 +40,8 @@ const config = {
           routeBasePath: "/",
           sidebarPath: require.resolve("./sidebars.js"),
           editUrl: "https://github.com/unionlabs/union/edit/main/docs",
+          remarkPlugins: [math],
+          rehypePlugins: [katex],
         },
         blog: false,
         theme: {
@@ -46,6 +50,15 @@ const config = {
       }),
     ],
   ],
+  stylesheets: [
+    {
+      href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css",
+      type: "text/css",
+      integrity:
+        "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM",
+      crossorigin: "anonymous",
+    },
+  ],
 
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
@@ -94,7 +107,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ["nix", "solidity"],
+        additionalLanguages: ["nix", "solidity", "systemd", "bash"],
       },
     }),
 };

docs/package.json

@@ -19,10 +19,13 @@
     "@docusaurus/theme-mermaid": "2.4.1",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
+    "hast-util-is-element": "1.1.0",
     "prism-react-renderer": "^1.3.5",
     "raw-loader": "^4.0.2",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "rehype-katex": "5",
+    "remark-math": "3"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.0"

yarn.lock

@@ -2133,6 +2133,11 @@
   resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.12.tgz#d70faba7039d5fca54c83c7dbab41051d2b6f6cb"
   integrity sha512-Hr5Jfhc9eYOQNPYO5WLDq/n4jqijdHNlDXjuAQkkt+mWdQR+XJToOHrsD4cPaMXpn6KO7y2+wM8AZEs8VpBLVA==
 
+"@types/katex@^0.11.0":
+  version "0.11.1"
+  resolved "https://registry.yarnpkg.com/@types/katex/-/katex-0.11.1.tgz#34de04477dcf79e2ef6c8d23b41a3d81f9ebeaf5"
+  integrity sha512-DUlIj2nk0YnJdlWgsFuVKcX27MLW0KbKmGVoUHmFr+74FYYNUDAaj9ZqTADvsbE8rfxuVmSFc7KczYn5Y09ozg==
+
 "@types/mdast@^3.0.0":
   version "3.0.11"
   resolved "https://registry.yarnpkg.com/@types/mdast/-/mdast-3.0.11.tgz#dc130f7e7d9306124286f6d6cee40cf4d14a3dc0"
@@ -3088,7 +3093,7 @@ commander@^5.1.0:
   resolved "https://registry.yarnpkg.com/commander/-/commander-5.1.0.tgz#46abbd1652f8e059bddaef99bbdcb2ad9cf179ae"
   integrity sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==
 
-commander@^8.3.0:
+commander@^8.0.0, commander@^8.3.0:
   version "8.3.0"
   resolved "https://registry.yarnpkg.com/commander/-/commander-8.3.0.tgz#4837ea1b2da67b9c616a67afbb0fafee567bca66"
   integrity sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==
@@ -4630,6 +4635,11 @@ hast-util-from-parse5@^6.0.0:
     vfile-location "^3.2.0"
     web-namespaces "^1.0.0"
 
+hast-util-is-element@1.1.0, hast-util-is-element@^1.0.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/hast-util-is-element/-/hast-util-is-element-1.1.0.tgz#3b3ed5159a2707c6137b48637fbfe068e175a425"
+  integrity sha512-oUmNua0bFbdrD/ELDSSEadRVtWZOf3iF6Lbv81naqsIV99RnSCieTbWuWCY8BAeEfKJTKl0gRdokv+dELutHGQ==
+
 hast-util-parse-selector@^2.0.0:
   version "2.2.5"
   resolved "https://registry.yarnpkg.com/hast-util-parse-selector/-/hast-util-parse-selector-2.2.5.tgz#d57c23f4da16ae3c63b3b6ca4616683313499c3a"
@@ -4662,6 +4672,15 @@ hast-util-to-parse5@^6.0.0:
     xtend "^4.0.0"
     zwitch "^1.0.0"
 
+hast-util-to-text@^2.0.0:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/hast-util-to-text/-/hast-util-to-text-2.0.1.tgz#04f2e065642a0edb08341976084aa217624a0f8b"
+  integrity sha512-8nsgCARfs6VkwH2jJU9b8LNTuR4700na+0h3PqCaEk4MAnMDeu5P0tP8mjk9LLNGxIeQRLbiDbZVw6rku+pYsQ==
+  dependencies:
+    hast-util-is-element "^1.0.0"
+    repeat-string "^1.0.0"
+    unist-util-find-after "^3.0.0"
+
 hastscript@^6.0.0:
   version "6.0.0"
   resolved "https://registry.yarnpkg.com/hastscript/-/hastscript-6.0.0.tgz#e8768d7eac56c3fdeac8a92830d58e811e5bf640"
@@ -5265,6 +5284,13 @@ jsonfile@^6.0.1:
   optionalDependencies:
     graceful-fs "^4.1.6"
 
+katex@^0.13.0:
+  version "0.13.24"
+  resolved "https://registry.yarnpkg.com/katex/-/katex-0.13.24.tgz#fe55455eb455698cb24b911a353d16a3c855d905"
+  integrity sha512-jZxYuKCma3VS5UuxOx/rFV1QyGSl3Uy/i0kTJF3HgQ5xMinCQVF8Zd4bMY/9aI9b9A2pjIBOsjSSm68ykTAr8w==
+  dependencies:
+    commander "^8.0.0"
+
 keyv@^3.0.0:
   version "3.1.0"
   resolved "https://registry.yarnpkg.com/keyv/-/keyv-3.1.0.tgz#ecc228486f69991e49e9476485a5be1e8fc5c4d9"
@@ -6747,6 +6773,26 @@ regjsparser@^0.9.1:
   dependencies:
     jsesc "~0.5.0"
 
+rehype-katex@5:
+  version "5.0.0"
+  resolved "https://registry.yarnpkg.com/rehype-katex/-/rehype-katex-5.0.0.tgz#b556f24fde918f28ba1cb642ea71c7e82f3373d7"
+  integrity sha512-ksSuEKCql/IiIadOHiKRMjypva9BLhuwQNascMqaoGLDVd0k2NlE2wMvgZ3rpItzRKCd6vs8s7MFbb8pcR0AEg==
+  dependencies:
+    "@types/katex" "^0.11.0"
+    hast-util-to-text "^2.0.0"
+    katex "^0.13.0"
+    rehype-parse "^7.0.0"
+    unified "^9.0.0"
+    unist-util-visit "^2.0.0"
+
+rehype-parse@^7.0.0:
+  version "7.0.1"
+  resolved "https://registry.yarnpkg.com/rehype-parse/-/rehype-parse-7.0.1.tgz#58900f6702b56767814afc2a9efa2d42b1c90c57"
+  integrity sha512-fOiR9a9xH+Le19i4fGzIEowAbwG7idy2Jzs4mOrFWBSJ0sNUgy0ev871dwWnbOo371SjgjG4pwzrbgSVrKxecw==
+  dependencies:
+    hast-util-from-parse5 "^6.0.0"
+    parse5 "^6.0.0"
+
 relateurl@^0.2.7:
   version "0.2.7"
   resolved "https://registry.yarnpkg.com/relateurl/-/relateurl-0.2.7.tgz#54dbf377e51440aca90a4cd274600d3ff2d888a9"
@@ -6766,6 +6812,11 @@ remark-footnotes@2.0.0:
   resolved "https://registry.yarnpkg.com/remark-footnotes/-/remark-footnotes-2.0.0.tgz#9001c4c2ffebba55695d2dd80ffb8b82f7e6303f"
   integrity sha512-3Clt8ZMH75Ayjp9q4CorNeyjwIxHFcTkaektplKGl2A1jNGEUey8cKL0ZC5vJwfcD5GFGsNLImLG/NGzWIzoMQ==
 
+remark-math@3:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/remark-math/-/remark-math-3.0.1.tgz#85a02a15b15cad34b89a27244d4887b3a95185bb"
+  integrity sha512-epT77R/HK0x7NqrWHdSV75uNLwn8g9qTyMqCRCDujL0vj/6T6+yhdrR7mjELWtkse+Fw02kijAaBuVcHBor1+Q==
+
 remark-mdx@1.6.22:
   version "1.6.22"
   resolved "https://registry.yarnpkg.com/remark-mdx/-/remark-mdx-1.6.22.tgz#06a8dab07dcfdd57f3373af7f86bd0e992108bbd"
@@ -6820,7 +6871,7 @@ renderkid@^3.0.0:
     lodash "^4.17.21"
     strip-ansi "^6.0.1"
 
-repeat-string@^1.5.4:
+repeat-string@^1.0.0, repeat-string@^1.5.4:
   version "1.6.1"
   resolved "https://registry.yarnpkg.com/repeat-string/-/repeat-string-1.6.1.tgz#8dcae470e1c88abc2d600fff4a776286da75e637"
   integrity sha512-PV0dzCYDNfRi1jCDbJzpW7jNNDRuCOG/jI5ctQcGKt/clZD+YcPS3yIlWuTJMmESC8aevCFmWJy5wjAFgNqN6w==
@@ -7610,7 +7661,7 @@ unified@9.2.0:
     trough "^1.0.0"
     vfile "^4.0.0"
 
-unified@^9.2.2:
+unified@^9.0.0, unified@^9.2.2:
   version "9.2.2"
   resolved "https://registry.yarnpkg.com/unified/-/unified-9.2.2.tgz#67649a1abfc3ab85d2969502902775eb03146975"
   integrity sha512-Sg7j110mtefBD+qunSLO1lqOEKdrwBFBrR6Qd8f4uwkhWNlbkaqwHse6e7QvD3AP/MNoJdEDLaf8OxYyoWgorQ==
@@ -7634,6 +7685,13 @@ unist-builder@2.0.3, unist-builder@^2.0.0:
   resolved "https://registry.yarnpkg.com/unist-builder/-/unist-builder-2.0.3.tgz#77648711b5d86af0942f334397a33c5e91516436"
   integrity sha512-f98yt5pnlMWlzP539tPc4grGMsFaQQlP/vM396b00jngsiINumNmsY8rkXjfoi1c6QaM8nQ3vaGDuoKWbe/1Uw==
 
+unist-util-find-after@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/unist-util-find-after/-/unist-util-find-after-3.0.0.tgz#5c65fcebf64d4f8f496db46fa8fd0fbf354b43e6"
+  integrity sha512-ojlBqfsBftYXExNu3+hHLfJQ/X1jYY/9vdm4yZWjIbf0VuWF6CRufci1ZyoD/wV2TYMKxXUoNuoqwy+CkgzAiQ==
+  dependencies:
+    unist-util-is "^4.0.0"
+
 unist-util-generated@^1.0.0:
   version "1.1.6"
   resolved "https://registry.yarnpkg.com/unist-util-generated/-/unist-util-generated-1.1.6.tgz#5ab51f689e2992a472beb1b35f2ce7ff2f324d4b"