From 4642442a956c016b3d15fc534971f7871ae4c9b2 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 1 Mar 2024 00:19:27 -0800
Subject: [PATCH 1/5] Add CLI docs

---
 .../sparo-lib/src/cli/commands/ci-checkout.ts |   2 +-
 .../docs/pages/ci_commands/overview.md        |  19 ++++
 .../pages/ci_commands/sparo-ci_checkout.md    |  17 +++
 .../docs/pages/ci_commands/sparo-ci_clone.md  |  18 +++
 apps/website/docs/pages/commands/overview.md  |  22 ++--
 .../docs/pages/commands/sparo_auto-config.md  |  34 ++++++
 .../docs/pages/commands/sparo_checkout.md     |  23 ++++
 .../docs/pages/commands/sparo_clone.md        |  24 ++++
 .../docs/pages/commands/sparo_fetch.md        |  16 +++
 .../docs/pages/commands/sparo_git-checkout.md |  17 +++
 .../docs/pages/commands/sparo_git-clone.md    |  19 ++++
 .../docs/pages/commands/sparo_git-fetch.md    |  15 +++
 .../docs/pages/commands/sparo_init-profile.md |  13 +++
 .../pages/commands/sparo_list-profiles.md     |  14 +++
 .../docs/pages/guide/sparo_profiles.md        | 103 ++++++++++++++++++
 apps/website/docs/pages/support/help.md       |   4 +-
 apps/website/sidebars.js                      |  23 +++-
 17 files changed, 371 insertions(+), 12 deletions(-)
 create mode 100644 apps/website/docs/pages/ci_commands/overview.md
 create mode 100644 apps/website/docs/pages/ci_commands/sparo-ci_checkout.md
 create mode 100644 apps/website/docs/pages/ci_commands/sparo-ci_clone.md
 create mode 100644 apps/website/docs/pages/commands/sparo_auto-config.md
 create mode 100644 apps/website/docs/pages/commands/sparo_checkout.md
 create mode 100644 apps/website/docs/pages/commands/sparo_clone.md
 create mode 100644 apps/website/docs/pages/commands/sparo_fetch.md
 create mode 100644 apps/website/docs/pages/commands/sparo_git-checkout.md
 create mode 100644 apps/website/docs/pages/commands/sparo_git-clone.md
 create mode 100644 apps/website/docs/pages/commands/sparo_git-fetch.md
 create mode 100644 apps/website/docs/pages/commands/sparo_init-profile.md
 create mode 100644 apps/website/docs/pages/commands/sparo_list-profiles.md

