Docusaurus v3 Upgrade (#752)

* upgrade package versions

* convert docusaurus config to typescript

* change dependency version for katex and math plugins

* re-add sentry plugin

* remove old docLayoutComponent config for platforms plugin

* update redocly config file, regenerate openapi docs

* fix compilation errors for MDX v3

* update sidebars files, re-swizzle ApiExplorer theme component

* add temporary patch for code samples issue

Refs: PaloAltoNetworks/docusaurus-openapi-docs/issues/870

* adjust sidebar generator for main docs plugin

* re-swizzle a couple theme components into typescript

* even more swizzling of components

* resolve the build failures

* upgrade openapi plugin, remove no-longer-necessary patch

* format and lint everything

* upgrade Dockerfile and gh workflow to nodejs 20

* downgrade an openrpc package, linting/formatting changes

* temporarily increase the container node memory to get it to build

* check for "MDXUl" and "ul" in attribute table lists

* regenerate openapi docs

* remove dependencies for unused features in dapps challenge

* formatting/linting the dapps challenge commented parts

* fix broken links

* so many broken anchors to fix

* enable mdx1 compatibility for old-style heading IDs

* throw error for broken links again

* reformat some links in a hubble analyst guide

.github/workflows/main.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
-          node-version: '18'
+          node-version: '20'
           cache: 'yarn'
           cache-dependency-path: '**/yarn.lock'
 

.nvmrc

@@ -1 +1 @@
-v18
+v20

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:22.04 as build
+FROM ubuntu:22.04 AS build
 
 LABEL maintainer="SDF Ops Team <[email protected]>"
 
@@ -9,7 +9,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 ENV INLINE_RUNTIME_CHUNK=false
 RUN apt-get update && apt-get install --no-install-recommends -y gpg curl git make ca-certificates apt-transport-https && \
     curl -sSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key|gpg --dearmor >/etc/apt/trusted.gpg.d/nodesource-key.gpg && \
-    echo "deb https://deb.nodesource.com/node_18.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list && \
+    echo "deb https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list && \
     curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg |gpg --dearmor >/etc/apt/trusted.gpg.d/yarnpkg.gpg && \
     echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list && \
     apt-get update && apt-get install -y nodejs yarn && apt-get clean
@@ -19,7 +19,7 @@ COPY . /app/
 RUN yarn install
 RUN yarn rpcspec:build
 RUN yarn stellar-cli:build
-RUN yarn build
+RUN NODE_OPTIONS="--max-old-space-size=4096" yarn build
 
 FROM nginx:1.17
 

docs/build/apps/example-application-tutorial/path-payment.mdx

@@ -119,30 +119,30 @@ Most of this page has been discussed in the [Payment section](./payment.mdx#the-
           /* ... */
         })
       : // highlight-start
-      pathPayment && strictReceive
-      ? await createPathPaymentStrictReceiveTransaction({
-          source: data.publicKey,
-          sourceAsset: sendAsset,
-          sourceAmount: sendAmount,
-          destination: otherDestination ? otherPublicKey : destination,
-          destinationAsset: receiveAsset,
-          destinationAmount: receiveAmount,
-          memo: memo,
-        })
-      : pathPayment && !strictReceive
-      ? await createPathPaymentStrictSendTransaction({
-          source: data.publicKey,
-          sourceAsset: sendAsset,
-          sourceAmount: sendAmount,
-          destination: otherDestination ? otherPublicKey : destination,
-          destinationAsset: receiveAsset,
-          destinationAmount: receiveAmount,
-          memo: memo,
-        })
-      : // highlight-end
-        await createPaymentTransaction({
-          /* ... */
-        });
+        pathPayment && strictReceive
+        ? await createPathPaymentStrictReceiveTransaction({
+            source: data.publicKey,
+            sourceAsset: sendAsset,
+            sourceAmount: sendAmount,
+            destination: otherDestination ? otherPublicKey : destination,
+            destinationAsset: receiveAsset,
+            destinationAmount: receiveAmount,
+            memo: memo,
+          })
+        : pathPayment && !strictReceive
+          ? await createPathPaymentStrictSendTransaction({
+              source: data.publicKey,
+              sourceAsset: sendAsset,
+              sourceAmount: sendAmount,
+              destination: otherDestination ? otherPublicKey : destination,
+              destinationAsset: receiveAsset,
+              destinationAmount: receiveAmount,
+              memo: memo,
+            })
+          : // highlight-end
+            await createPaymentTransaction({
+              /* ... */
+            });
 
     /* ... */
   };

docs/build/guides/conventions/deploy-contract.mdx

@@ -4,7 +4,7 @@ title: Deploy a contract from installed Wasm bytecode using a deployer contract
 
 <head>
   <title>
-    Deploy a contract from installed Wasm bytecode using a deployer contract
+    {`Deploy a contract from installed Wasm bytecode using a deployer contract`}
   </title>
   <meta charSet="utf-8" />
   <meta
@@ -25,7 +25,7 @@ This guide walks through the process of deploying a smart contract from installe
 
 - Basic understanding of [Rust programming language](https://www.rust-lang.org/). To brush up on Rust, check out [Rustlings](https://github.com/rust-lang/rustlings) or [The Rust book](https://doc.rust-lang.org/book/).
 - Familiarity with [Stellar smart contracts](../../smart-contracts/getting-started/hello-world.mdx)
-- Installed Cargo, [Stellar CLI](../../smart-contracts/getting-started/setup.mdx#install-the-soroban-cli) and Soroban SDK
+- Installed Cargo, [Stellar CLI](../../smart-contracts/getting-started/setup.mdx#install-the-stellar-cli) and Soroban SDK
 
 ### Setup environment
 

docs/build/guides/conventions/install-deploy-contract-with-code.mdx

@@ -23,7 +23,7 @@ Before you begin, ensure you have the following installed:
 
 1. [Rust](https://www.rust-lang.org/) and Cargo (for compiling smart contracts)
 2. [Node.js](https://nodejs.org/en) and npm (for running JavaScript deployment scripts)
-3. [Soroban CLI](../../smart-contracts/getting-started/setup.mdx#install-the-soroban-cli)
+3. [Soroban CLI](../../smart-contracts/getting-started/setup.mdx#install-the-stellar-cli)
 
 # Initialize a sample Rust Contract
 

docs/build/guides/conventions/upgrading-contracts.mdx

@@ -23,7 +23,7 @@ Upgrading a smart contract allows you to improve or modify your contract without
 
 - Basic understanding of [Rust programming language]. To brush up on Rust, check out [Rustlings](https://github.com/rust-lang/rustlings) or [The Rust book](https://doc.rust-lang.org/book/).
 - Familiarity with [Stellar smart contracts](../../smart-contracts/getting-started/hello-world.mdx)
-- Installed [Stellar CLI](../../smart-contracts/getting-started/setup.mdx#install-the-soroban-cli) and Soroban SDK
+- Installed [Stellar CLI](../../smart-contracts/getting-started/setup.mdx#install-the-stellar-cli) and Soroban SDK
 
 ### Download the upgradeable contract example
 

docs/smart-contracts/guides/transactions/simulateTransaction-Deep-Dive.mdx → docs/build/guides/transactions/simulateTransaction-Deep-Dive.mdx

@@ -1,28 +1,8 @@
 ---
 title: simulateTransaction RPC method guide
-hide_table_of_contents: true
 ---
 
-## simulateTransaction Examples and Tutorials Guide
-
-### Table of Contents
-
-- [simulateTransaction Examples and Tutorials Guide](#simulatetransaction-examples-and-tutorials-guide)
-  - [Table of Contents](#table-of-contents)
-- [Overview](#overview)
-- [When to Use `simulateTransaction` (whenever you use soroban :D )](#when-to-use-simulatetransaction-whenever-you-use-soroban-d-)
-- [How to Call `simulateTransaction`](#how-to-call-simulatetransaction)
-  - [Using Fetch](#using-fetch)
-  - [Using the JavaScript SDK](#using-the-javascript-sdk)
-- [Understanding the Footprint](#understanding-the-footprint)
-- [Assembling a Transaction](#assembling-a-transaction)
-  - [javascript-sdk-assembleTransaction](#javascript-sdk-assembletransaction)
-- [Handling Archived Ledger Entries](#handling-archived-ledger-entries)
-- [Fees and Resource Usage](#fees-and-resource-usage)
-- [Preflight Error Handling](#preflight-error-handling)
-  - [Common Preflight Errors](#common-preflight-errors)
-- [Backend Code and Workflow](#backend-code-and-workflow)
-- [Further Reading](#further-reading)
+# `simulateTransaction` Examples and Tutorials Guide
 
 ## Overview
 

docs/build/smart-contracts/example-contracts/alloc.mdx

@@ -6,7 +6,7 @@ sidebar_position: 80
 
 <head>
   <title>
-    Use the allocator feature to emulate heap memory in a smart contract.
+    {`Use the allocator feature to emulate heap memory in a smart contract.`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/example-contracts/custom-account.mdx

@@ -6,8 +6,8 @@ sidebar_position: 150
 
 <head>
   <title>
-    Implement an account contract supporting multisig and custom authorization
-    policies.
+    {`Implement an account contract supporting multisig and custom authorization
+    policies.`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/example-contracts/deployer.mdx

@@ -6,7 +6,7 @@ sidebar_position: 70
 
 <head>
   <title>
-    Deploy and initialize a smart contract using another smart contract.
+    {`Deploy and initialize a smart contract using another smart contract.`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/example-contracts/fuzzing.mdx

@@ -6,7 +6,7 @@ sidebar_position: 160
 
 <head>
   <title>
-    Increase confidence in a contract's correctness with fuzz testing.
+    {`Increase confidence in a contract's correctness with fuzz testing.`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/example-contracts/liquidity-pool.mdx

@@ -467,7 +467,7 @@ Open the `liquidity_pool/src/lib.rs` file or see the code above to follow along.
 
 When this contract is first deployed, it could create a liquidity pool for _any_ pair of tokens available on Soroban. It must first be initialized with the following information:
 
-- **`token_wasm_hash`:** The contract will end up [creating its own `POOL` token] as well as [interacting with contracts for `token_a` and `token_b`]. The way this example works is by using the [`token` example contract] for both of these jobs. When our liquidity pool contract is initialized it wants us to pass the wasm hash of the **already [installed]** token contract. It will then deploy a contract that will run the WASM bytecode stored at that hash as a new token contract for the `POOL` tokens.
+- **`token_wasm_hash`:** The contract will end up [creating its own `POOL` token] as well as [interacting with contracts for `token_a` and `token_b`]. The way this example works is by using the [`token` example contract] for both of these jobs. When our liquidity pool contract is initialized it wants us to pass the wasm hash of the **already installed** token contract. It will then deploy a contract that will run the WASM bytecode stored at that hash as a new token contract for the `POOL` tokens.
 - **`token_a`:** The contract `Address` for an **already deployed** (or wrapped) token that will be held in reserve by the liquidity pool.
 - **`token_b`:** The contract `Address` for an **already deployed** (or wrapped) token that will be held in reserve by the liquidity pool.
 
@@ -492,7 +492,6 @@ fn initialize(e: Env, token_wasm_hash: BytesN<32>, taken_a: Address, token_b: Ad
 [creating its own `pool` token]: #creating-a-custom-pool-token-for-lp-shares
 [interacting with contracts for `token_a` and `token_b`]: #token-transfers-tofrom-the-lp-contract
 [`token` example contract]: ./tokens.mdx
-[installed]: ../getting-started/deploy-to-testnet.mdx#two-step-deployment
 [lexicographical order]: ../../../learn/encyclopedia/sdex/liquidity-on-stellar-sdex-liquidity-pools.mdx#liquidity-pool-participation
 
 ### A "Constant Product" Liquidity Pool

docs/build/smart-contracts/example-contracts/logging.mdx

@@ -39,7 +39,7 @@ Logs are not accessible by dapps and other applications. See the [events example
 
 :::
 
-[testing]: ../getting-started/hello-world.mdx#testing
+[testing]: ../getting-started/hello-world.mdx#run-the-tests
 [events example]: events.mdx
 
 ## Run the Example

docs/build/smart-contracts/example-contracts/single-offer-sale.mdx

@@ -6,7 +6,7 @@ sidebar_position: 120
 
 <head>
   <title>
-    Make a standing offer to sell a token in exchange for another token.
+    {`Make a standing offer to sell a token in exchange for another token.`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/example-contracts/timelock.mdx

@@ -6,7 +6,7 @@ sidebar_position: 110
 
 <head>
   <title>
-    Lockup some token to be claimed by another user under set conditions
+    {`Lockup some token to be claimed by another user under set conditions`}
   </title>
   <meta charSet="utf-8" />
   <meta

docs/build/smart-contracts/getting-started/deploy-to-testnet.mdx

@@ -27,7 +27,7 @@ To recap what we've done so far, in [Setup](setup.mdx):
 - configured the stellar-cli to communicate with the Stellar Testnet via RPC
 - and configured an identity to sign transactions
 
-In [Hello World](hello-world.mdx) we created a `hello-world` project, and learned how to test and build the `HelloWorld` contract. Now we are ready to deploy that contract to Testnet, and interact with it.
+In [Hello World](./hello-world.mdx) we created a `hello-world` project, and learned how to test and build the `HelloWorld` contract. Now we are ready to deploy that contract to Testnet, and interact with it.
 
 ## Deploy
 
@@ -63,7 +63,7 @@ This returns the contract's id, starting with a `C`. In this example, we're goin
 
 ## Interact
 
-Using the code we wrote in [Write a Contract](hello-world.mdx#write-a-contract) and the resulting `.wasm` file we built in [Build](hello-world.mdx#build), run the following command to invoke the `hello` function.
+Using the code we wrote in [Write a Contract](./hello-world.mdx#contract-source-code) and the resulting `.wasm` file we built in [Build](hello-world.mdx#build-the-contract), run the following command to invoke the `hello` function.
 
 :::info
 

docs/build/smart-contracts/getting-started/hello-world.mdx

@@ -333,7 +333,7 @@ This will optimize and output a new `hello_world.optimized.wasm` file in the sam
 
 :::tip
 
-Building optimized contracts is only necessary when deploying to a network with fees or when analyzing and profiling a contract to get it as small as possible. If you're just starting out writing a contract, these steps are not necessary. See [Build](#build) for details on how to build for development.
+Building optimized contracts is only necessary when deploying to a network with fees or when analyzing and profiling a contract to get it as small as possible. If you're just starting out writing a contract, these steps are not necessary. See [Build](#build-the-contract) for details on how to build for development.
 
 :::
 

docs/data/horizon/admin-guide/prerequisites.mdx

@@ -40,7 +40,7 @@ To achieve high availability, redundancy, and high throughput, refer to the [sca
 
 - Ensure that the Horizon instance can establish a connection with the PostgreSQL database instance. The default port for PostgreSQL is 5432.
 
-- A stable and fast network connection with the Internet is required for any Horizon instance running the ingestion role. This is to ensure it has efficient outbound connectivity to remote hosts in the [quorum set](../../../validators/admin-guide/configuring.mdx#choosing-your-quorum-set) and [archive urls](../../../validators/admin-guide/configuring.mdx#history) for the chosen Stellar network. During ingestion, the Horizon instance communicates with these hosts, receiving network transaction data through its local captive core sub-process.
+- A stable and fast network connection with the Internet is required for any Horizon instance running the ingestion role. This is to ensure it has efficient outbound connectivity to remote hosts in the [quorum set](../../../validators/admin-guide/configuring.mdx#choosing-your-quorum-set) and [archive urls](../../../validators/admin-guide/environment-preparation.mdx#history-archives) for the chosen Stellar network. During ingestion, the Horizon instance communicates with these hosts, receiving network transaction data through its local captive core sub-process.
 
 :::note
 

docs/data/horizon/admin-guide/running.mdx

@@ -5,11 +5,11 @@ sidebar_position: 40
 
 import { CodeExample } from "@site/src/components/CodeExample";
 
-Once you have [established the Horizon database](./configuring.mdx#initialize-horizon-database) and have [identified the Horizon runtime config per host](./configuring.mdx#pre-requisites), you're ready to run Horizon.
+Once you have [established the Horizon database](./configuring.mdx#initialize-horizon-database) and have [identified the Horizon runtime config per host](./configuring.mdx#prerequisites), you're ready to run Horizon.
 
 ## Bare-metal installation
 
-Run the `stellar-horizon` binary with the [appropriate environment parameters](./configuring.mdx#parameters) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`).
+Run the `stellar-horizon` binary with the [appropriate environment parameters](./configuring.mdx#passing-configurations-to-horizon) set (or `stellar-horizon-cmd serve` if you [installed via the package manager](./installing.mdx#package-manager), which will automatically import your configuration from `/etc/default/stellar-horizon`).
 
 ## Containerized installation
 
@@ -23,7 +23,7 @@ Use `docker run stellar/stellar-horizon:<tag_version> --env-file <env_filename>`
 
 Ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm CLI tool and added the Stellar chart repo to Helm client.
 
-The Horizon process [requires access to a Postgres 12 database](./configuring.mdx#preparing-the-database). First use the common Kubernetes CLI tool `kubectl` from your workstation to create a Kubernetes secret on the intended namespace of the Kubernetes cluster which will hold the Horizon database URL.
+The Horizon process [requires access to a Postgres 12 database](./prerequisites.mdx#postgresql-database-server-compute-instance). First use the common Kubernetes CLI tool `kubectl` from your workstation to create a Kubernetes secret on the intended namespace of the Kubernetes cluster which will hold the Horizon database URL.
 
 <CodeExample>
 

docs/data/horizon/admin-guide/scaling.mdx

@@ -13,7 +13,7 @@ Horizon enables different logical tiers that can be scaled independently for inc
 
 It is recommend to start with a [single instance deployment](./prerequisites.mdx), and scale up based on the needs of your particular use-case.
 
-This [deployment](./configuring.mdx#single-instance-deployment) is intended for use with minimal history retention (<= 30 days) and minimal request volume.
+This [deployment](./configuring.mdx#single-instance-deployment) is intended for use with minimal history retention (\<= 30 days) and minimal request volume.
 
 In this setup, a single instance of Horizon performs all three [roles](./configuring.mdx#multiple-instance-deployment); ingestion, transaction submission, and end-user API requests.
 

docs/data/horizon/admin-guide/upgrading.mdx

@@ -50,7 +50,7 @@ Now that you know your current Horizon version, visit [Horizon Releases](https:/
 
 Now that you have indentified the new version and are aware of the potential impacts from upgrading to new version based on release notes, such as state rebuilds and db migrations, you are informed and ready to proceed with upgrade.
 
-Upgrading production deployents should leverage a secondary, hot-backup deployment, also known as a [blue/green model](./scaling.mdx#redundant-hot-backup) and perform the upgrade on the inactive deployment first. This will avoid downtime of system to your external users, as the upgrade takes place on the inactive deployment.
+Upgrading production deployents should leverage a secondary, hot-backup deployment, also known as a [blue/green model](./scaling.mdx#scaling-to-multiple-instances) and perform the upgrade on the inactive deployment first. This will avoid downtime of system to your external users, as the upgrade takes place on the inactive deployment.
 
 A good strategy for upgrading Horizon and applicable to single or multi-instance deployments - shut all instances down, install new Horizon version on one of the ingesting instances first. The reason being Horizon software will only initate `State Rebuild` and `DB Schema Migration` actions related to an upgrade on an instance that it detects ingestion has been enabled with configuration parameter, `INGEST=true`. This lowers complexity for you during the upgrade as you only need to focus on one instance and it avoids potential concurrent Horizon ingestion processes attempting the same upgrade on the database.
 

docs/data/horizon/api-reference/aggregations/order-books/single.mdx

@@ -16,7 +16,7 @@ When filtering for a specific order book, you must use use all six of these argu
 
 |  |  |
 | --- | --- |
-| GET | /order_book?selling_asset_type={native,credit_alphanum4,credit_alphanum12}&selling_asset_issuer={:account_id}&selling_asset_code{:asset_code}&buying_asset_type={native,credit_alphanum4,credit_alphanum12}&buying_asset_issuer={:account_id}&buying_asset_code{:asset_code}&limit={1-200} |
+| GET | /order_book?selling_asset_type=\{native,credit_alphanum4,credit_alphanum12}&selling_asset_issuer=\{:account_id}&selling_asset_code\{:asset_code}&buying_asset_type=\{native,credit_alphanum4,credit_alphanum12}&buying_asset_issuer=\{:account_id}&buying_asset_code\{:asset_code}&limit=\{1-200} |
 
 </Endpoint>