Migrate Mintlify to Docusaurus

TraceMachina · Jan 3, 2024 · 8f3d121 · 8f3d121
1 parent 546484b
commit 8f3d121
Show file tree

Hide file tree

Showing 23 changed files with 8,849 additions and 5,488 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,15 @@ __pycache__
 .pre-commit-config.yaml
 result
 .bazelrc.user
+/node_modules
+/build
+.docusaurus
+.cache-loader
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/flake.nix b/flake.nix
@@ -145,6 +145,7 @@
               pkgs.kubectl
               pkgs.kubernetes-helm
               pkgs.cilium-cli
+              pkgs.yarn
 
               # Additional tools from within our development environment.
               local-image-test

diff --git a/nativelink-docs/.gitignore b/nativelink-docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/nativelink-docs/README.md b/nativelink-docs/README.md
@@ -1,20 +1,23 @@
 # NativeLink Docs
 
-### Development
-
-Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+### Installation
 
 ```
-npm i -g mintlify
+$ yarn
 ```
 
-Run the following command at the root of your documentation (where mint.json is)
+### Local Development
 
 ```
-mintlify dev
+$ yarn start
 ```
 
-#### Troubleshooting
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
 
-- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
-- Page loads as a 404 - Make sure you are running in a folder with `mint.json`
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
diff --git a/nativelink-docs/babel.config.js b/nativelink-docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/nativelink-docs/about.mdx → nativelink-docs/docs/About.mdx b/nativelink-docs/about.mdx → nativelink-docs/docs/About.mdx
@@ -1,16 +1,12 @@
 ---
-title: About
+sidebar_position: 4
+title: 'About'
 description: 'What is NativeLink?'
 ---
 
-<img
-  className="block dark:hidden"
-  src="/images/hero-dark.png"
-  alt="Hero Light"
-/>
 <img
   className="hidden dark:block"
-  src="/images/hero-dark.png"
+  src="/img/hero-dark.png"
   alt="Hero Dark"
 />
 