diff --git a/apps/sparo-lib/src/cli/commands/ci-checkout.ts b/apps/sparo-lib/src/cli/commands/ci-checkout.ts
index aef30a8..fc7452f 100644
--- a/apps/sparo-lib/src/cli/commands/ci-checkout.ts
+++ b/apps/sparo-lib/src/cli/commands/ci-checkout.ts
@@ -13,7 +13,7 @@ export interface ICICheckoutCommandOptions {
 export class CICheckoutCommand implements ICommand<ICICheckoutCommandOptions> {
   public cmd: string = 'checkout';
   public description: string =
-    'Special checkout command for CI. It only accepts project selector suchs as --to and --from now.';
+    'Special checkout command for CI. It only accepts project selector such as --to and --from now.';
   @inject(GitSparseCheckoutService) private _gitSparseCheckoutService!: GitSparseCheckoutService;
   public builder(yargs: Argv<ICICheckoutCommandOptions>): void {
     yargs
diff --git a/apps/website/docs/pages/ci_commands/overview.md b/apps/website/docs/pages/ci_commands/overview.md
new file mode 100644
index 0000000..ab79a0b
--- /dev/null
+++ b/apps/website/docs/pages/ci_commands/overview.md
@@ -0,0 +1,19 @@
+---
+title: Overview
+---
+
+Everyday development involves a variety of Git operations such as switching between branches, fetching incremental changes from the server, and browsing history.  By contrast, when a continuous integration (CI) pipeline checks out a Git branch, it is typically a much simpler operation, and the folder or entire virtual machine image may be discarded as soon as the job completes.  Therefore, different approaches for optimizing Git require required for these two use cases.
+
+Sparo provides a separate command line `sparo-ci` that is specifically optimized for CI pipelines.  The current implementation takes this approach:
+
+- It uses [treeless clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) instead of **blobless clone**, under the assumption that Git history will be rarely needed.
+
+  _Shallow clone is a common alternative, however it has trouble supporting operations such as incremental build or publishing that require comparison with a base branch._
+
+- Spare checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
+
+Currently two subcommands are supported for CI:
+
+- `sparo-ci checkout`
+- `sparo-ci clone`
+
diff --git a/apps/website/docs/pages/ci_commands/sparo-ci_checkout.md b/apps/website/docs/pages/ci_commands/sparo-ci_checkout.md
new file mode 100644
index 0000000..6e020fc
--- /dev/null
+++ b/apps/website/docs/pages/ci_commands/sparo-ci_checkout.md
@@ -0,0 +1,17 @@
+---
+title: sparo-ci checkout
+---
+
+```
+sparo-ci checkout
+
+Special checkout command for CI. It only accepts project selector such as --to
+and --from now.
+
+Options:
+      --help  Show help                                                [boolean]
+  -t, --to    See https://rushjs.io/pages/developer/selecting_subsets/#--to for
+              more details.                                              [array]
+  -f, --from  See https://rushjs.io/pages/developer/selecting_subsets/#--from
+              for more details.                                          [array]
+```
diff --git a/apps/website/docs/pages/ci_commands/sparo-ci_clone.md b/apps/website/docs/pages/ci_commands/sparo-ci_clone.md
new file mode 100644
index 0000000..a5453b3
--- /dev/null
+++ b/apps/website/docs/pages/ci_commands/sparo-ci_clone.md
@@ -0,0 +1,18 @@
+---
+title: sparo-ci clone
+---
+
+```
+sparo-ci clone <repository> [directory]
+
+Positionals:
+  repository  The remote repository to clone from.           [string] [required]
+  directory   The name of a new directory to clone into. The "humanish" part of
+              the source repository is used if no directory is explicitly given
+              (repo for /path/to/repo.gitService and foo for
+              host.xz:foo/.gitService). Cloning into an existing directory is
+              only allowed if the directory is empty                    [string]
+
+Options:
+  --help  Show help                                                    [boolean]
+```
diff --git a/apps/website/docs/pages/commands/overview.md b/apps/website/docs/pages/commands/overview.md
index 07514bc..a445edb 100644
--- a/apps/website/docs/pages/commands/overview.md
+++ b/apps/website/docs/pages/commands/overview.md
@@ -9,25 +9,27 @@ Sparo has four kinds of subcommands:
 1. **Mirrored subcommands** such as `sparo branch` and `sparo revert` directly invoke the corresponding `git` version of that subcommand.  The motivation for using mirrored subcommands is to enable Sparo to provide advice about parameters that may cause performance issues.  Additionally, you can optionally configure Sparo to collect anonymized usage metrics to help you measure the experience in your repository.  (Collected data is sent to your own service. It is not accessible by any other party.)
 
 2. **Enhanced subcommands** follow the same basic design as their `git` counterparts, but with adaptations for sparse checkout profiles and more efficient defaults.  There are four enhanced commands:
-   - `sparo clone`
    - `sparo checkout`
+   - `sparo clone`
    - `sparo fetch`
-   - `sparo pull`
+   - `sparo pull` (not implemented yet; currently mirrors `git pull`)
 
 3. **Renamed subcommands** are the mirrored versions of the four enhanced subcommands. They are renamed to add a `git-` prefix:
-  - `sparo git-clone`
   - `sparo git-checkout`
+  - `sparo git-clone`
   - `sparo git-fetch`
-  - `sparo git-pull`.
+  - `sparo git-pull` (not implemented yet)
 
 4. **Auxiliary subcommands** are new subcommands that provide Sparo-specific functionality.  They are:
-  - `sparo purge`
-  - `sparo list-profiles`
+  - `sparo auto-config`
   - `sparo init-profile`
+  - `sparo list-profiles`
+  - `sparo inspect` (not implemented yet, reports working directory status and diagnostics)
+  - `sparo reclone` (not implemented yet, will efficiently revert to a clean clone)
 
 ## Mirrored commands
 
-Each subcommand has its own page in this documentation, except for the mirrored commands which are already covered by the Git documentation.  For convenience, their names are listed in the table below.
+Each subcommand has its own page in this documentation, except for the mirrored commands which are already covered by the Git documentation.  For convenience, the most essential ["porcelain"](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) subcommands are listed in the table below, however every Git subcommand is supported.
 
 | Subcommand | Summary |
 | --- | --- |
@@ -71,4 +73,8 @@ Each subcommand has its own page in this documentation, except for the mirrored
 | [git stash](https://git-scm.com/docs/git-stash) | Stash the changes in a dirty working directory away |
 | [git status](https://git-scm.com/docs/git-status) | Show the working tree status |
 | [git submodule](https://git-scm.com/docs/git-submodule) | Initialize, update or inspect submodules |
-| [git switch](https://git-scm.com/docs/git-switch) |
+| [git switch](https://git-scm.com/docs/git-switch) | Switch branches |
+| [git tag](https://git-scm.com/docs/git-tag) | Create, list, delete or verify a tag object signed with GPG |
+| [git worktree](https://git-scm.com/docs/git-worktree) | Manage multiple working trees |
+| . . . | _...and many other subcommands including any custom commands found in the shell `PATH`_ |
+
diff --git a/apps/website/docs/pages/commands/sparo_auto-config.md b/apps/website/docs/pages/commands/sparo_auto-config.md
new file mode 100644
index 0000000..8165a10
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_auto-config.md
@@ -0,0 +1,34 @@
+---
+title: sparo auto-config
+---
+
+```
+sparo auto-config
+
+Automatic setup optimized git config
+
+Options:
+  --help       Show help                                               [boolean]
+  --overwrite                                         [boolean] [default: false]
+```
+
+You do not normally need to invoke `sparo auto-config`.  As the name implies, it is automatically applied by `sparo clone`.  This command is provided for reapplying the configuration in a situation where the user may have manually altered Sparo's configuration.  It is a good first step when investigating problems.
+
+## Auto-config settings
+
+The implementation can be found in [GitService.ts](https://github.com/tiktok/sparo/blob/main/apps/sparo-lib/src/services/GitService.ts).  Below is a summary of the currently applied settings:
+
+```
+pull.rebase=true
+fetch.prune=true
+fetch.showForcedUpdates=false
+feature.manyFiles=true
+core.fsmonitor=true
+core.fscache=true
+core.untrackedcache=true
+om-my-zsh.hide-status=1
+on-my-zsh.hide-dirty=1
+lfs.allowincompletepush=true
+lfs.concurrenttransfers=32
+push.autoSetupRemote=true
+```
diff --git a/apps/website/docs/pages/commands/sparo_checkout.md b/apps/website/docs/pages/commands/sparo_checkout.md
new file mode 100644
index 0000000..e28608c
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_checkout.md
@@ -0,0 +1,23 @@
+---
+title: sparo checkout
+---
+
+```
+sparo checkout [branch] [start-point]
+
+Updates files in the working tree to match the version in the index or the
+specified tree. If no pathspec was given, git checkout will also update HEAD to
+set the specified branch as the current branch.
+
+Positionals:
+  branch                                                                [string]
+  start-point                                                           [string]
+
+Options:
+      --help         Show help                                         [boolean]
+  -b                 Create a new branch and start it at <start-point> [boolean]
+  -B                 Create a new branch and start it at <start-point>; if it
+                     already exists, reset it to <start-point>         [boolean]
+      --profile                                            [array] [default: []]
+      --add-profile                                        [array] [default: []]
+```
diff --git a/apps/website/docs/pages/commands/sparo_clone.md b/apps/website/docs/pages/commands/sparo_clone.md
new file mode 100644
index 0000000..f06de92
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_clone.md
@@ -0,0 +1,24 @@
+---
+title: sparo clone
+---
+
+```
+sparo clone <repository> [directory]
+
+Positionals:
+  repository  The remote repository to clone from.           [string] [required]
+  directory   The name of a new directory to clone into. The "humanish" part of
+              the source repository is used if no directory is explicitly given
+              (repo for /path/to/repo.gitService and foo for
+              host.xz:foo/.gitService). Cloning into an existing directory is
+              only allowed if the directory is empty                    [string]
+
+Options:
+      --help             Show help                                     [boolean]
+  -s, --skip-git-config  By default, Sparo automatically configures the
+                         recommended git settings for the repository you are
+                         about to clone. If you prefer not to include this step,
+                         you can use the input parameter --skip-git-config
+                                                      [boolean] [default: false]
+  -b, --branch           Specify a branch to clone                      [string]
+```
\ No newline at end of file
diff --git a/apps/website/docs/pages/commands/sparo_fetch.md b/apps/website/docs/pages/commands/sparo_fetch.md
new file mode 100644
index 0000000..d81d586
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_fetch.md
@@ -0,0 +1,16 @@
+---
+title: sparo fetch
+---
+
+```
+sparo fetch [remote] [branch]
+
+fetch remote branch to local
+
+Positionals:
+  remote                                                                [string]
+  branch                                                                [string]
+
+Options:
+  --help  Show help                                                    [boolean]
+```
\ No newline at end of file
diff --git a/apps/website/docs/pages/commands/sparo_git-checkout.md b/apps/website/docs/pages/commands/sparo_git-checkout.md
new file mode 100644
index 0000000..fdda909
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_git-checkout.md
@@ -0,0 +1,17 @@
+---
+title: sparo git-checkout
+---
+
+This is the [mirrored subcommand](./overview.md) for `git checkout`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-checkout [-q] [-f] [-m] [<branch>]
+sparo git-checkout [-q] [-f] [-m] --detach [<branch>]
+sparo git-checkout [-q] [-f] [-m] [--detach] <commit>
+sparo git-checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+sparo git-checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>…​
+sparo git-checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
+sparo git-checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
+```
+
+See [git checkout](https://git-scm.com/docs/git-checkout) in the Git documentation for details.
diff --git a/apps/website/docs/pages/commands/sparo_git-clone.md b/apps/website/docs/pages/commands/sparo_git-clone.md
new file mode 100644
index 0000000..d85bb70
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_git-clone.md
@@ -0,0 +1,19 @@
+---
+title: sparo git-clone
+---
+
+This is the [mirrored subcommand](./overview.md) for `git clone`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-clone [--template=<template-directory>]
+	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
+	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+	  [--dissociate] [--separate-git-dir <git-dir>]
+	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
+	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
+	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
+	  [--filter=<filter> [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
+```
+
+See [git clone](https://git-scm.com/docs/git-clone) in the Git documentation for details.
diff --git a/apps/website/docs/pages/commands/sparo_git-fetch.md b/apps/website/docs/pages/commands/sparo_git-fetch.md
new file mode 100644
index 0000000..fc3089c
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_git-fetch.md
@@ -0,0 +1,15 @@
+---
+title: sparo git-fetch
+---
+
+This is the [mirrored subcommand](./overview.md) for `git fetch`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-fetch [<options>] [<repository> [<refspec>…​]]
+sparo git-fetch [<options>] <group>
+sparo git-fetch --multiple [<options>] [(<repository> | <group>)…​]
+sparo git-fetch --all [<options>]
+```
+
+See [git fetch](https://git-scm.com/docs/git-fetch) in the Git documentation for details.
+
diff --git a/apps/website/docs/pages/commands/sparo_init-profile.md b/apps/website/docs/pages/commands/sparo_init-profile.md
new file mode 100644
index 0000000..41cfc3e
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_init-profile.md
@@ -0,0 +1,13 @@
+---
+title: sparo init-profile
+---
+
+```
+sparo init-profile
+
+Initialize a new profile.
+
+Options:
+  --help     Show help                                                 [boolean]
+  --profile  The name of the profile to initialize.          [string] [required]
+```
\ No newline at end of file
diff --git a/apps/website/docs/pages/commands/sparo_list-profiles.md b/apps/website/docs/pages/commands/sparo_list-profiles.md
new file mode 100644
index 0000000..bcbf010
--- /dev/null
+++ b/apps/website/docs/pages/commands/sparo_list-profiles.md
@@ -0,0 +1,14 @@
+---
+title: sparo list-profiles
+---
+
+```
+sparo list-profiles
+
+List all available profiles or query profiles that contain the specified project
+name
+
+Options:
+  --help     Show help                                                 [boolean]
+  --project  List all profiles contains this specified project name     [string]
+```
diff --git a/apps/website/docs/pages/guide/sparo_profiles.md b/apps/website/docs/pages/guide/sparo_profiles.md
index d06d988..a1422c8 100644
--- a/apps/website/docs/pages/guide/sparo_profiles.md
+++ b/apps/website/docs/pages/guide/sparo_profiles.md
@@ -2,3 +2,106 @@
 title: Sparo profiles
 ---
 
+Git's sparse checkout feature normally relies on a collection of glob patterns that are stored in the `.git/info/sparse-checkout` config file.  Normal glob syntax proved to be too inefficient, so Git instead uses ["cone mode"](https://git-scm.com/docs/git-sparse-checkout#_internalsnon_cone_problems) that ignores file-matching patterns and only matches directories.
+
+The syntax looks something like this:
+
+**.git/info/sparse-checkout  example**
+```
+/*
+!/*/
+/apps/
+!/apps/*/
+/apps/my-app/
+!/apps/my-app/*/
+/apps/my-app/_/
+```
+
+To simplify management, the `git sparse-checkout` command line provides convenient ways to add/remove patterns from this file.  However, in a large monorepo with hundreds of projects, managing these globs can be confusing and error-prone.
+
+Sparo's approach is to generate the `.git/info/sparse-checkout` configuration from config files called profiles.  This provides many benefits:
+
+- Profiles are specified using [project selectors](https://rushjs.io/pages/developer/selecting_subsets/#--to), for example: _"Give me **app1**, **app2**, and all the projects needed to build them."_ This is more concise and maintainable than specifying globs.
+
+- Profiles are stored in a config file and committed to Git.  This makes it easy to share them with your teammates.
+
+- Profiles are automatically updated when switching between branches, which ensures deterministic results.  For example, when checking out a very old branch, you want the old profile definition, not today's version of it.
+
+- You combine multiple profiles at the same time (`sparo checkout --profile team1 --profile team2`), which produces the union of their subsets.  This is useful for example when modifying a library project that is consumed by projects belonging to several other teams.  You could instead use a selector `--from the-library` of course, but it's likely those other teams have included other relevant projects in their profiles.
+
+- Sparo avoids common mistakes by imposing additional restrictions beyond `git sparse-checkout`.
+
+## Best practices for profiles
+
+You an add JSON comments to your profile config files.  In a large shared codebase, we recommend adding a standardized header to the top of your files indicating their ownership and purpose.  Something like this:
+
+**common/sparo-profiles/example-profile.json**
+```js
+/**
+ * OWNER:   Customer service team
+ * PURPOSE: Use this profile when working on the customer service apps.
+ */
+{
+  "$schema": "https://tiktok.github.io/sparo/schemas/sparo-profile.schema.json",
+
+  /**
+   * A list of Rush project selectors indicating the project folders to be
+   * included for sparse checkout.  The selectors will be combined to make
+   * the union superset of projects.  See the Rush selector docs for details:
+   * https://rushjs.io/pages/developer/selecting_subsets/
+   */
+  "selections": [
+     {
+        "selector": "--to",
+        "argument": "tag:cs-dashboard"
+     },
+     {
+        "selector": "--to",
+        "argument": "tag:cs-tools"
+     }
+  ]
+}
+```
+
+## Combining profiles
+
+The simple way to combine profiles is to specify `--profile` multiple times.  For example:
+
+```shell
+# Check out the union of profiles team-a.json, team-b.json, team-c.json
+# NOTE: This will replace whatever profile selection was already checked out.
+sparo checkout --profile team-a --profile team-b --profile team-c
+```
+
+You can also use `--add-profile` to incrementally combine them.  For example:
+
+```shell
+# These three commands are equivalent to the above command.
+sparo checkout --profile team-a
+sparo checkout --add-profile team-b
+sparo checkout --add-profile team-c
+```
+
+How to checkout NO profile? In other words, returning to the [skeleton](../reference/skeleton_folders.md) state of a clean `sparo clone`?  It can't be `sparo checkout`, because if `--profile` is entirely omitted then the existing profile selection is preserved.
+
+```shell
+# NOT IMPLEMENTED YET - check out just the skeleton folders
+# without applying any profiles
+sparo checkout --no-profile
+```
+
+
+## Querying profiles
+
+Engineers can find available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
+
+```shell
+# Suppose you need to make a fix for the "example-app" project.
+
+# Which sparse checkout profiles include the "example-app" project?
+sparo list-profiles --project example-app
+
+# Great, let's add the "example-profile" result to our current checkout
+# (combining it with the existing profile).
+sparo checkout --add-profile example-profile
+```
diff --git a/apps/website/docs/pages/support/help.md b/apps/website/docs/pages/support/help.md
index 6e08b15..a99a5e5 100644
--- a/apps/website/docs/pages/support/help.md
+++ b/apps/website/docs/pages/support/help.md
@@ -2,6 +2,6 @@
 title: Getting help
 ---
 
-If you encounter questions or problems, please [create a GitHub issue](https://github.com/tiktok/sparo/issues/new/choose).
+Please [create a GitHub issue](https://github.com/tiktok/sparo/issues/new/choose) to report any problems or feature requests.
 
-Additional support channels are coming soon.
+For general questions, please use our [GitHub Discussions](https://github.com/tiktok/sparo/discussions) forum.
diff --git a/apps/website/sidebars.js b/apps/website/sidebars.js
index de58800..b5fbcb9 100644
--- a/apps/website/sidebars.js
+++ b/apps/website/sidebars.js
@@ -56,7 +56,28 @@ const sidebars = {
       type: 'category',
       label: 'Commands',
       collapsible: false,
-      items: ['pages/commands/overview']
+      items: [
+        'pages/commands/overview',
+        'pages/commands/sparo_auto-config',
+        'pages/commands/sparo_checkout',
+        'pages/commands/sparo_clone',
+        'pages/commands/sparo_fetch',
+        'pages/commands/sparo_git-checkout',
+        'pages/commands/sparo_git-clone',
+        'pages/commands/sparo_git-fetch',
+        'pages/commands/sparo_init-profile',
+        'pages/commands/sparo_list-profiles'
+      ]
+    },
+    {
+      type: 'category',
+      label: 'CI Commands',
+      collapsible: false,
+      items: [
+        'pages/ci_commands/overview',
+        'pages/ci_commands/sparo-ci_checkout',
+        'pages/ci_commands/sparo-ci_clone'
+      ]
     },
     {
       type: 'category',

From 86d3b0c3d87383944fd4e87bd8479908c7de278a Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 1 Mar 2024 00:21:35 -0800
Subject: [PATCH 2/5] rush change

---
 .../sparo/octogonz-more-docs_2024-03-01-08-21.json     | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 common/changes/sparo/octogonz-more-docs_2024-03-01-08-21.json

diff --git a/common/changes/sparo/octogonz-more-docs_2024-03-01-08-21.json b/common/changes/sparo/octogonz-more-docs_2024-03-01-08-21.json
new file mode 100644
index 0000000..6b6ce60
--- /dev/null
+++ b/common/changes/sparo/octogonz-more-docs_2024-03-01-08-21.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "sparo",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "sparo"
+}
\ No newline at end of file

From 8f6dd74dab41ac2a1f18d997458254501e8f246b Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 1 Mar 2024 00:24:14 -0800
Subject: [PATCH 3/5] Remove the under construction banner now that the basic
 docs are complete

---
 apps/website/docs/index.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/apps/website/docs/index.md b/apps/website/docs/index.md
index 67e398e..7f7c520 100644
--- a/apps/website/docs/index.md
+++ b/apps/website/docs/index.md
@@ -16,12 +16,7 @@ import { ThemedImage } from '@site/src/components/ThemedImage';
     />
 </div>
 
-> 🚧 UNDER CONSTRUCTION 🚧
->
-> This is an early test release of the software.
-> It is not yet ready for general usage.
-> If you have questions about this project, let us know
-> using [GitHub discussions](https://github.com/tiktok/sparo/discussions).
+
 
 ## Clone faster!
 

From 77ddc264b536979e40a52116ccba01e7d9c5413a Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 1 Mar 2024 00:40:46 -0800
Subject: [PATCH 4/5] Editing

---
 apps/website/README.md                        |  8 +++----
 apps/website/docs/index.md                    |  6 ++---
 .../docs/pages/ci_commands/overview.md        |  4 ++--
 apps/website/docs/pages/commands/overview.md  |  8 +++----
 .../docs/pages/guide/getting_started.md       |  8 +++----
 .../docs/pages/guide/sparo_profiles.md        | 24 +++++++++----------
 apps/website/docs/pages/reference/security.md |  8 +++----
 .../docs/pages/support/contributing.md        | 10 ++++----
 8 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/apps/website/README.md b/apps/website/README.md
index 281a505..dd57c79 100644
--- a/apps/website/README.md
+++ b/apps/website/README.md
@@ -6,14 +6,14 @@ This is the [Docusaurus](https://docusaurus.io/) project for the Sparo website.
 
 1. Install the monorepo dependencies using [RushJS](https://rushjs.io/):
 
-   ```shell
+   ```bash
    rush install
    rush build
    ```
 
 2. Launch the local development server:
 
-   ```shell
+   ```bash
    cd apps/website
    rushx start
    ```
@@ -33,14 +33,14 @@ Notes:
 
 1. If you will manually copy the files to a server, you can build the **apps/sparo/build** folder like this:
 
-   ```shell
+   ```bash
    cd apps/website
    rushx build
    ```
 
 2. To automatically deploy to GitHub Pages (as an administrator):
 
-   ```shell
+   ```bash
    # If you are using HTTPS authentication for GitHub:
    cd apps/website
    GIT_USER=<Your GitHub username> rushx deploy
diff --git a/apps/website/docs/index.md b/apps/website/docs/index.md
index 7f7c520..924221b 100644
--- a/apps/website/docs/index.md
+++ b/apps/website/docs/index.md
@@ -48,7 +48,7 @@ Try out Sparo in 5 easy steps:
 
 2. Clone your [RushJS](https://rushjs.io/) monorepo:
 
-   ```shell
+   ```bash
    sparo clone https://github.com/my-company/my-monorepo.git
    ```
 
@@ -76,7 +76,7 @@ Try out Sparo in 5 easy steps:
 
 4. Check out your Sparo profile:
 
-   ```shell
+   ```bash
    sparo checkout --profile my-team
    ```
 
@@ -84,7 +84,7 @@ Try out Sparo in 5 easy steps:
 
    Examples:
 
-   ```shell
+   ```bash
    sparo pull
 
    sparo commit -m "Example command"
diff --git a/apps/website/docs/pages/ci_commands/overview.md b/apps/website/docs/pages/ci_commands/overview.md
index ab79a0b..e5edad2 100644
--- a/apps/website/docs/pages/ci_commands/overview.md
+++ b/apps/website/docs/pages/ci_commands/overview.md
@@ -2,7 +2,7 @@
 title: Overview
 ---
 
-Everyday development involves a variety of Git operations such as switching between branches, fetching incremental changes from the server, and browsing history.  By contrast, when a continuous integration (CI) pipeline checks out a Git branch, it is typically a much simpler operation, and the folder or entire virtual machine image may be discarded as soon as the job completes.  Therefore, different approaches for optimizing Git require required for these two use cases.
+Everyday development involves a variety of Git operations such as switching between branches, fetching incremental changes from the server, and browsing history.  By contrast, when a continuous integration (CI) pipeline checks out a Git branch, it is typically a much simpler operation. The folder or entire virtual machine image may be discarded as soon as the job completes.  Therefore, different approaches for optimizing Git require required for these two use cases.
 
 Sparo provides a separate command line `sparo-ci` that is specifically optimized for CI pipelines.  The current implementation takes this approach:
 
@@ -10,7 +10,7 @@ Sparo provides a separate command line `sparo-ci` that is specifically optimized
 
   _Shallow clone is a common alternative, however it has trouble supporting operations such as incremental build or publishing that require comparison with a base branch._
 
-- Spare checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
+- Sparse checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
 
 Currently two subcommands are supported for CI:
 
diff --git a/apps/website/docs/pages/commands/overview.md b/apps/website/docs/pages/commands/overview.md
index a445edb..9c8dec9 100644
--- a/apps/website/docs/pages/commands/overview.md
+++ b/apps/website/docs/pages/commands/overview.md
@@ -12,20 +12,20 @@ Sparo has four kinds of subcommands:
    - `sparo checkout`
    - `sparo clone`
    - `sparo fetch`
-   - `sparo pull` (not implemented yet; currently mirrors `git pull`)
+   - `sparo pull` _(not implemented yet; currently mirrors `git pull`)_
 
 3. **Renamed subcommands** are the mirrored versions of the four enhanced subcommands. They are renamed to add a `git-` prefix:
   - `sparo git-checkout`
   - `sparo git-clone`
   - `sparo git-fetch`
-  - `sparo git-pull` (not implemented yet)
+  - `sparo git-pull` _(not implemented yet)_
 
 4. **Auxiliary subcommands** are new subcommands that provide Sparo-specific functionality.  They are:
   - `sparo auto-config`
   - `sparo init-profile`
   - `sparo list-profiles`
-  - `sparo inspect` (not implemented yet, reports working directory status and diagnostics)
-  - `sparo reclone` (not implemented yet, will efficiently revert to a clean clone)
+  - `sparo inspect` _(not implemented yet, will report working directory status and diagnostics)_
+  - `sparo reclone` _(not implemented yet, will efficiently revert to a clean clone)_
 
 ## Mirrored commands
 
diff --git a/apps/website/docs/pages/guide/getting_started.md b/apps/website/docs/pages/guide/getting_started.md
index 4de21b8..e0fe6f7 100644
--- a/apps/website/docs/pages/guide/getting_started.md
+++ b/apps/website/docs/pages/guide/getting_started.md
@@ -19,7 +19,7 @@ Many Git optimizations are relatively new and not available in older versions of
 
 Clone your [RushJS](https://rushjs.io/) monorepo:
 
-```shell
+```bash
 sparo clone https://github.com/my-company/my-monorepo.git
 ```
 
@@ -64,7 +64,7 @@ The `--to` [project selector](https://rushjs.io/pages/developer/selecting_subset
 The `--profile` parameter can be included with `sparo checkout` (and in the future also `sparo clone` and `sparo pull`).  This parameter specifies the name of the JSON file to be selected.  You can also combine multiple profiles (`sparo checkout --profile p1 --profile p2`), in which case the union of their selections will be used.  (Combining profiles is an advanced scenario, but useful for example if your pull request will impact sets of projects belonging to multiple teams.)
 
 **Sparse checkout based on common/sparo-profiles/my-team.json**
-```shell
+```bash
 sparo checkout --profile my-team
 ```
 
@@ -75,7 +75,7 @@ sparo checkout --profile my-team
 - To checkout just the skeleton (returning to the initial state from Step 1 where no profile is chosen yet), specify `--no-profile` instead of `--profile NAME`.
 
 - To add more profiles, combining with your existing selection, use `--add-profile NAME` instead of `--profile NAME`.  For example, these two commands produce the same result as `sparo checkout --profile p1 --profile p2`:
-  ```shell
+  ```bash
   sparo checkout --profile p1
   sparo checkout --add-profile p2
   ```
@@ -86,7 +86,7 @@ For everyday work, consider choosing [mirrored subcommands](../commands/overview
 
 Examples:
 
-```shell
+```bash
 sparo pull
 
 sparo commit -m "Example command"
diff --git a/apps/website/docs/pages/guide/sparo_profiles.md b/apps/website/docs/pages/guide/sparo_profiles.md
index a1422c8..9e3f9b5 100644
--- a/apps/website/docs/pages/guide/sparo_profiles.md
+++ b/apps/website/docs/pages/guide/sparo_profiles.md
@@ -2,7 +2,7 @@
 title: Sparo profiles
 ---
 
-Git's sparse checkout feature normally relies on a collection of glob patterns that are stored in the `.git/info/sparse-checkout` config file.  Normal glob syntax proved to be too inefficient, so Git instead uses ["cone mode"](https://git-scm.com/docs/git-sparse-checkout#_internalsnon_cone_problems) that ignores file-matching patterns and only matches directories.
+Git's sparse checkout feature normally relies on a collection of glob patterns that are stored in the `.git/info/sparse-checkout` config file.  Normal glob syntax proved to be too inefficient, so Git instead uses a ["cone mode"](https://git-scm.com/docs/git-sparse-checkout#_internalsnon_cone_problems) glob interpretation that ignores file-matching patterns and only matches directories.
 
 The syntax looks something like this:
 
@@ -17,19 +17,19 @@ The syntax looks something like this:
 /apps/my-app/_/
 ```
 
-To simplify management, the `git sparse-checkout` command line provides convenient ways to add/remove patterns from this file.  However, in a large monorepo with hundreds of projects, managing these globs can be confusing and error-prone.
+To simplify management, the `git sparse-checkout` command line provides convenient ways to add/remove patterns from this file.  However, in a large monorepo with hundreds of projects, managing these globs would nonetheless be confusing and error-prone.
 
-Sparo's approach is to generate the `.git/info/sparse-checkout` configuration from config files called profiles.  This provides many benefits:
+Sparo makes life easier by generating the `.git/info/sparse-checkout` configuration automatically from config files called **profiles.**  This offers many benefits:
 
-- Profiles are specified using [project selectors](https://rushjs.io/pages/developer/selecting_subsets/#--to), for example: _"Give me **app1**, **app2**, and all the projects needed to build them."_ This is more concise and maintainable than specifying globs.
+- Sparo profiles are defined using [project selectors](https://rushjs.io/pages/developer/selecting_subsets/#--to), for example: _"Give me **app1**, **app2**, and all the projects needed to build them."_ This is more concise and maintainable than specifying globs.
 
 - Profiles are stored in a config file and committed to Git.  This makes it easy to share them with your teammates.
 
 - Profiles are automatically updated when switching between branches, which ensures deterministic results.  For example, when checking out a very old branch, you want the old profile definition, not today's version of it.
 
-- You combine multiple profiles at the same time (`sparo checkout --profile team1 --profile team2`), which produces the union of their subsets.  This is useful for example when modifying a library project that is consumed by projects belonging to several other teams.  You could instead use a selector `--from the-library` of course, but it's likely those other teams have included other relevant projects in their profiles.
+- You can combine multiple profiles together (`sparo checkout --profile team1 --profile team2`), which selects the union of their projects.  This is useful for example when modifying a library project that is consumed by projects belonging to several other teams.  You could check out their projects using `--from the-library` of course, but it's likely those other teams will have included other relevant projects in their profiles.
 
-- Sparo avoids common mistakes by imposing additional restrictions beyond `git sparse-checkout`.
+- Sparo avoids common mistakes by imposing additional restrictions beyond `git sparse-checkout`.  This avoids mistakes such as trying to switch to a profile that is missing a project folder containing files that are locally modified. It is better for users to stash or commit such modifications first.
 
 ## Best practices for profiles
 
@@ -67,7 +67,7 @@ You an add JSON comments to your profile config files.  In a large shared codeba
 
 The simple way to combine profiles is to specify `--profile` multiple times.  For example:
 
-```shell
+```bash
 # Check out the union of profiles team-a.json, team-b.json, team-c.json
 # NOTE: This will replace whatever profile selection was already checked out.
 sparo checkout --profile team-a --profile team-b --profile team-c
@@ -75,16 +75,16 @@ sparo checkout --profile team-a --profile team-b --profile team-c
 
 You can also use `--add-profile` to incrementally combine them.  For example:
 
-```shell
+```bash
 # These three commands are equivalent to the above command.
 sparo checkout --profile team-a
 sparo checkout --add-profile team-b
 sparo checkout --add-profile team-c
 ```
 
-How to checkout NO profile? In other words, returning to the [skeleton](../reference/skeleton_folders.md) state of a clean `sparo clone`?  It can't be `sparo checkout`, because if `--profile` is entirely omitted then the existing profile selection is preserved.
+How to checkout no profile at all? That is, how to return to the initial state of a clean `sparo clone` that only includes the [skeleton](../reference/skeleton_folders.md) folders?  If `--profile` is entirely omitted, then `sparo checkout` will preserve the existing profile selection.  Instead, the `--no-profile` parameter is needed:
 
-```shell
+```bash
 # NOT IMPLEMENTED YET - check out just the skeleton folders
 # without applying any profiles
 sparo checkout --no-profile
@@ -93,9 +93,9 @@ sparo checkout --no-profile
 
 ## Querying profiles
 
-Engineers can find available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
+Users can discover available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
 
-```shell
+```bash
 # Suppose you need to make a fix for the "example-app" project.
 
 # Which sparse checkout profiles include the "example-app" project?
diff --git a/apps/website/docs/pages/reference/security.md b/apps/website/docs/pages/reference/security.md
index a1e8dbd..3761c25 100644
--- a/apps/website/docs/pages/reference/security.md
+++ b/apps/website/docs/pages/reference/security.md
@@ -5,7 +5,7 @@ title: Security
 Because the Sparo tool acts as a wrapper for Git, our goal is to provide comparable security expectations as the `git` command.
 
 > ⚠️ **This is a goal not a guarantee.** ⚠️
-> 
+>
 > The software is still in its early stages of development, and not all security
 > requirements have been identified or implemented yet.  Efforts to improve Sparo
 > security should not be interpreted to contradict the terms of the MIT license:
@@ -48,15 +48,15 @@ And of course, if an explicit target folder is specified using `git clone https:
 
 Shell interpreters commonly transform expressions involving special characters such as `$`, `%`, `(`, etc.  For example:
 
-```shell
-# Problem: Bash would replace "$project" with the value of 
+```bash
+# Problem: Bash would replace "$project" with the value of
 # the environment variable whose name is "project".
 git clone https://github.com/example/project.git $project
 ```
 
 This requires escaping:
 
-```shell
+```bash
 # This backslash escape ensures that a literal dollar sign
 # is included in the created folder name:
 git clone https://github.com/example/project.git \$project
diff --git a/apps/website/docs/pages/support/contributing.md b/apps/website/docs/pages/support/contributing.md
index 0446d60..e4332a1 100644
--- a/apps/website/docs/pages/support/contributing.md
+++ b/apps/website/docs/pages/support/contributing.md
@@ -6,32 +6,32 @@ Building the projects in this monorepo:
 
 1. Install the [RushJS](https://rushjs.io/) tool:
 
-   ```shell
+   ```bash
    npm install -g @microsoft/rush
    ```
 
 2. Clone the repo:
 
-   ```shell
+   ```bash
    git clone https://github.com/tiktok/sparo.git
    ```
 
 3. Install the dependencies
 
-   ```shell
+   ```bash
    cd sparo
    rush install
    ```
 
 4. Build all projects
 
-   ```shell
+   ```bash
    rush build
    ```
 
 How to invoke your locally build `sparo` command:
 
-```shell
+```bash
 cd apps/sparo
 node lib/start.js
 ```

From 16beb15473ff13911414ad439c0c19fa3285825c Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 1 Mar 2024 00:58:10 -0800
Subject: [PATCH 5/5] Finally fix the problem where ```shell was not
 highlighted correctly

---
 apps/website/README.md                           |  8 ++++----
 apps/website/docs/index.md                       |  6 +++---
 apps/website/docs/pages/guide/getting_started.md |  8 ++++----
 apps/website/docs/pages/guide/sparo_profiles.md  |  8 ++++----
 apps/website/docs/pages/reference/security.md    |  4 ++--
 apps/website/docs/pages/support/contributing.md  | 10 +++++-----
 apps/website/docusaurus.config.js                |  5 ++++-
 apps/website/package.json                        |  3 ++-
 common/config/rush/pnpm-lock.yaml                |  5 ++++-
 9 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/apps/website/README.md b/apps/website/README.md
index dd57c79..281a505 100644
--- a/apps/website/README.md
+++ b/apps/website/README.md
@@ -6,14 +6,14 @@ This is the [Docusaurus](https://docusaurus.io/) project for the Sparo website.
 
 1. Install the monorepo dependencies using [RushJS](https://rushjs.io/):
 
-   ```bash
+   ```shell
    rush install
    rush build
    ```
 
 2. Launch the local development server:
 
-   ```bash
+   ```shell
    cd apps/website
    rushx start
    ```
@@ -33,14 +33,14 @@ Notes:
 
 1. If you will manually copy the files to a server, you can build the **apps/sparo/build** folder like this:
 
-   ```bash
+   ```shell
    cd apps/website
    rushx build
    ```
 
 2. To automatically deploy to GitHub Pages (as an administrator):
 
-   ```bash
+   ```shell
    # If you are using HTTPS authentication for GitHub:
    cd apps/website
    GIT_USER=<Your GitHub username> rushx deploy
diff --git a/apps/website/docs/index.md b/apps/website/docs/index.md
index 924221b..7f7c520 100644
--- a/apps/website/docs/index.md
+++ b/apps/website/docs/index.md
@@ -48,7 +48,7 @@ Try out Sparo in 5 easy steps:
 
 2. Clone your [RushJS](https://rushjs.io/) monorepo:
 
-   ```bash
+   ```shell
    sparo clone https://github.com/my-company/my-monorepo.git
    ```
 
@@ -76,7 +76,7 @@ Try out Sparo in 5 easy steps:
 
 4. Check out your Sparo profile:
 
-   ```bash
+   ```shell
    sparo checkout --profile my-team
    ```
 
@@ -84,7 +84,7 @@ Try out Sparo in 5 easy steps:
 
    Examples:
 
-   ```bash
+   ```shell
    sparo pull
 
    sparo commit -m "Example command"
diff --git a/apps/website/docs/pages/guide/getting_started.md b/apps/website/docs/pages/guide/getting_started.md
index e0fe6f7..4de21b8 100644
--- a/apps/website/docs/pages/guide/getting_started.md
+++ b/apps/website/docs/pages/guide/getting_started.md
@@ -19,7 +19,7 @@ Many Git optimizations are relatively new and not available in older versions of
 
 Clone your [RushJS](https://rushjs.io/) monorepo:
 
-```bash
+```shell
 sparo clone https://github.com/my-company/my-monorepo.git
 ```
 
@@ -64,7 +64,7 @@ The `--to` [project selector](https://rushjs.io/pages/developer/selecting_subset
 The `--profile` parameter can be included with `sparo checkout` (and in the future also `sparo clone` and `sparo pull`).  This parameter specifies the name of the JSON file to be selected.  You can also combine multiple profiles (`sparo checkout --profile p1 --profile p2`), in which case the union of their selections will be used.  (Combining profiles is an advanced scenario, but useful for example if your pull request will impact sets of projects belonging to multiple teams.)
 
 **Sparse checkout based on common/sparo-profiles/my-team.json**
-```bash
+```shell
 sparo checkout --profile my-team
 ```
 
@@ -75,7 +75,7 @@ sparo checkout --profile my-team
 - To checkout just the skeleton (returning to the initial state from Step 1 where no profile is chosen yet), specify `--no-profile` instead of `--profile NAME`.
 
 - To add more profiles, combining with your existing selection, use `--add-profile NAME` instead of `--profile NAME`.  For example, these two commands produce the same result as `sparo checkout --profile p1 --profile p2`:
-  ```bash
+  ```shell
   sparo checkout --profile p1
   sparo checkout --add-profile p2
   ```
@@ -86,7 +86,7 @@ For everyday work, consider choosing [mirrored subcommands](../commands/overview
 
 Examples:
 
-```bash
+```shell
 sparo pull
 
 sparo commit -m "Example command"
diff --git a/apps/website/docs/pages/guide/sparo_profiles.md b/apps/website/docs/pages/guide/sparo_profiles.md
index 9e3f9b5..474a6a2 100644
--- a/apps/website/docs/pages/guide/sparo_profiles.md
+++ b/apps/website/docs/pages/guide/sparo_profiles.md
@@ -67,7 +67,7 @@ You an add JSON comments to your profile config files.  In a large shared codeba
 
 The simple way to combine profiles is to specify `--profile` multiple times.  For example:
 
-```bash
+```sh
 # Check out the union of profiles team-a.json, team-b.json, team-c.json
 # NOTE: This will replace whatever profile selection was already checked out.
 sparo checkout --profile team-a --profile team-b --profile team-c
@@ -75,7 +75,7 @@ sparo checkout --profile team-a --profile team-b --profile team-c
 
 You can also use `--add-profile` to incrementally combine them.  For example:
 
-```bash
+```shell
 # These three commands are equivalent to the above command.
 sparo checkout --profile team-a
 sparo checkout --add-profile team-b
@@ -84,7 +84,7 @@ sparo checkout --add-profile team-c
 
 How to checkout no profile at all? That is, how to return to the initial state of a clean `sparo clone` that only includes the [skeleton](../reference/skeleton_folders.md) folders?  If `--profile` is entirely omitted, then `sparo checkout` will preserve the existing profile selection.  Instead, the `--no-profile` parameter is needed:
 
-```bash
+```shell
 # NOT IMPLEMENTED YET - check out just the skeleton folders
 # without applying any profiles
 sparo checkout --no-profile
@@ -95,7 +95,7 @@ sparo checkout --no-profile
 
 Users can discover available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
 
-```bash
+```shell
 # Suppose you need to make a fix for the "example-app" project.
 
 # Which sparse checkout profiles include the "example-app" project?
diff --git a/apps/website/docs/pages/reference/security.md b/apps/website/docs/pages/reference/security.md
index 3761c25..6b20273 100644
--- a/apps/website/docs/pages/reference/security.md
+++ b/apps/website/docs/pages/reference/security.md
@@ -48,7 +48,7 @@ And of course, if an explicit target folder is specified using `git clone https:
 
 Shell interpreters commonly transform expressions involving special characters such as `$`, `%`, `(`, etc.  For example:
 
-```bash
+```shell
 # Problem: Bash would replace "$project" with the value of
 # the environment variable whose name is "project".
 git clone https://github.com/example/project.git $project
@@ -56,7 +56,7 @@ git clone https://github.com/example/project.git $project
 
 This requires escaping:
 
-```bash
+```shell
 # This backslash escape ensures that a literal dollar sign
 # is included in the created folder name:
 git clone https://github.com/example/project.git \$project
diff --git a/apps/website/docs/pages/support/contributing.md b/apps/website/docs/pages/support/contributing.md
index e4332a1..0446d60 100644
--- a/apps/website/docs/pages/support/contributing.md
+++ b/apps/website/docs/pages/support/contributing.md
@@ -6,32 +6,32 @@ Building the projects in this monorepo:
 
 1. Install the [RushJS](https://rushjs.io/) tool:
 
-   ```bash
+   ```shell
    npm install -g @microsoft/rush
    ```
 
 2. Clone the repo:
 
-   ```bash
+   ```shell
    git clone https://github.com/tiktok/sparo.git
    ```
 
 3. Install the dependencies
 
-   ```bash
+   ```shell
    cd sparo
    rush install
    ```
 
 4. Build all projects
 
-   ```bash
+   ```shell
    rush build
    ```
 
 How to invoke your locally build `sparo` command:
 
-```bash
+```shell
 cd apps/sparo
 node lib/start.js
 ```
diff --git a/apps/website/docusaurus.config.js b/apps/website/docusaurus.config.js
index a92d16d..54d295c 100644
--- a/apps/website/docusaurus.config.js
+++ b/apps/website/docusaurus.config.js
@@ -119,7 +119,10 @@ const config = {
       },
       prism: {
         theme: prismThemes.github,
-        darkTheme: prismThemes.dracula
+        darkTheme: prismThemes.dracula,
+        // Docusaurus's small set of Markdown syntax highlighting languages:
+        // https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages
+        additionalLanguages: ['bash', 'batch', 'javascript', 'json', 'powershell', 'typescript']
       }
     })
 };
diff --git a/apps/website/package.json b/apps/website/package.json
index f260adf..9d1ce21 100644
--- a/apps/website/package.json
+++ b/apps/website/package.json
@@ -35,7 +35,8 @@
     "@docusaurus/types": "3.1.1",
     "@types/react": "~18.2.59",
     "@types/react-dom": "~18.2.19",
-    "typescript": "~5.3.3"
+    "typescript": "~5.3.3",
+    "prismjs": "~1.29.0"
   },
   "browserslist": {
     "production": [
diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
index e6b227d..8761d6a 100644
--- a/common/config/rush/pnpm-lock.yaml
+++ b/common/config/rush/pnpm-lock.yaml
@@ -142,6 +142,9 @@ importers:
       '@types/react-dom':
         specifier: ~18.2.19
         version: 18.2.19
+      prismjs:
+        specifier: ~1.29.0
+        version: 1.29.0
       typescript:
         specifier: ~5.3.3
         version: 5.3.3
@@ -10020,7 +10023,6 @@ packages:
   /prismjs@1.29.0:
     resolution: {integrity: sha512-Kx/1w86q/epKcmte75LNrEoT+lX8pBpavuAbvJWRXar7Hz8jrtF+e3vY751p0R8H9HdArwaCTNDDzHg/ScJK1Q==}
     engines: {node: '>=6'}
-    dev: false
 
   /process-nextick-args@2.0.1:
     resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==}
@@ -12275,6 +12277,7 @@ time:
   /inversify@6.0.2: '2023-10-20T23:35:39.918Z'
   /lunr@2.3.9: '2020-08-19T20:30:07.948Z'
   /prism-react-renderer@2.3.1: '2023-12-18T14:23:38.265Z'
+  /prismjs@1.29.0: '2022-08-23T10:42:14.395Z'
   /react-dom@18.2.0: '2022-06-14T19:46:48.370Z'
   /react@18.2.0: '2022-06-14T19:46:38.369Z'
   /reflect-metadata@0.2.1: '2023-12-14T18:54:20.669Z'