@@ -23,20 +19,15 @@ such as [Bazel](https://bazel.build), [Buck2](https://buck2.build),
 
 Supports Unix-based operating systems and Windows.
 
-**🎯 Goals**
-<Steps>
-  <Step title="Stability">
-    Things should work out of the box as expected.
-  </Step>
-  <Step title="Efficiency">
-    Don't waste time on inefficiencies &amp; low resource usage.
-  </Step>
-  <Step title="User First">
-    Design choices should be optimized for what users want.
-  </Step>
-</Steps>
-
-**🏺 History**
+## 🎯 Goals
+
+**1. Things should work out of the box as expected.**
+
+**2. Don't waste time on inefficiencies &amp; low resource usage.**
+
+**3. Design choices should be optimized for what users want.**
+
+## 🏺 History
 
 This project was first created due to frustration with similar projects not
 working or being extremely inefficient. Rust was chosen as the language to

diff --git a/nativelink-docs/contributing.mdx → nativelink-docs/docs/Contributing.mdx b/nativelink-docs/contributing.mdx → nativelink-docs/docs/Contributing.mdx
@@ -1,14 +1,21 @@
 ---
+sidebar_position: 3
 title: 'Contributing'
 description: 'Learn how to contribute to NativeLink'
 ---
 
-<Info>
+:::info
+
   **Prerequisite** You should have Rust installed (version 1.71.0 or
   higher).
-</Info>
 
-<Warning>MacOS and Windows developers will not be able to run the full unit-test suite, which is necessary for contributing. Follow the Docker instructions in quickstart to get docker set up with NativeLink.</Warning>
+:::
+
+:::warning
+
+MacOS and Windows developers will not be able to run the full unit-test suite, which is necessary for contributing. Follow the Docker instructions in quickstart to get docker set up with NativeLink.
+
+:::
 
 ## Fork the repository
 
@@ -26,7 +33,11 @@ Should you wish to work on an issue, please claim it first by commenting on
 the GitHub issue that you want to work on it. This is to prevent duplicated
 efforts from contributors on the same issue.
 
-<Tip>Look for the `good first issue` label or ask contributors in comments if something is a good issue to get started with!</Tip>
+:::tip
+
+Look for the `good first issue` label or ask contributors in comments if something is a good issue to get started with!
+
+:::
 
 ## Pull Request Checklist
 
@@ -54,7 +65,11 @@ efforts from contributors on the same issue.
 
 - Unit-tests run with `bazel test //..` must pass locally.
 
-<Note>See Quickstart if having trouble running unit tests.</Note>
+:::note
+
+See Quickstart if having trouble running unit tests.
+
+:::
 
 - If `rustfmt` complains you can use the following command to apply its
   suggested changes to the Rust sources:

diff --git a/nativelink-docs/quickstart.mdx → nativelink-docs/docs/Quickstart.mdx b/nativelink-docs/quickstart.mdx → nativelink-docs/docs/Quickstart.mdx
@@ -1,23 +1,30 @@
 ---
+slug: /
+sidebar_position: 1
 title: 'Quickstart'
-description: 'Getting started with NativeLink remote execution in <5 minutes'
+description: 'Getting started with NativeLink remote execution in <5 minutes.'
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 ## 🦀 Installing with Cargo
 
 Install or Update Rust
 
-<CodeGroup>
+<Tabs>
+  <TabItem value="install" label="Install" default>
+    ```bash
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    ```
+  </TabItem>
 
-```shell  Install
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-```
-
-```shell Update
-rustup update
-```
-</CodeGroup>
+  <TabItem value="update" label="Update">
+    ```shell
+    rustup update
+    ```
+  </TabItem>
+</Tabs>
 
 ```bash
 cargo install --git https://github.com/TraceMachina/nativelink
@@ -43,21 +50,28 @@ cas basic_cas.json
 
 ## 🧪 Evaluating Native Link
 
-<Note>If Bazel is not installed follow the instructions below based on your
-machine.</Note>
+:::note
 
-<CodeGroup>
+If Bazel is not installed follow the instructions below based on your
+machine.
 
-```shell Linux
+:::
+
+<Tabs>
+
+<TabItem value="linux" label="Linux" default>
+```bash
 apt install -y gcc g++ lld python3 curl
 
 sudo apt update && sudo apt install bazel
 
 # Verify the installation.
 bazel --version
 ```
+</TabItem>
 
-```shell Docker-ARM
+<TabItem value="dockerArm" label="Docker-ARM">
+```bash
 # The commands for creating docker containers can fill up space very quickly when run frequently.
 # If `apt update` throws an out of space error you can run `docker system prune`
 # to free up space. Be careful to make sure it's not removing any containers/images you want to keep.
@@ -83,8 +97,10 @@ mv bazel-6.4.0-linux-arm64 /usr/local/bin/bazel
 bazel --version
 
 ```
+</TabItem>
 
-```shell Docker-x86
+<TabItem value="dockerx" label="Docker-x86">
+```shell
 # The commands for creating docker containers can fill up space very quickly
 # when run frequently. If `apt update` throws an out of space error you can
 # run `docker system prune` to free up space. Be careful to make sure it's
@@ -111,8 +127,10 @@ mv bazel-6.4.0-linux-x86_64 /usr/local/bin/bazel
 bazel --version
 
 ```
+</TabItem>
 
-```shell MacOS (Beta)
+<TabItem value="macOS (Beta)" label="MacOS">
+```shell
 # It is recommended to use x86 Docker for Intel Macs and ARM Docker for Silicon Macs.
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
@@ -121,8 +139,9 @@ brew install bazel
 # Verify the installation.
 bazel --version
 ```
+</TabItem>
 
-</CodeGroup>
+</Tabs>
 
 Once you've built Native Link and have an instance running with the
 `basic_cas.json` configuration, launch a separate terminal session and run the
@@ -149,7 +168,7 @@ bazel test //... `
 This causes Bazel to run the commands through an all-in-one `CAS`, `scheduler`
 and `worker`.
 
-🎉 Tada 🎉 Native Link is working.
+**🎉 Tada 🎉 Native Link is working.**
 
 ## 🌱 Building with Bazel
 
@@ -158,9 +177,12 @@ and `worker`.
 * Bazel 6.4.0+
 * A recent C++ toolchain with LLD as linker
 
-> [!TIP]
-> This build supports Nix/direnv which provides Bazel but no C++ toolchain
-> (yet).
+:::tip
+
+This build supports Nix/direnv which provides Bazel but no C++ toolchain
+(yet).
+
+:::
 
 The following commands place an executable in `./bazel-bin/cas/cas` and start
 the service:
@@ -179,7 +201,11 @@ bazel run --config=windows cas -- ./nativelink-config/examples/basic_cas.json
 bazel run --config=windows -c opt cas -- ./nativelink-config/examples/basic_cas.json
 ```
 
-<Note>The `--release` flag causes link-time-optmization to be enabled, which can take a while to compile, but will result in a much faster binary.</Note>
+:::note
+
+The `--release` flag causes link-time-optmization to be enabled, which can take a while to compile, but will result in a much faster binary.
+
+:::
 
 ## 🦀 Building with Cargo
 
@@ -188,9 +214,12 @@ bazel run --config=windows -c opt cas -- ./nativelink-config/examples/basic_cas.
 * Cargo 1.74.0+
 * A recent C++ toolchain with LLD as linker
 
-> [!TIP]
-> This build supports Nix/direnv which provides Cargo but no C++
-> toolchain/stdenv (yet).
+:::tip
+
+This build supports Nix/direnv which provides Cargo but no C++
+toolchain/stdenv (yet).
+
+:::
 
 ```bash
 # Unoptimized development build
@@ -229,18 +258,6 @@ export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)
 cosign verify ghcr.io/tracemachina/nativelink:${LATEST} \
     --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
     --certificate-oidc-issuer=https://token.actions.githubusercontent.com
-
-
-For use in production pin the image to a specific revision:
-
-```sh
-# Get the tag for a specific commit
-export PINNED_TAG=$(nix eval github:TraceMachina/nativelink/<revision>#image.imageTag --raw)
-
-# Verify the signature
-cosign verify ghcr.io/tracemachina/nativelink:${PINNED_TAG} \
-    --certificate-identity=https://github.com/TraceMachina/nativelink/.github/workflows/image.yaml@refs/heads/main \
-    --certificate-oidc-issuer=https://token.actions.githubusercontent.com
 ```
 
 For use in production pin the executable to a specific revision: